@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/commands/session.d.ts

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

package/dist/commands/session.js

@@ -0,0 +1,109 @@
+import { parseJsonObject, readNonNegativeInt } from "../cli-values.js";
+import { parseJsonArray } from "../command-support.js";
+import { addSessionOutput, addSessionStatus, getSessionUsage, startSession, updateSessionStep } from "../session.js";
+import { readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { Command } from "commander";
+function parseStringArray(value) {
+    const parsed = parseJsonArray(value);
+    const labels = parsed
+        .map((entry) => typeof entry === "string" ? entry.trim() : "")
+        .filter(Boolean);
+    if (labels.length !== parsed.length || labels.length === 0) {
+        throw new OxygenError("invalid_session", "Session steps must be a non-empty JSON array of strings.", {
+            exitCode: 1,
+        });
+    }
+    return labels;
+}
+function normalizeSessionStepStatus(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized === "pending"
+        || normalized === "running"
+        || normalized === "completed"
+        || normalized === "error"
+        || normalized === "skipped") {
+        return normalized;
+    }
+    throw new OxygenError("invalid_session_status", "Session status must be pending, running, completed, error, or skipped.", {
+        details: { status: value },
+        exitCode: 1,
+    });
+}
+export function registerSessionFamily(program, handleAsyncAction) {
+    program
+        .command("session")
+        .description("Local agent session plan and output commands.")
+        .addCommand(new Command("start")
+        .description("Start a local Oxygen agent session or update a step.")
+        .option("--steps <json>", "JSON array of step labels.")
+        .option("--user-prompt <text>", "Original user request for local session context.")
+        .option("--update <index>", "Update a step index instead of replacing the plan.")
+        .option("--status <status>", "Step status: pending, running, completed, error, or skipped.")
+        .option("--session-id <id>", "Session id to update. Defaults to the current session.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        // skipcq: JS-0116 — async Promise-wraps the synchronous session helpers to satisfy handleAsyncAction's Promise<unknown> action
+        await handleAsyncAction("session start", options, async () => {
+            const updateIndex = readNonNegativeInt(options.update);
+            if (updateIndex !== undefined) {
+                return updateSessionStep({
+                    sessionId: readOption(options.sessionId),
+                    index: updateIndex,
+                    status: normalizeSessionStepStatus(options.status),
+                });
+            }
+            if (!options.steps) {
+                throw new OxygenError("invalid_session", "Pass --steps as a JSON array of labels.", {
+                    exitCode: 1,
+                });
+            }
+            return startSession({
+                steps: parseStringArray(options.steps),
+                userPrompt: readOption(options.userPrompt),
+            });
+        });
+    }))
+        .addCommand(new Command("status")
+        .description("Attach a live status message to the current local session.")
+        .requiredOption("--message <message>", "Status message.")
+        .option("--step-index <index>", "Optional step index. Defaults to the running step.")
+        .option("--session-id <id>", "Session id. Defaults to the current session.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        // skipcq: JS-0116 — async Promise-wraps the synchronous addSessionStatus helper to satisfy handleAsyncAction's Promise<unknown> action
+        await handleAsyncAction("session status", options, async () => addSessionStatus({
+            sessionId: readOption(options.sessionId),
+            message: options.message,
+            stepIndex: readNonNegativeInt(options.stepIndex) ?? null,
+        }));
+    }))
+        .addCommand(new Command("output")
+        .description("Register a local session output file or table.")
+        .option("--csv <path>", "CSV output path.")
+        .option("--file <path>", "Generic output file path.")
+        .option("--table <table>", "Workspace table id or slug.")
+        .option("--label <label>", "Human-readable output label.")
+        .option("--meta-json <json>", "Optional JSON metadata object.")
+        .option("--session-id <id>", "Session id. Defaults to the current session.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        // skipcq: JS-0116 — async Promise-wraps the synchronous addSessionOutput helper to satisfy handleAsyncAction's Promise<unknown> action
+        await handleAsyncAction("session output", options, async () => addSessionOutput({
+            sessionId: readOption(options.sessionId),
+            csv: readOption(options.csv),
+            file: readOption(options.file),
+            table: readOption(options.table),
+            label: readOption(options.label),
+            meta: options.metaJson ? parseJsonObject(options.metaJson) : null,
+        }));
+    }))
+        .addCommand(new Command("usage")
+        .description("Summarize the current local session. Org credit usage is available through billing usage.")
+        .option("--session-id <id>", "Session id. Defaults to the current session.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        // skipcq: JS-0116 — async Promise-wraps the synchronous getSessionUsage helper to satisfy handleAsyncAction's Promise<unknown> action
+        await handleAsyncAction("session usage", options, async () => getSessionUsage({ sessionId: readOption(options.sessionId) }));
+    }));
+}

package/dist/commands/signals.d.ts

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

package/dist/commands/signals.js

@@ -0,0 +1,289 @@
+import { parseJsonObject, readPositiveInt } from "../cli-values.js";
+import { CADENCE_FLAG_DESCRIPTION, buildCrmLeadsTodayPath, buildCrmSignalRecordBody, readCsvOption, readFileIfPresent, readPositiveNumber, 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 buildSignalsListPath(options) {
+    const params = new URLSearchParams();
+    if (options.types)
+        params.set("types", options.types);
+    if (options.since)
+        params.set("since", options.since);
+    if (options.limit)
+        params.set("limit", options.limit);
+    const query = params.toString();
+    return query ? `/api/cli/signals?${query}` : "/api/cli/signals";
+}
+function readSignalsSearchPlanBody(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 = readSignalSearchFilters(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) } : {}),
+        family: options.family,
+        ...(readOption(options.scope) ? { scope: readOption(options.scope) } : {}),
+        ...(targetCount !== undefined ? { target_count: targetCount } : {}),
+        ...(filters ? { filters } : {}),
+        ...(options.estimate ? { estimate: true } : {}),
+    };
+}
+function readSignalsSearchRunBody(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;
+    // A post search needs no prompt: its --keywords and filters are the plan,
+    // as they are for the free preview (the server names the table after them).
+    const postSearchFilters = !prompt && !plan && (readOption(options.source) ?? readOption(options.family)) === "linkedin_posts"
+        ? readSignalSearchFilters(options)
+        : null;
+    const postSearch = Array.isArray(postSearchFilters?.keywords) && postSearchFilters.keywords.length > 0;
+    if (!prompt && !plan && !postSearch) {
+        throw new OxygenError("invalid_request", "Pass --prompt or --plan-json (linkedin_posts needs only --keywords).", { exitCode: 1 });
+    }
+    if (prompt && !readOption(options.family)) {
+        throw new OxygenError("invalid_request", "Pass --family when planning from --prompt.", { exitCode: 1 });
+    }
+    const maxPages = readPositiveInt(options.maxPages);
+    const maxCredits = readPositiveNumber(options.maxCredits);
+    const targetCount = readPositiveInt(options.targetCount);
+    const maxCreditsPerCycle = readPositiveNumber(options.maxCreditsPerCycle);
+    const maxRowsPerCycle = readPositiveInt(options.maxRowsPerCycle);
+    // Filters describe a prompt that is being (re)planned. A saved plan already
+    // froze its own, so they are never re-sent with one; typed alongside a saved
+    // plan they are refused, because dropping them would run live unfiltered. A
+    // prompt-less linkedin_posts search (no plan) is planned from its filters.
+    const typedFilters = readSignalSearchFilters(options);
+    if (plan && !prompt && typedFilters) {
+        throw new OxygenError("invalid_request", `A saved plan keeps the filters it was planned with, so ${Object.keys(typedFilters).join(", ")} cannot be added to --plan-json. `
+            + "Re-plan with oxygen signals search plan --prompt <goal> --family <family> and the filter flags, or pass them to signals search run --prompt.", { exitCode: 1 });
+    }
+    const filters = prompt ? typedFilters : postSearchFilters;
+    return {
+        ...(readOption(options.source) ? { source: readOption(options.source) } : {}),
+        ...(prompt ? { prompt } : {}),
+        ...(plan ? { plan } : {}),
+        ...(readOption(options.family) ? { family: readOption(options.family) } : {}),
+        ...(readOption(options.scope) ? { scope: readOption(options.scope) } : {}),
+        ...(readOption(options.routeId) ? { route_id: readOption(options.routeId) } : {}),
+        ...(readOption(options.toolId) ? { tool_id: readOption(options.toolId) } : {}),
+        ...(readOption(options.table) ? { table: readOption(options.table) } : {}),
+        ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+        ...(readOption(options.upsertKey) ? { upsert_key: readOption(options.upsertKey) } : {}),
+        ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
+        ...(maxPages !== undefined ? { max_pages: maxPages } : {}),
+        ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+        ...(targetCount !== undefined ? { target_count: targetCount } : {}),
+        ...(filters ? { filters } : {}),
+        ...(options.approved ? { approved: true } : {}),
+        ...(options.bindFeed ? { bind_feed: true } : {}),
+        ...(readOption(options.every) ? { every: readOption(options.every) } : {}),
+        ...(maxCreditsPerCycle !== undefined ? { max_credits_per_cycle: maxCreditsPerCycle } : {}),
+        ...(maxRowsPerCycle !== undefined ? { max_rows_per_cycle: maxRowsPerCycle } : {}),
+        ...(readOption(options.credentialMode) ? { credential_mode: readOption(options.credentialMode) } : {}),
+    };
+}
+// SignalSearchFilters mirror (structural — the server validates every field and
+// rejects unknown values by name). --filters-json wins per top-level path so an
+// agent can pass a precise object while still using flags for the rest.
+function readSignalSearchFilters(options) {
+    const filters = {};
+    const keywords = readCsvOption(options.keywords);
+    if (keywords.length > 0)
+        filters.keywords = keywords;
+    const allKeywords = readCsvOption(options.allKeywords);
+    if (allKeywords.length > 0)
+        filters.all_keywords = allKeywords;
+    const excludeKeywords = readCsvOption(options.excludeKeywords);
+    if (excludeKeywords.length > 0)
+        filters.exclude_keywords = excludeKeywords;
+    const sort = readOption(options.sort);
+    if (sort)
+        filters.sort_by = sort;
+    const minReactions = readOption(options.minReactions);
+    if (minReactions)
+        filters.min_reactions = minReactions;
+    const postedBy = readOption(options.postedBy);
+    if (postedBy)
+        filters.posted_by = postedBy;
+    const aiFilter = readOption(options.aiFilter);
+    if (aiFilter)
+        filters.ai_filter = aiFilter;
+    const countries = readCsvOption(options.countries);
+    if (countries.length > 0)
+        filters.countries = countries;
+    const location = readOption(options.location);
+    if (location)
+        filters.location = location;
+    const lastDays = readPositiveInt(options.lastDays);
+    if (lastDays !== undefined)
+        filters.last_days = lastDays;
+    const domains = readCsvOption(options.domains);
+    if (domains.length > 0)
+        filters.domains = domains;
+    const fundingTypes = readCsvOption(options.fundingTypes);
+    if (fundingTypes.length > 0)
+        filters.funding_types = fundingTypes;
+    const categories = readCsvOption(options.categories);
+    if (categories.length > 0)
+        filters.categories = categories;
+    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;
+}
+export function registerSignalsFamily(program, handleAsyncAction) {
+    program
+        .command("signals")
+        .description("The Signals primitive: record intent events, read the event feed and type registry, and rank leads with signals leads-today. Tag a registered type with `oxygen tags attach signal_type <type> --tags <labels>`.")
+        .addCommand(new Command("list")
+        .description("List the raw GTM signal-event feed newest-first (website_visit / profile_view / post_reaction / new_follower), each resolved onto the person it attached to. Read-only.")
+        .option("--types <types>", "Comma-separated signal types to include. Defaults to all four.")
+        .option("--since <days>", "Look-back window in days. Defaults to 7; your plan's maximum (30 on free, up to 365) is in `oxygen limits show`.")
+        .option("--limit <limit>", "Maximum events to return. Defaults to 25; your plan's maximum (100 on free, up to 1,000) is in `oxygen limits show`.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("signals list", options, () => requestOxygen(buildSignalsListPath(options)));
+    }))
+        .addCommand(new Command("registry")
+        .description("Show registered signal types with intent weight, capture status, and workspace tags. Tag a type with `oxygen tags attach signal_type <type> --tags <labels>`. Read-only.")
+        .option("--tag <tag>", "Only signal types carrying this workspace tag; use tags attach to set it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("signals registry", options, () => requestOxygen(`/api/cli/signals/registry${options.tag ? `?tag=${encodeURIComponent(options.tag)}` : ""}`));
+    }))
+        .addCommand(new Command("record")
+        .description("Record one inbound GTM signal (website_visit, profile_view, post_engager, new_follower). Internal write — free, no approval. Idempotent on --external-event-id.")
+        .requiredOption("--event <event>", "Signal event: website_visit | profile_view | post_engager | new_follower.")
+        .option("--external-event-id <id>", "Stable provider event id (redelivery/idempotency guard). Derived from --session-id when omitted.")
+        .option("--email <email>", "Person email (identity).")
+        .option("--linkedin-url <url>", "Person LinkedIn URL (identity when no email).")
+        .option("--company-domain <domain>", "Company domain for the company assert.")
+        .option("--company-name <name>", "Company name.")
+        .option("--first-name <name>", "Person first name.")
+        .option("--last-name <name>", "Person last name.")
+        .option("--page-url <url>", "Page the signal fired on (website visit).")
+        .option("--session-id <id>", "Provider session id (provenance + idempotency).")
+        .option("--payload-json <json>", "JSON object merged into the signal payload (wins over the flags above).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("signals record", options, () => requestOxygen("/api/cli/signals", {
+            method: "POST",
+            body: buildCrmSignalRecordBody(options),
+        }));
+    }))
+        .addCommand(new Command("leads-today")
+        .description("List people to contact today, ranked by their most recent GTM intent signal. When the output has rankedBy, equal signals are ordered by the company's ICP fit (see each lead's fit). Do-not-contact filtering is best-effort (email-only leads surface unchecked).")
+        .option("--limit <limit>", "Maximum leads to return. Defaults to 25, max 100.")
+        .option("--within-days <days>", "Signal look-back window in days. Defaults to 7, max 30.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("signals leads-today", options, () => requestOxygen(buildCrmLeadsTodayPath(options)));
+    }))
+        .addCommand(new Command("search")
+        .description("Source EXTERNAL market signals into a table: hiring, technology adoption, funding, acquisitions, news, and public LinkedIn posts by keyword (linkedin_posts). This is the sourcing half of Signals — `signals list` reads the events already captured for your workspace.")
+        .addCommand(new Command("plan")
+        .description("Compile a signal-sourcing request into ordered provider routes without provider calls: the chain, per-route applied/dropped filters, credit estimate, table blueprint, and whether the route can be kept LIVE on a cadence. Free.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt). The --prompt flag wins if both are given.")
+        .option("--prompt <text-or-file>", "Signal-sourcing prompt, or a path to a prompt file.")
+        .requiredOption("--family <family>", "Signal family: hiring, tech, funding, acquisition, news, job_change, or linkedin_posts (public LinkedIn posts matching keywords).")
+        .option("--scope <scope>", "market (discover new companies) or watch_list (track companies you name via --domains). Defaults per family.")
+        .option("--target-count <n>", "Desired row count for routing and estimates. linkedin_posts: posts fetched per keyword before the AI filter (default 100), which also sets the Why it matches credit ceiling (1.5 per fetched post).")
+        .option("--keywords <csv>", "Comma-separated keywords, e.g. job titles for hiring or technology names for tech. For linkedin_posts: a post must mention AT LEAST ONE of these (each is its own search, at most 5).")
+        .option("--all-keywords <csv>", "linkedin_posts: a post must mention ALL of these.")
+        .option("--exclude-keywords <csv>", "linkedin_posts: drop posts that mention any of these, e.g. hiring.")
+        .option("--sort <order>", "linkedin_posts: recent (latest first), relevance (top match) or top (most reactions first).")
+        .option("--min-reactions <n>", "linkedin_posts: keep only posts with at least this many reactions.")
+        .option("--posted-by <url>", "linkedin_posts: only posts by this LinkedIn profile or company page URL.")
+        .option("--ai-filter <text>", "linkedin_posts: keep only posts an AI classifier judges to match this description (at most 500 characters). Free, unless the plan returns an ai_filter block: that block names the family it covers and its credits_per_item.")
+        .option("--countries <csv>", "Comma-separated ISO 3166-1 alpha-2 country codes.")
+        .option("--location <text>", "Country or state NAME for providers that filter on a location string.")
+        .option("--last-days <n>", "Only signals from the last N days (1-3650).")
+        .option("--domains <csv>", "Comma-separated company domains. Required for watch_list scope.")
+        .option("--funding-types <csv>", "Comma-separated funding types for the funding family.")
+        .option("--categories <csv>", "Comma-separated provider event categories.")
+        .option("--filters-json <json-or-file>", "Filters JSON inline or a path to a JSON file; wins over individual flags per top-level filter path.")
+        .option("--estimate", "Run the free server-side preflight pass: resolves provider enum values and, where a provider publishes one, a free match count (zero credits).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (promptArg, options) => {
+        await handleAsyncAction("signals search plan", options, () => requestOxygen("/api/cli/signals/search/plan", {
+            method: "POST",
+            body: readSignalsSearchPlanBody(options, promptArg),
+        }));
+    }))
+        .addCommand(new Command("preview")
+        .description("Preview public LinkedIn posts for free on Oxygen's Managed rail (family linkedin_posts): up to 25 per keyword, with author, engagement and the --ai-filter applied. Nothing is created or charged. Each --keywords entry is one search against a small hourly search budget shared across OXYGEN. After repricing, own-key previews are paused because they would make billable Up2Data calls without a credit approval; use Managed for the preview or quote a direct scraper tool run. Then signals search run --family linkedin_posts with the same flags creates the table.")
+        .option("--family <family>", "linkedin_posts, the only family with a free preview.", "linkedin_posts")
+        .option("--keywords <csv>", "A post must mention AT LEAST ONE of these (each is its own search, at most 5).")
+        .option("--all-keywords <csv>", "A post must mention ALL of these.")
+        .option("--exclude-keywords <csv>", "Drop posts that mention any of these, e.g. hiring.")
+        .option("--last-days <n>", "Only posts from the last N days: 1 = 24 hours, up to 7 = week, up to 30 = month.")
+        .option("--sort <order>", "recent (latest first), relevance (top match) or top (most reactions first).")
+        .option("--min-reactions <n>", "Keep only posts with at least this many reactions.")
+        .option("--posted-by <url>", "Only posts by this LinkedIn profile or company page URL.")
+        .option("--ai-filter <text>", "Keep only posts an AI classifier judges to match this description (at most 500 characters). Free, and each kept post shows why it matches (ai_filter_reason).")
+        .option("--filters-json <json-or-file>", "Filters JSON inline or a path to a JSON file; wins over individual flags per top-level filter path.")
+        .option("--credential-mode <mode>", "managed (default): Oxygen's key. user_api_key: your own Up2Data key saved in Connections, which spends your Up2Data searches instead of the shared hourly budget.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("signals search preview", options, () => requestOxygen("/api/cli/signals/search/preview", {
+            method: "POST",
+            body: {
+                family: options.family,
+                filters: readSignalSearchFilters(options) ?? {},
+                ...(readOption(options.credentialMode) ? { credential_mode: readOption(options.credentialMode) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("run")
+        .description("Return a dry-run request or queue a live signal-search ingestion run. Live requires --approved and --max-credits (linkedin_posts is free, --approved only, unless --ai-filter is set: its Why it matches reasons cost credits per kept post, quoted by the dry run, or none on the workspace's own OpenRouter key, and a dry-run ai_filter quote prices the filter itself). Add --bind-feed --every to also bind a pull feed to the same table in the same call, so the table keeps refilling on a cadence.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt); requires --family. The --prompt flag wins if both are given.")
+        .option("--prompt <text-or-file>", "Signal-sourcing prompt, or a path to a prompt file. Requires --family.")
+        .option("--plan-json <json-or-file>", "Plan JSON returned by signals search plan, or a path to a JSON file.")
+        .option("--source <linkedin_posts>", "Run the native post-search lane using --filters-json or --keywords; no prompt needed.")
+        .option("--family <family>", "Signal family when planning from --prompt: hiring, tech, funding, acquisition, news, job_change, or linkedin_posts.")
+        .option("--scope <scope>", "market or watch_list when planning from --prompt.")
+        .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 one from the plan blueprint.")
+        .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 <key>", "Column key used for live upsert. Defaults to the plan upsert key.")
+        .option("--mode <mode>", "dry_run or live. Defaults to dry_run.")
+        .option("--max-pages <n>", "Maximum provider pages to ingest. Defaults to 1.")
+        .option("--max-credits <n>", "Credit ceiling for live runs. linkedin_posts needs it only when the dry run quotes credits for the --ai-filter reasons or the filter itself.")
+        .option("--target-count <n>", "Desired row count when planning. linkedin_posts: posts fetched per keyword before the AI filter (default 100); with --ai-filter the Why it matches ceiling is 1.5 credits per fetched post, but only kept posts are charged.")
+        .option("--keywords <csv>", "Comma-separated keywords when planning from --prompt. For linkedin_posts: a post must mention at least one.")
+        .option("--all-keywords <csv>", "linkedin_posts: a post must mention ALL of these, when planning from --prompt.")
+        .option("--exclude-keywords <csv>", "linkedin_posts: drop posts that mention any of these, when planning from --prompt.")
+        .option("--sort <order>", "linkedin_posts: recent, relevance or top, when planning from --prompt.")
+        .option("--min-reactions <n>", "linkedin_posts: at least this many reactions, when planning from --prompt.")
+        .option("--posted-by <url>", "linkedin_posts: only posts by this profile or company page, when planning from --prompt.")
+        .option("--ai-filter <text>", "linkedin_posts: keep only posts an AI classifier judges to match this description (at most 500 characters), when planning from --prompt. Other families only where the plan returns an ai_filter block.")
+        .option("--countries <csv>", "Comma-separated ISO 3166-1 alpha-2 country codes when planning from --prompt.")
+        .option("--location <text>", "Country or state NAME when planning from --prompt.")
+        .option("--last-days <n>", "Only signals from the last N days when planning from --prompt.")
+        .option("--domains <csv>", "Comma-separated company domains when planning from --prompt.")
+        .option("--funding-types <csv>", "Comma-separated funding types when planning from --prompt.")
+        .option("--categories <csv>", "Comma-separated provider event categories when planning from --prompt.")
+        .option("--filters-json <json-or-file>", "Filters JSON inline or a path to a JSON file when planning from --prompt.")
+        .option("--approved", "Required for live runs after inspecting dry-run output.")
+        .option("--bind-feed", "Also bind a pull feed to the target table so it keeps refilling. Requires --every; refused when the route cannot pull incrementally.")
+        .option("--every <sugar>", CADENCE_FLAG_DESCRIPTION)
+        .option("--max-credits-per-cycle <n>", "Credit ceiling PER sync cycle for the bound feed.")
+        .option("--max-rows-per-cycle <n>", "Advisory row ceiling per sync cycle for the bound feed.")
+        .option("--credential-mode <mode>", "linkedin_posts: managed (default) or user_api_key to search on your own Up2Data key saved in Connections, billed by Up2Data. The table's bound feed keeps using it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (promptArg, options) => {
+        await handleAsyncAction("signals search run", options, () => requestOxygen("/api/cli/signals/search/run", {
+            method: "POST",
+            body: readSignalsSearchRunBody(options, promptArg),
+        }));
+    })));
+}

package/dist/commands/signup-leads.d.ts

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

package/dist/commands/signup-leads.js

@@ -0,0 +1,46 @@
+import { readPositiveInt } from "../cli-values.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+export function registerSignupLeadsFamily(program, handleAsyncAction) {
+    program
+        .command("signup-leads")
+        .description("Signup lead delivery queue commands.")
+        .addCommand(new Command("deliveries")
+        .description("Inspect and retry durable signup lead webhook deliveries.")
+        .addCommand(new Command("list")
+        .description("List signup lead webhook deliveries for the current organization.")
+        .option("--status <status>", "Filter by pending, running, succeeded, skipped, retrying, failed, or dead.")
+        .option("--limit <n>", "Maximum deliveries to return. Defaults to 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("signup-leads deliveries list", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            const limit = readPositiveInt(options.limit);
+            if (status)
+                params.set("status", status);
+            if (limit)
+                params.set("limit", String(limit));
+            const suffix = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/signup-leads/deliveries${suffix}`);
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Get one signup lead webhook delivery by delivery id or event id.")
+        .argument("<id>", "Delivery id or event id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("signup-leads deliveries get", options, () => requestOxygen(`/api/cli/signup-leads/deliveries?id=${encodeURIComponent(id)}`));
+    }))
+        .addCommand(new Command("retry")
+        .description("Retry one failed signup lead webhook delivery.")
+        .argument("<id>", "Delivery id or event id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("signup-leads deliveries retry", options, () => requestOxygen("/api/cli/signup-leads/deliveries", {
+            method: "POST",
+            body: { id },
+        }));
+    })));
+}

package/dist/commands/skills.d.ts

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

package/dist/commands/skills.js

@@ -0,0 +1,50 @@
+import { doctorAgentSkills, getAgentSkill, installAgentSkills, listAgentSkills, searchAgentSkills } from "../skills.js";
+import { Command } from "commander";
+export function registerSkillsFamily(program, handleAsyncAction) {
+    program
+        .command("skills")
+        .description("Find and install Oxygen guides, or create and import private workspace skills with skills workspace.")
+        .addCommand(new Command("list")
+        .description("List Oxygen agent skills available from the hosted skill index.")
+        .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("skills list", options, () => listAgentSkills(options));
+    }))
+        .addCommand(new Command("search")
+        .description("Find a bounded set of Oxygen skills and matching documents from an outcome.")
+        .argument("<query...>", "Outcome, primitive, provider, or operating task.")
+        .option("--limit <n>", "Maximum results (default 5, max 10).")
+        .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (queryParts, options) => {
+        await handleAsyncAction("skills search", options, () => searchAgentSkills(queryParts.join(" "), options));
+    }))
+        .addCommand(new Command("get")
+        .description("Hydrate one exact Oxygen skill entrypoint and its document index.")
+        .argument("<skill-name>", "Exact name returned by skills search.")
+        .option("--file <path>", "Read one manifest-listed supporting file relative to the selected skill.")
+        .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (skillName, options) => {
+        await handleAsyncAction("skills get", options, () => getAgentSkill(skillName, options));
+    }))
+        .addCommand(new Command("doctor")
+        .description("Check Oxygen skill index reachability and local installer prerequisites.")
+        .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("skills doctor", options, () => doctorAgentSkills(options));
+    }))
+        .addCommand(new Command("install")
+        .description("Install Oxygen agent skills into local agent skill directories only; uses 0 credits and does not change the Oxygen workspace or call a provider. Also removes retired Oxygen skills it installed earlier.")
+        .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
+        .option("--agents <agents...>", "Space or comma separated agents. Defaults to codex, claude-code, and cursor.")
+        .option("--skill <skill>", "Skill name or '*'. Defaults to '*'.")
+        .option("--project", "Install into the current project instead of global agent scope. A flag with no value: run it from the project directory; a path argument is rejected.")
+        .option("--copy", "Copy skill files instead of symlinking when supported by npx skills. Default on Windows, where symlinks need Developer Mode or admin.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("skills install", options, () => installAgentSkills(options));
+    }));
+}

package/dist/commands/sourcing.d.ts

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

package/dist/commands/sourcing.js

@@ -0,0 +1,27 @@
+import { readFileIfPresent } from "../command-support.js";
+import { requestOxygen } from "../http-client.js";
+import { readOption } from "../util.js";
+import { Command } from "commander";
+export function registerSourcingFamily(program, handleAsyncAction) {
+    program
+        .command("sourcing")
+        .description("Plan account, people, profile, and enrichment-handoff sourcing workflows.")
+        .addCommand(new Command("plan")
+        .description("Classify a sourcing request and recommend provider routes without executing paid tools.")
+        .requiredOption("--prompt <file|text>", "Sourcing prompt text, or a local file path containing the prompt.")
+        .option("--strategy <id>", "Optional strategy id such as account_first_lead_sourcing or known_account_org_chart.")
+        .option("--table <table_id>", "Optional target table id or slug for follow-up commands.")
+        .option("--materialize-preview", "Create a preview table for the plan. Defaults to no table side effect.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("sourcing plan", options, () => requestOxygen("/api/cli/sourcing/plan", {
+            method: "POST",
+            body: {
+                prompt: readFileIfPresent(options.prompt),
+                ...(readOption(options.strategy) ? { strategy: readOption(options.strategy) } : {}),
+                ...(readOption(options.table) ? { target_table_id: readOption(options.table) } : {}),
+                ...(options.materializePreview ? { materialize_preview: true } : {}),
+            },
+        }));
+    }));
+}

package/dist/commands/status.d.ts

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

package/dist/commands/status.js

@@ -0,0 +1,51 @@
+import { defaultApiUrl, loadCredentials } from "../credentials.js";
+import { requestOxygen } from "../http-client.js";
+import { isVersionGreater, isVersionLess } from "@oxygen/shared/semver";
+import { OXYGEN_VERSION } from "@oxygen/shared/version";
+export function registerStatusFamily(program, handleAsyncAction) {
+    program
+        .command("status")
+        .description("Compare the local Oxygen CLI version against the active profile's deployed Oxygen API. Read-only, 0 credits. "
+        + "`compatible` is the field that matters: false means commands are refused until the CLI updates. "
+        + "`in_sync` and `skew` compare reported versions. A CLI may be ahead during a rollout; "
+        + "if the difference persists, share the status SHA with support.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("status", options, async () => {
+            // Resolve the API URL exactly like authenticated commands do: the
+            // active profile (honoring --profile / OXYGEN_PROFILE / OXYGEN_API_URL
+            // overrides), falling back to the default prod URL only when no
+            // credentials are stored. Without this, requestOxygen's
+            // requireAuth:false path skips loadCredentials() and always hits prod,
+            // so `status` reports a different deployment than every other command.
+            const credentials = await loadCredentials();
+            const apiUrl = credentials?.apiUrl ?? defaultApiUrl();
+            const server = await requestOxygen("/api/health", {
+                credentials: credentials ?? { token: "", apiUrl },
+                requireAuth: false,
+                enforceMinimumCliVersion: false,
+            });
+            // Explicit skew semantics: in_sync=false alone forced every ops sweep
+            // to hand-interpret whether a version gap was safe (fleet friction,
+            // recurring since 2026-06-18). `skew` names the direction and
+            // `compatible` answers the only question that matters: is this CLI at
+            // or above the server's enforced minimum?
+            const minimum = server.minimum_cli_version ?? null;
+            return {
+                client_version: OXYGEN_VERSION,
+                api_url: apiUrl,
+                server_version: server.server_version,
+                minimum_cli_version: minimum,
+                sha: server.sha,
+                region: server.region,
+                in_sync: server.server_version === OXYGEN_VERSION,
+                skew: isVersionGreater(OXYGEN_VERSION, server.server_version)
+                    ? "client_ahead"
+                    : isVersionLess(OXYGEN_VERSION, server.server_version)
+                        ? "client_behind"
+                        : "in_sync",
+                compatible: minimum === null || !isVersionLess(OXYGEN_VERSION, minimum),
+            };
+        });
+    });
+}

package/dist/commands/supabase.d.ts

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