@oxygen-agent/cli 1.109.10 → 1.123.0

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation and support, visit https://oxygen-agent.com.
 
-Version: 1.109.10
+Version: 1.123.0

package/dist/http-client.js

@@ -1,6 +1,7 @@
 import { OXYGEN_VERSION, OxygenError } from "@oxygen/shared";
 import { randomUUID } from "node:crypto";
 import { defaultApiUrl, loadCredentials } from "./credentials.js";
+import { resolveCliUpdateGuidance } from "./runtime.js";
 const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 const CLI_COMPATIBILITY_CHECK_TIMEOUT_MS = 5_000;
 const PROD_API_HOSTNAME = "oxygen-agent.com";
@@ -77,13 +78,13 @@ path, options = {}) {
     }
     const envelope = await readEnvelope(response);
     const compatibility = readEnvelopeCompatibility(envelope);
-    assertCliMeetsMinimumApiVersion(compatibility, options);
-    warnIfCliIsOlderThanApi(compatibility.version);
+    assertCliMeetsMinimumApiVersion(compatibility, options, apiUrl);
+    warnIfCliIsOlderThanApi(compatibility.version, apiUrl);
     if (!response.ok || !envelope.ok) {
         const failure = envelope;
         const responseTraceId = response.headers.get("x-oxygen-trace-id") ?? traceId;
         throw new OxygenError(failure.error.code, failure.error.message, {
-            details: withTraceDetails(failure.error.details, responseTraceId, compatibility),
+            details: withTraceDetails(failure.error.details, responseTraceId, compatibility, apiUrl),
             exitCode: response.status >= 500 ? 1 : 1,
         });
     }
@@ -97,8 +98,8 @@ export async function ensureFreshCliForApiUrl(apiUrl, options = {}) {
     if (!compatibility) {
         return;
     }
-    assertCliMeetsMinimumApiVersion(compatibility, {});
-    warnIfCliIsOlderThanApi(compatibility.version);
+    assertCliMeetsMinimumApiVersion(compatibility, {}, apiUrl);
+    warnIfCliIsOlderThanApi(compatibility.version, apiUrl);
     cliCompatibilityCheckKeys.add(checkKey);
 }
 function resolveSelectedOrganization(credentials, explicit) {
@@ -145,14 +146,18 @@ async function readHealthCompatibility(apiUrl, fetchImpl) {
     }
 }
 const staleCliWarningVersions = new Set();
-function warnIfCliIsOlderThanApi(serverVersion) {
-    if (!serverVersion || staleCliWarningVersions.has(serverVersion))
+function warnIfCliIsOlderThanApi(serverVersion, apiUrl) {
+    if (!serverVersion)
         return;
     if (!isVersionGreater(serverVersion, OXYGEN_VERSION))
         return;
-    staleCliWarningVersions.add(serverVersion);
-    process.stderr.write(`[oxygen] CLI version ${OXYGEN_VERSION} is older than Oxygen API version ${serverVersion}. `
-        + "Run `oxygen update` before using operational commands.\n");
+    const guidance = resolveCliUpdateGuidance(apiUrl);
+    const warningKey = `${serverVersion}|${guidance.channel}|${guidance.binaryName}`;
+    if (staleCliWarningVersions.has(warningKey))
+        return;
+    staleCliWarningVersions.add(warningKey);
+    process.stderr.write(`[${guidance.binaryName}] CLI version ${OXYGEN_VERSION} is older than Oxygen API version ${serverVersion}. `
+        + `${guidance.warningInstruction}\n`);
 }
 function isProdApiUrl(apiUrl) {
     try {
@@ -162,18 +167,19 @@ function isProdApiUrl(apiUrl) {
         return false;
     }
 }
-function assertCliMeetsMinimumApiVersion(compatibility, options) {
+function assertCliMeetsMinimumApiVersion(compatibility, options, apiUrl) {
     if (options.enforceMinimumCliVersion === false)
         return;
     const minimumCliVersion = compatibility.minimumCliVersion;
     if (!minimumCliVersion || !isVersionGreater(minimumCliVersion, OXYGEN_VERSION))
         return;
-    throw new OxygenError("cli_update_required", "This Oxygen API requires a newer CLI. Run `oxygen update` before using this command.", {
+    const guidance = resolveCliUpdateGuidance(apiUrl);
+    throw new OxygenError("cli_update_required", `This Oxygen API requires a newer CLI. ${guidance.failureInstruction}`, {
         details: {
             client_version: OXYGEN_VERSION,
             ...(compatibility.version ? { server_version: compatibility.version } : {}),
             minimum_cli_version: minimumCliVersion,
-            cli_update_command: "oxygen update",
+            ...guidance.details,
         },
         exitCode: 1,
     });
@@ -191,7 +197,7 @@ function readEnvelopeCompatibility(envelope) {
     }
     return compatibility;
 }
-function withTraceDetails(details, traceId, compatibility) {
+function withTraceDetails(details, traceId, compatibility, apiUrl) {
     const serverVersion = compatibility.version;
     const fields = {
         trace_id: traceId,
@@ -204,7 +210,7 @@ function withTraceDetails(details, traceId, compatibility) {
     if ((serverVersion && isVersionGreater(serverVersion, OXYGEN_VERSION))
         || (compatibility.minimumCliVersion
             && isVersionGreater(compatibility.minimumCliVersion, OXYGEN_VERSION))) {
-        fields.cli_update_command = "oxygen update";
+        Object.assign(fields, resolveCliUpdateGuidance(apiUrl).details);
     }
     if (details && typeof details === "object" && !Array.isArray(details)) {
         return {

package/dist/index.js

@@ -19,6 +19,7 @@ import { ensureFreshCliForApiUrl, requestOxygen } from "./http-client.js";
 import { runLocalCustomHttpColumn } from "./local-custom-http-column.js";
 import { addSessionOutput, addSessionStatus, getSessionUsage, startSession, updateSessionStep, } from "./session.js";
 import { doctorAgentSkills, installAgentSkills, listAgentSkills, runAutomaticSkillsInstall, } from "./skills.js";
+import { resolveCliBinaryName } from "./runtime.js";
 import { updateCli } from "./update.js";
 const BROWSER_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 const OXYGEN_SPINNER_INTERVAL_MS = 90;
@@ -172,8 +173,9 @@ function readSpecFileBody(path) {
 }
 export function createProgram() {
     const program = new Command();
+    const binaryName = resolveCliBinaryName();
     program
-        .name("oxygen")
+        .name(binaryName)
         .description("CLI/API-first GTM platform for GTM tool and workflow primitives.")
         .version(OXYGEN_VERSION)
         .option("--profile <name>", "Use a stored CLI profile for this command.")
@@ -358,18 +360,54 @@ export function createProgram() {
         .option("--json", "Print a JSON envelope.")
         .action(async (organization, options) => {
         await handleOrgUseAction(organization, options, "orgs select");
+    }))
+        .addCommand(new Command("billing-link")
+        .description("Bill a workspace through another organization you administer.")
+        .requiredOption("--owner <organization>", "Billing owner organization id, Clerk org id, or slug.")
+        .option("--organization <organization>", "Workspace organization to link. Defaults to the active organization.")
+        .option("--organization-id <id>", "Alias for --organization.")
+        .option("--monthly-credit-cap <credits>", "Optional monthly credit cap for this workspace.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("orgs billing-link", options, () => requestOxygen("/api/cli/orgs/billing-link", {
+            method: "POST",
+            body: {
+                billing_owner_organization_id: readOption(options.owner),
+                ...(readOption(options.organization) || readOption(options.organizationId)
+                    ? { organization_id: readOption(options.organization) ?? readOption(options.organizationId) }
+                    : {}),
+                ...(readOption(options.monthlyCreditCap)
+                    ? { monthly_credit_cap: readPositiveNumber(options.monthlyCreditCap) }
+                    : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("billing-unlink")
+        .description("Return a workspace to owning its own billing.")
+        .option("--organization <organization>", "Workspace organization to unlink. Defaults to the active organization.")
+        .option("--organization-id <id>", "Alias for --organization.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("orgs billing-unlink", options, () => requestOxygen("/api/cli/orgs/billing-unlink", {
+            method: "POST",
+            body: {
+                ...(readOption(options.organization) || readOption(options.organizationId)
+                    ? { organization_id: readOption(options.organization) ?? readOption(options.organizationId) }
+                    : {}),
+            },
+        }));
     }));
     program
         .command("db")
         .description("Tenant database commands.")
         .addCommand(new Command("status")
-        .description("Show the current organization's tenant database status.")
+        .description("Show the current organization's tenant database status. Staff can pass global --org to inspect another org.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("db status", options, async () => requestOxygen("/api/cli/db/status"));
     }))
         .addCommand(new Command("provision")
-        .description("Provision a managed Neon tenant database for the current organization.")
+        .description("Provision a managed Neon tenant database for the current organization. Staff can pass global --org to repair another org.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("db provision", options, async () => requestOxygen("/api/cli/db/provision", { method: "POST", body: {} }));
@@ -1798,6 +1836,27 @@ export function createProgram() {
             body: {},
         }));
     }));
+    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 } : {}),
+            },
+        }));
+    }));
     program
         .command("lead-sourcing")
         .description("ICP-gated lead sourcing planning and audit commands.")
@@ -1829,9 +1888,161 @@ export function createProgram() {
             },
         }));
     }));
+    program
+        .command("search")
+        .description("Agent-operable company search, web search, and scraping jobs.")
+        .addCommand(new Command("plan")
+        .description("Plan an Oxygen search or scrape route before running provider jobs.")
+        .requiredOption("--goal <file|text>", "Search/scrape goal text, or a local file path containing the goal.")
+        .option("--kind <kind>", "Route kind: company_search, people_search, signal_search, web_search, web_scrape, local_business_search, or source_specific_scrape.")
+        .option("--target-count <n>", "Optional target row count.")
+        .option("--geography <text>", "Optional geography hint.")
+        .option("--known-urls <urls>", "Comma-separated known URLs for scrape routes.")
+        .option("--provider-hints <providers>", "Comma-separated provider hints.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("search plan", options, () => requestOxygen("/api/cli/search/plan", {
+            method: "POST",
+            body: {
+                goal: readFileIfPresent(options.goal),
+                ...(readOption(options.kind) ? { kind: readOption(options.kind) } : {}),
+                ...(readPositiveInt(options.targetCount) ? { target_count: readPositiveInt(options.targetCount) } : {}),
+                ...(readOption(options.geography) ? { geography: readOption(options.geography) } : {}),
+                ...(readOption(options.knownUrls) ? { known_urls: readCsvOption(options.knownUrls) } : {}),
+                ...(readOption(options.providerHints) ? { provider_hints: readCsvOption(options.providerHints) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("run")
+        .description("Preview or enqueue a durable table-backed search/scrape job from a search plan.")
+        .argument("<table>", "Target table id or slug for live runs.")
+        .requiredOption("--plan <file|json>", "Search plan JSON returned by oxygen search plan.")
+        .option("--route <route_id>", "Route id from the plan. Defaults to recommended_route_id.")
+        .requiredOption("--request-json <json>", "Provider request JSON for the selected route.")
+        .option("--mode <mode>", "dry_run or live. Defaults to dry_run.")
+        .option("--max-credits <n>", "Required credit ceiling for live runs.")
+        .option("--max-pages <n>", "Maximum provider pages to fetch. Defaults to the route's page cap.")
+        .option("--rows-path <path>", "Override route rows path.")
+        .option("--row-mapping-json <json>", "Override route row mapping.")
+        .option("--cursor-path <path>", "Override route cursor path.")
+        .option("--cursor-request-key <path>", "Override request key that receives the next cursor.")
+        .option("--upsert-key <key>", "Column key used to upsert instead of inserting.")
+        .option("--connection-id <connection_id>", "Optional provider integration connection id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("search run", options, () => requestOxygen("/api/cli/search/run", {
+            method: "POST",
+            body: {
+                table,
+                plan: parseJsonObject(readFileIfPresent(options.plan)),
+                request: parseJsonObject(options.requestJson),
+                ...(readOption(options.route) ? { route_id: readOption(options.route) } : {}),
+                ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
+                ...(readPositiveNumber(options.maxCredits) ? { max_credits: readPositiveNumber(options.maxCredits) } : {}),
+                ...(readPositiveInt(options.maxPages) ? { max_pages: readPositiveInt(options.maxPages) } : {}),
+                ...(readOption(options.rowsPath) ? { rows_path: readOption(options.rowsPath) } : {}),
+                ...(options.rowMappingJson ? { row_mapping: parseJsonObject(options.rowMappingJson) } : {}),
+                ...(readOption(options.cursorPath) ? { cursor_path: readOption(options.cursorPath) } : {}),
+                ...(readOption(options.cursorRequestKey) ? { cursor_request_key: readOption(options.cursorRequestKey) } : {}),
+                ...(readOption(options.upsertKey) ? { upsert_key: readOption(options.upsertKey) } : {}),
+                ...(readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("runs")
+        .description("Inspect and control durable search/scrape runs.")
+        .addCommand(new Command("get")
+        .description("Get one durable search/scrape run.")
+        .argument("<run_id>", "Search run UUID.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (runId, options) => {
+        await handleAsyncAction("search runs get", options, () => requestOxygen(`/api/cli/search/runs/${encodeURIComponent(runId)}`));
+    }))
+        .addCommand(new Command("items")
+        .description("List search/scrape run items.")
+        .argument("<run_id>", "Search run UUID.")
+        .option("--status <status>", "Filter by pending, leased, completed, failed, skipped, or canceled.")
+        .option("--limit <n>", "Maximum items to return. Defaults to 100.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (runId, options) => {
+        await handleAsyncAction("search runs items", options, () => {
+            const query = new URLSearchParams();
+            if (readOption(options.status))
+                query.set("status", readOption(options.status) ?? "");
+            const limit = readPositiveInt(options.limit);
+            if (limit)
+                query.set("limit", String(limit));
+            const suffix = query.toString() ? `?${query.toString()}` : "";
+            return requestOxygen(`/api/cli/search/runs/${encodeURIComponent(runId)}/items${suffix}`);
+        });
+    }))
+        .addCommand(new Command("wait")
+        .description("Poll a durable search/scrape run until it finishes.")
+        .argument("<run_id>", "Search run UUID.")
+        .option("--timeout-seconds <n>", "Maximum time to wait. Defaults to 600.")
+        .option("--interval-seconds <n>", "Polling interval. Defaults to 5.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (runId, options) => {
+        await handleAsyncAction("search runs wait", options, () => waitForSearchRun(runId, options));
+    }))
+        .addCommand(new Command("cancel")
+        .description("Request cancellation for a queued or running search/scrape run.")
+        .argument("<run_id>", "Search run UUID.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (runId, options) => {
+        await handleAsyncAction("search runs cancel", options, () => requestOxygen(`/api/cli/search/runs/${encodeURIComponent(runId)}/cancel`, {
+            method: "POST",
+            body: {},
+        }));
+    }))
+        .addCommand(new Command("retry-failed")
+        .description("Requeue failed search/scrape run items.")
+        .argument("<run_id>", "Search run UUID.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (runId, options) => {
+        await handleAsyncAction("search runs retry-failed", options, () => requestOxygen(`/api/cli/search/runs/${encodeURIComponent(runId)}/retry-failed`, {
+            method: "POST",
+            body: {},
+        }));
+    })));
     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("plan")
+        .description("Compile a company-search prompt into ordered provider routes without provider calls.")
+        .requiredOption("--prompt <text-or-file>", "Company-search prompt, or a path to a prompt file.")
+        .option("--target-count <n>", "Desired company count for routing and estimates.")
+        .option("--source-intent <intent>", "Override detected intent: structured, technology, hiring, local, known_source, web, or fallback.")
+        .option("--materialize-preview", "Create a preview table with route rows.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("companies search plan", options, () => requestOxygen("/api/cli/companies/search/plan", {
+            method: "POST",
+            body: readCompaniesSearchPlanBody(options),
+        }));
+    }))
+        .addCommand(new Command("run")
+        .description("Return a dry-run request or queue a live company-search ingestion run.")
+        .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("--mode <mode>", "dry_run or live. Defaults to dry_run.")
+        .option("--max-pages <n>", "Maximum provider pages to ingest. Defaults to the route estimate.")
+        .option("--max-credits <n>", "Required credit ceiling for live runs.")
+        .option("--target-count <n>", "Desired company count when planning from --prompt.")
+        .option("--source-intent <intent>", "Override detected intent when planning from --prompt.")
+        .option("--approved", "Required for live runs after inspecting dry-run output.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("companies search run", options, () => requestOxygen("/api/cli/companies/search/run", {
+            method: "POST",
+            body: readCompaniesSearchRunBody(options),
+        }));
+    })))
         .addCommand(new Command("enrich")
         .description("Preview or run a company enrichment waterfall over an existing table.")
         .addCommand(new Command("preview")
@@ -2231,19 +2442,28 @@ export function createProgram() {
         .description("Search the tool catalog.")
         .argument("[query]", "Search text.")
         .option("--verbosity <verbosity>", "minimal, summary, or full. Defaults to summary. Use minimal for high-fanout discovery sweeps that need to stay under the MCP token budget.")
+        .option("--terse", "Alias for --verbosity minimal.")
         .option("--only-runnable", "Only return tools runnable by the active organization.")
+        .option("--category <category>", "Filter by Oxygen tool category, such as company_search, people_search, research, or local.")
         .option("--capability <tag>", "Filter by capability tag, such as mobile_phone.")
+        .option("--limit <n>", "Maximum number of tools to return. Capped at 100.")
         .option("--json", "Print a JSON envelope.")
         .action(async (query, options) => {
-        await handleAsyncAction("tools search", options, async () => {
+        await handleAsyncAction("tools search", options, () => {
             const params = new URLSearchParams();
             params.set("query", query ?? "");
-            if (readOption(options.verbosity))
-                params.set("verbosity", readOption(options.verbosity) ?? "");
+            const verbosity = options.terse ? "minimal" : readOption(options.verbosity);
+            if (verbosity)
+                params.set("verbosity", verbosity);
             if (options.onlyRunnable)
                 params.set("only_runnable", "true");
+            if (readOption(options.category))
+                params.set("category", readOption(options.category) ?? "");
             if (readOption(options.capability))
                 params.set("capability", readOption(options.capability) ?? "");
+            const limit = readPositiveInt(options.limit);
+            if (limit !== undefined)
+                params.set("limit", String(Math.min(limit, 100)));
             return requestOxygen(`/api/cli/tools/search?${params.toString()}`);
         });
     }))
@@ -2340,7 +2560,9 @@ export function createProgram() {
         .option("--capability <capability>", "Capability to enrich: mobile_phone or work_email. Defaults to mobile_phone.")
         .option("--target-column <column>", "Target enrichment column key. Defaults to the capability payload column.")
         .option("--on-existing-manual-column <mode>", "How to handle an existing manual target: error, write_if_empty, or create_enrichment_column.")
-        .option("--provider-order <providers>", "Comma-separated provider order. Work email defaults to blitzapi,prospeo,leadmagic,hunter,contactout,bettercontact,ai_ark; phone defaults to blitzapi,prospeo,leadmagic,contactout,bettercontact,ai_ark.")
+        .option("--provider-order <providers>", "Comma-separated provider order. Overrides the default waterfall profile.")
+        .option("--email-waterfall-profile <profile>", "Work-email waterfall profile: auto, name_domain, linkedin_url, or first_last_domain.")
+        .option("--email-pattern-validation <mode>", "Work-email pattern pre-step: leadmagic_valid_only or disabled.")
         .option("--verify-phone", "Validate found phone numbers with ClearoutPhone before returning them.")
         .option("--phone-verification-credential-mode <mode>", "ClearoutPhone credential mode for phone verification: managed or user_api_key.")
         .option("--limit <n>", "Rows to estimate. Defaults to 10.")
@@ -2371,7 +2593,9 @@ export function createProgram() {
         .option("--capability <capability>", "Capability to enrich: mobile_phone or work_email. Defaults to mobile_phone.")
         .option("--target-column <column>", "Target enrichment column key. Defaults to the capability payload column.")
         .option("--on-existing-manual-column <mode>", "How to handle an existing manual target: error, write_if_empty, or create_enrichment_column.")
-        .option("--provider-order <providers>", "Comma-separated provider order. Work email defaults to blitzapi,prospeo,leadmagic,hunter,contactout,bettercontact,ai_ark; phone defaults to blitzapi,prospeo,leadmagic,contactout,bettercontact,ai_ark.")
+        .option("--provider-order <providers>", "Comma-separated provider order. Overrides the default waterfall profile.")
+        .option("--email-waterfall-profile <profile>", "Work-email waterfall profile: auto, name_domain, linkedin_url, or first_last_domain.")
+        .option("--email-pattern-validation <mode>", "Work-email pattern pre-step: leadmagic_valid_only or disabled.")
         .option("--verify-phone", "Validate found phone numbers with ClearoutPhone before returning them.")
         .option("--phone-verification-credential-mode <mode>", "ClearoutPhone credential mode for phone verification: managed or user_api_key.")
         .option("--limit <n>", "Rows to queue.")
@@ -2744,7 +2968,7 @@ export function createProgram() {
         .option("--workflow-id <workflow_id>", "Workflow id or slug.")
         .option("--workflow-name <workflow_name>", "Workflow name.")
         .option("--input-json <json>", "Workflow input object. Defaults to {}.")
-        .option("--mode <mode>", "Execution mode: live, dry-run, or smoke-test.")
+        .requiredOption("--mode <mode>", "Execution mode: live, dry-run, or smoke-test.")
         .option("--idempotency-key <key>", "Optional idempotency key.")
         .option("--include-bundle", "Include durable recipe bundles in JSON output.")
         .option("--json", "Print a JSON envelope.")
@@ -2772,7 +2996,7 @@ export function createProgram() {
         .option("--headers-json <json>", "Optional delivery headers object.")
         .option("--external-event-id <id>", "Provider event id for idempotency and inspection.")
         .option("--idempotency-key <key>", "Optional explicit event idempotency key.")
-        .option("--mode <mode>", "Execution mode: live, dry-run, or smoke-test.")
+        .requiredOption("--mode <mode>", "Execution mode: live, dry-run, or smoke-test.")
         .option("--include-bundle", "Include durable recipe bundles in JSON output.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -3019,6 +3243,7 @@ async function tryCompileRecipeFile(absolutePath, source) {
         ...(recipe.status ? { status: recipe.status } : {}),
         ...(recipe.trigger ? { trigger: recipe.trigger } : {}),
         ...(recipe.inputSchema ? { inputSchema: recipe.inputSchema } : {}),
+        ...(recipe.visualPlan ? { visualPlan: recipe.visualPlan } : {}),
         bundle,
         toolsUsed: recipe.tools,
         sourceHash,
@@ -3178,7 +3403,8 @@ export function toolStep(input) {
 }
 `;
 }
-async function tailWorkflowRun(runId, options) {
+async function tailWorkflowRun(// skipcq: JS-R1005 -- CLI tailer coordinates polling, status transitions, and final output formatting.
+runId, options) {
     const timeoutSeconds = readPositiveInt(options.timeoutSeconds)
         ?? WORKFLOW_TAIL_DEFAULT_TIMEOUT_SECONDS;
     const intervalSeconds = readPositiveInt(options.intervalSeconds)
@@ -3192,9 +3418,13 @@ async function tailWorkflowRun(runId, options) {
             method: "POST",
             body: { run_id: runId },
         });
-        const run = latest.run ?? latest;
+        const run = isRecord(latest.run) ? latest.run : latest;
         const status = readRecordString(run, "status");
         if (isTerminalWorkflowRunStatus(status)) {
+            const workflowUrl = readRecordString(latest, "workflowUrl");
+            const runUrl = readRecordString(latest, "runUrl");
+            const webUrl = readRecordString(latest, "web_url");
+            const deepLink = readRecordString(latest, "deepLink");
             return {
                 run,
                 workflowRunId: readRecordString(run, "id") ?? runId,
@@ -3202,6 +3432,10 @@ async function tailWorkflowRun(runId, options) {
                 terminal: true,
                 polls,
                 elapsedMs: Date.now() - startedAt,
+                ...(workflowUrl ? { workflowUrl } : {}),
+                ...(runUrl ? { runUrl } : {}),
+                ...(webUrl ? { web_url: webUrl } : {}),
+                ...(deepLink ? { deepLink } : {}),
             };
         }
         const remainingMs = deadline - Date.now();
@@ -3388,6 +3622,45 @@ async function recoverBackgroundColumnRun(table, traceId) {
 function isNetworkTimeoutError(error) {
     return error instanceof OxygenError && error.code === "network_timeout";
 }
+function readCompaniesSearchPlanBody(options) {
+    const targetCount = readPositiveInt(options.targetCount);
+    return {
+        prompt: readFileIfPresent(options.prompt),
+        ...(targetCount !== undefined ? { target_count: targetCount } : {}),
+        ...(options.sourceIntent ? { source_intent: options.sourceIntent } : {}),
+        ...(options.materializePreview ? { materialize_preview: true } : {}),
+    };
+}
+function readCompaniesSearchRunBody(options) {
+    const prompt = options.prompt ? readFileIfPresent(options.prompt) : null;
+    const plan = options.planJson ? readCompanySearchPlanJson(options.planJson) : null;
+    if (!prompt && !plan) {
+        throw new OxygenError("invalid_request", "Pass --prompt or --plan-json.", { exitCode: 1 });
+    }
+    const maxPages = readPositiveInt(options.maxPages);
+    const maxCredits = readPositiveNumber(options.maxCredits);
+    const targetCount = readPositiveInt(options.targetCount);
+    return {
+        ...(prompt ? { prompt } : {}),
+        ...(plan ? { plan } : {}),
+        ...(options.routeId ? { route_id: options.routeId } : {}),
+        ...(options.toolId ? { tool_id: options.toolId } : {}),
+        ...(options.table ? { table: options.table } : {}),
+        ...(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 } : {}),
+        ...(options.approved ? { approved: true } : {}),
+    };
+}
+function readCompanySearchPlanJson(value) {
+    const parsed = parseJsonObject(readFileIfPresent(value));
+    const data = parsed.data;
+    return data && typeof data === "object" && !Array.isArray(data)
+        ? data
+        : parsed;
+}
 function readCompaniesEnrichBody(table, options) {
     const body = { table };
     const fields = readCsvOption(options.missingFields);
@@ -3795,6 +4068,44 @@ async function waitForTableIngestionRun(runId, options) {
         await sleep(Math.min(intervalSeconds * 1000, remainingMs));
     }
 }
+async function waitForSearchRun(runId, options) {
+    const timeoutSeconds = readPositiveInt(options.timeoutSeconds)
+        ?? TABLE_INGESTION_WAIT_DEFAULT_TIMEOUT_SECONDS;
+    const intervalSeconds = readPositiveInt(options.intervalSeconds)
+        ?? TABLE_INGESTION_WAIT_DEFAULT_INTERVAL_SECONDS;
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutSeconds * 1000;
+    let polls = 0;
+    while (true) {
+        polls += 1;
+        const latestRun = await requestOxygen(`/api/cli/search/runs/${encodeURIComponent(runId)}`);
+        const status = readRecordString(latestRun, "status");
+        if (isTerminalTableIngestionStatus(status)) {
+            return {
+                searchRun: latestRun,
+                searchRunId: readRecordString(latestRun, "id") ?? runId,
+                status,
+                terminal: true,
+                polls,
+                elapsedMs: Date.now() - startedAt,
+                ...(readRecordString(latestRun, "web_url") ? { web_url: readRecordString(latestRun, "web_url") } : {}),
+            };
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            throw new OxygenError("search_run_wait_timeout", "Timed out waiting for search run to finish.", {
+                details: {
+                    search_run_id: runId,
+                    status: status ?? null,
+                    timeout_seconds: timeoutSeconds,
+                    polls,
+                },
+                exitCode: 1,
+            });
+        }
+        await sleep(Math.min(intervalSeconds * 1000, remainingMs));
+    }
+}
 async function waitForTableActionRun(runId, options) {
     const timeoutSeconds = readPositiveInt(options.timeoutSeconds)
         ?? TABLE_ACTION_RUN_WAIT_DEFAULT_TIMEOUT_SECONDS;
@@ -5532,7 +5843,8 @@ function buildContextAssetUpsertBody(options) {
         ...(options.dataJson ? { data: parseJsonObject(options.dataJson) } : {}),
     };
 }
-function buildEnrichColumnBody(table, options) {
+function buildEnrichColumnBody(// skipcq: JS-R1005 -- CLI body builder maps enrichment aliases, selection, provider order, and safety caps.
+table, options) {
     const limit = readPositiveInt(options.limit);
     const filterSelection = readFilterSelectionOption(options.filterJson);
     const explicitSelection = readSelectionJsonOption(options.selectionJson);
@@ -5566,6 +5878,12 @@ function buildEnrichColumnBody(table, options) {
             ? { on_existing_manual_column: readOption(options.onExistingManualColumn) }
             : {}),
         ...(readOption(options.providerOrder) ? { provider_order: readCsvOption(options.providerOrder) } : {}),
+        ...(readOption(options.emailWaterfallProfile)
+            ? { email_waterfall_profile: readOption(options.emailWaterfallProfile) }
+            : {}),
+        ...(readOption(options.emailPatternValidation)
+            ? { email_pattern_validation: readOption(options.emailPatternValidation) }
+            : {}),
         ...(options.verifyPhone ? { verify_phone: true } : {}),
         ...(readOption(options.phoneVerificationCredentialMode)
             ? { phone_verification_credential_mode: readOption(options.phoneVerificationCredentialMode) }

package/dist/runtime.d.ts

@@ -0,0 +1,15 @@
+declare const DEV_CLI_BINARY = "oxygen-dev";
+declare const PROD_CLI_BINARY = "oxygen";
+export type CliUpdateGuidance = {
+    binaryName: typeof DEV_CLI_BINARY | typeof PROD_CLI_BINARY;
+    channel: "dev" | "npm";
+    warningInstruction: string;
+    failureInstruction: string;
+    details: {
+        cli_update_command?: string;
+        cli_update_instruction?: string;
+    };
+};
+export declare function resolveCliBinaryName(env?: NodeJS.ProcessEnv, argv?: readonly string[]): typeof DEV_CLI_BINARY | typeof PROD_CLI_BINARY;
+export declare function resolveCliUpdateGuidance(apiUrl: string | undefined, env?: NodeJS.ProcessEnv, argv?: readonly string[]): CliUpdateGuidance;
+export {};

package/dist/runtime.js

@@ -0,0 +1,56 @@
+import { basename } from "node:path";
+const PROD_API_HOSTNAME = "oxygen-agent.com";
+const DEV_CLI_BINARY = "oxygen-dev";
+const PROD_CLI_BINARY = "oxygen";
+export function resolveCliBinaryName(env = process.env, argv = process.argv) {
+    const explicit = normalizeBinaryName(env.OXYGEN_CLI_BINARY ?? env.OXYGEN_CLI_NAME);
+    if (explicit)
+        return explicit;
+    const invoked = normalizeBinaryName(argv[1]);
+    if (invoked)
+        return invoked;
+    return PROD_CLI_BINARY;
+}
+export function resolveCliUpdateGuidance(apiUrl, env = process.env, argv = process.argv) {
+    const binaryName = resolveCliBinaryName(env, argv);
+    const devLike = binaryName === DEV_CLI_BINARY || (apiUrl ? !isProdApiUrl(apiUrl) : false);
+    if (devLike) {
+        return {
+            binaryName,
+            channel: "dev",
+            warningInstruction: "Refresh the dev CLI (`oxygen-dev`) from the dev branch before using operational commands.",
+            failureInstruction: "Refresh the dev CLI (`oxygen-dev`) from the dev branch before using this command.",
+            details: {
+                cli_update_instruction: "Refresh the dev CLI (`oxygen-dev`) from the dev branch.",
+            },
+        };
+    }
+    return {
+        binaryName,
+        channel: "npm",
+        warningInstruction: "Run `oxygen update` before using operational commands.",
+        failureInstruction: "Run `oxygen update` before using this command.",
+        details: {
+            cli_update_command: "oxygen update",
+        },
+    };
+}
+function normalizeBinaryName(value) {
+    const normalized = basename(value ?? "")
+        .replace(/\.(?:cmd|ps1|bat|js)$/i, "")
+        .trim()
+        .toLowerCase();
+    if (normalized === DEV_CLI_BINARY)
+        return DEV_CLI_BINARY;
+    if (normalized === PROD_CLI_BINARY)
+        return PROD_CLI_BINARY;
+    return null;
+}
+function isProdApiUrl(apiUrl) {
+    try {
+        return new URL(apiUrl).hostname === PROD_API_HOSTNAME;
+    }
+    catch {
+        return false;
+    }
+}

package/node_modules/@oxygen/recipe-sdk/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { JsonSchema, WorkflowStepEffect, WorkflowMode, WorkflowStatus, WorkflowTriggerManifest } from "@oxygen/workflows";
-export type { JsonSchema, WorkflowTriggerManifest, WorkflowMode, WorkflowStatus, WorkflowStepEffect };
+import type { JsonSchema, RecipeVisualPlanManifest, WorkflowStepEffect, WorkflowMode, WorkflowStatus, WorkflowTriggerManifest } from "@oxygen/workflows";
+export type { JsonSchema, RecipeVisualPlanManifest, WorkflowTriggerManifest, WorkflowMode, WorkflowStatus, WorkflowStepEffect };
 export type RecipeLogLevel = "debug" | "info" | "warn" | "error";
 export type RecipeRuntime = "durable";
 export type RecipeToolRunOptions = {
@@ -106,6 +106,32 @@ export type RecipeContext = {
 export type DurableRecipeContext = RecipeContext;
 export type RecipeRunFunction = (ctx: RecipeContext) => unknown | Promise<unknown>;
 export type DurableRecipeRunFunction = RecipeRunFunction;
+export type RecipeVisualBaseStep = {
+    id: string;
+    label: string;
+    description?: string;
+    checkpointId?: string;
+    checkpointKey?: string;
+};
+export type RecipeVisualToolStep = RecipeVisualBaseStep & {
+    kind: "tool";
+    tool: string;
+    effect?: WorkflowStepEffect;
+};
+export type RecipeVisualCodeStep = RecipeVisualBaseStep & {
+    kind: "step";
+};
+export type RecipeVisualBranchStep = RecipeVisualBaseStep & {
+    kind: "branch";
+    conditionLabel?: string;
+    thenId: string;
+    elseId?: string;
+    joinId?: string;
+};
+export type RecipeVisualStep = RecipeVisualToolStep | RecipeVisualCodeStep | RecipeVisualBranchStep;
+export type RecipeVisualPlan = {
+    steps: RecipeVisualStep[];
+};
 export type RecipeDefinition = {
     readonly __oxygen_recipe: true;
     id: string;
@@ -114,6 +140,7 @@ export type RecipeDefinition = {
     status?: WorkflowStatus;
     trigger?: WorkflowTriggerManifest;
     inputSchema?: JsonSchema;
+    visualPlan?: RecipeVisualPlanManifest;
     tools: string[];
     run: RecipeRunFunction;
 };
@@ -125,6 +152,7 @@ export type DefineRecipeInput = {
     status?: WorkflowStatus;
     trigger?: WorkflowTriggerManifest;
     inputSchema?: JsonSchema;
+    visualPlan?: RecipeVisualPlan;
     run: RecipeRunFunction;
 };
 export type DurableRecipeDefinition = RecipeDefinition;
@@ -133,3 +161,7 @@ export type DefineDurableRecipeInput = DefineRecipeInput & {
 };
 export declare function defineRecipe(input: DefineRecipeInput): RecipeDefinition;
 export declare function isRecipeDefinition(value: unknown): value is RecipeDefinition;
+export declare function recipeVisualPlan(steps: RecipeVisualStep[]): RecipeVisualPlan;
+export declare function recipeToolAction(input: Omit<RecipeVisualToolStep, "kind">): RecipeVisualToolStep;
+export declare function recipeStepAction(input: Omit<RecipeVisualCodeStep, "kind">): RecipeVisualCodeStep;
+export declare function recipeBranchAction(input: Omit<RecipeVisualBranchStep, "kind">): RecipeVisualBranchStep;

package/node_modules/@oxygen/recipe-sdk/dist/index.js

@@ -23,6 +23,7 @@ export function defineRecipe(input) {
         }
         return tool.trim();
     }))).sort();
+    const visualPlan = normalizeVisualPlan(input.visualPlan);
     return {
         __oxygen_recipe: true,
         id: input.id,
@@ -32,6 +33,7 @@ export function defineRecipe(input) {
         ...(input.status ? { status: input.status } : {}),
         ...(input.trigger ? { trigger: input.trigger } : {}),
         ...(input.inputSchema ? { inputSchema: input.inputSchema } : {}),
+        ...(visualPlan ? { visualPlan } : {}),
         run: input.run,
     };
 }
@@ -40,3 +42,62 @@ export function isRecipeDefinition(value) {
         && typeof value === "object"
         && value.__oxygen_recipe === true;
 }
+export function recipeVisualPlan(steps) {
+    return { steps };
+}
+export function recipeToolAction(input) {
+    return { kind: "tool", ...withCheckpointAlias("tool", input) };
+}
+export function recipeStepAction(input) {
+    return { kind: "step", ...withCheckpointAlias("step", input) };
+}
+export function recipeBranchAction(input) {
+    return { kind: "branch", ...withCheckpointAlias("step", input) };
+}
+function withCheckpointAlias(prefix, input) {
+    if (input.checkpointId || !input.checkpointKey)
+        return input;
+    return {
+        ...input,
+        checkpointId: `${prefix}:${input.checkpointKey}`,
+    };
+}
+function normalizeVisualPlan(input) {
+    if (!input)
+        return undefined;
+    return {
+        version: 1,
+        steps: input.steps.map((step) => {
+            const checkpointId = step.checkpointId
+                ?? (step.checkpointKey ? `${step.kind === "tool" ? "tool" : "step"}:${step.checkpointKey}` : undefined);
+            const base = {
+                id: step.id,
+                label: step.label,
+                ...(step.description ? { description: step.description } : {}),
+                ...(checkpointId ? { checkpoint_id: checkpointId } : {}),
+            };
+            if (step.kind === "tool") {
+                return {
+                    kind: "tool",
+                    ...base,
+                    tool: step.tool,
+                    ...(step.effect ? { effect: step.effect } : {}),
+                };
+            }
+            if (step.kind === "branch") {
+                return {
+                    kind: "branch",
+                    ...base,
+                    ...(step.conditionLabel ? { condition_label: step.conditionLabel } : {}),
+                    then_id: step.thenId,
+                    ...(step.elseId ? { else_id: step.elseId } : {}),
+                    ...(step.joinId ? { join_id: step.joinId } : {}),
+                };
+            }
+            return {
+                kind: "step",
+                ...base,
+            };
+        }),
+    };
+}

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

@@ -32,9 +32,9 @@ export declare const BASE_PRICING_PLANS: {
         readonly weeklyCreditsLimit: 500;
         readonly rolloverCap: 500;
         readonly byokEnabled: false;
-        readonly description: "Try OXYGEN with managed email, phone enrichment, and AI credits.";
+        readonly description: "Get $10 in credits on us every month — try OXYGEN with managed email, phone enrichment, and AI credits.";
         readonly ctaLabel: "Start free";
-        readonly features: readonly ["All integrations", "Workflows", "No card required"];
+        readonly features: readonly ["$10 in credits every month", "All integrations", "Workflows", "No card required"];
     };
     readonly starter: {
         readonly tier: "starter";

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

@@ -11,9 +11,10 @@ export const BASE_PRICING_PLANS = {
         weeklyCreditsLimit: 500,
         rolloverCap: 500,
         byokEnabled: false,
-        description: "Try OXYGEN with managed email, phone enrichment, and AI credits.",
+        description: "Get $10 in credits on us every month — try OXYGEN with managed email, phone enrichment, and AI credits.",
         ctaLabel: "Start free",
         features: [
+            "$10 in credits every month",
             "All integrations",
             "Workflows",
             "No card required",

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

@@ -1,2 +1,2 @@
-export declare const OXYGEN_VERSION = "1.109.10";
+export declare const OXYGEN_VERSION = "1.123.0";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.0.0";

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

@@ -1,3 +1,3 @@
-export const OXYGEN_VERSION = "1.109.10";
+export const OXYGEN_VERSION = "1.123.0";
 // Bump this only when deployed CLI/API contracts require a newer CLI.
 export const OXYGEN_MINIMUM_CLI_VERSION = "1.0.0";

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

@@ -9,7 +9,7 @@ export declare const DEFAULT_WORKFLOW_CRON_TIMEZONE = "UTC";
 export type WorkflowMode = "dry_run" | "live" | "smoke_test";
 export type WorkflowTriggerType = "api" | "webhook" | "cron" | "event";
 export type WorkflowStatus = "active" | "disabled";
-export type WorkflowStepKind = "transform" | "tool";
+export type WorkflowStepKind = "transform" | "tool" | "branch";
 export type WorkflowStepEffect = "none" | "external_read" | "external_write";
 export type RecipeRuntime = "durable";
 export type WorkflowEventFilterOp = "eq" | "neq" | "exists" | "not_exists";
@@ -69,7 +69,48 @@ export type WorkflowToolStepManifest = {
     mode?: WorkflowMode;
     payload_source: string;
 };
-export type WorkflowStepManifest = WorkflowTransformStepManifest | WorkflowToolStepManifest;
+export type WorkflowBranchStepManifest = {
+    kind: "branch";
+    id: string;
+    description?: string;
+    condition_source: string;
+    then_id: string;
+    else_id?: string;
+    join_id?: string;
+};
+export type WorkflowStepManifest = WorkflowTransformStepManifest | WorkflowToolStepManifest | WorkflowBranchStepManifest;
+export type RecipeVisualToolStepManifest = {
+    kind: "tool";
+    id: string;
+    label: string;
+    description?: string;
+    tool: string;
+    effect?: WorkflowStepEffect;
+    checkpoint_id?: string;
+};
+export type RecipeVisualCodeStepManifest = {
+    kind: "step";
+    id: string;
+    label: string;
+    description?: string;
+    checkpoint_id?: string;
+};
+export type RecipeVisualBranchStepManifest = {
+    kind: "branch";
+    id: string;
+    label: string;
+    description?: string;
+    condition_label?: string;
+    then_id: string;
+    else_id?: string;
+    join_id?: string;
+    checkpoint_id?: string;
+};
+export type RecipeVisualStepManifest = RecipeVisualToolStepManifest | RecipeVisualCodeStepManifest | RecipeVisualBranchStepManifest;
+export type RecipeVisualPlanManifest = {
+    version: 1;
+    steps: RecipeVisualStepManifest[];
+};
 export type WorkflowManifest = {
     manifest_version: 1;
     workflow: {
@@ -98,6 +139,7 @@ export type RecipeManifest = {
     bundle: string;
     bundle_format: "esm";
     tools_used: string[];
+    visual_plan?: RecipeVisualPlanManifest;
     source_hash: string;
     compiler_version: typeof DURABLE_RECIPE_COMPILER_VERSION;
     created_at: string;
@@ -176,7 +218,7 @@ export type WorkflowCallInput = {
     workflow_id?: string;
     workflow_name?: string;
     input?: Record<string, unknown>;
-    mode?: WorkflowMode;
+    mode: WorkflowMode;
     idempotency_key?: string;
 };
 type WorkflowFunction = (context: Record<string, unknown>) => unknown | Promise<unknown>;
@@ -208,7 +250,17 @@ export type WorkflowToolStepDefinition = {
     mode?: WorkflowMode;
     payload: WorkflowFunction;
 };
-export type WorkflowStepDefinition = WorkflowTransformStepDefinition | WorkflowToolStepDefinition;
+export type WorkflowBranchStepDefinition = {
+    readonly __oxygen_workflow_step: true;
+    kind: "branch";
+    id: string;
+    description?: string;
+    condition: WorkflowFunction;
+    then: string;
+    else?: string;
+    join?: string;
+};
+export type WorkflowStepDefinition = WorkflowTransformStepDefinition | WorkflowToolStepDefinition | WorkflowBranchStepDefinition;
 export type WorkflowLintIssue = {
     path: string;
     code: string;
@@ -271,12 +323,21 @@ export declare function toolStep(input: {
     mode?: WorkflowMode;
     payload: WorkflowFunction;
 }): WorkflowToolStepDefinition;
+export declare function branchStep(input: {
+    id: string;
+    description?: string;
+    condition: WorkflowFunction;
+    then: string;
+    else?: string;
+    join?: string;
+}): WorkflowBranchStepDefinition;
 export declare function isWorkflowDefinition(value: unknown): value is WorkflowDefinition;
 export declare function isWorkflowManifest(value: unknown): value is WorkflowManifest;
 export declare function isRecipeManifest(value: unknown): value is RecipeManifest;
 export declare function isDurableRecipeManifest(value: unknown): value is RecipeManifest;
 export declare function isAnyWorkflowManifest(value: unknown): value is AnyWorkflowManifest;
-export declare function compileWorkflowDefinition(definition: WorkflowDefinition, options?: {
+export declare function compileWorkflowDefinition(// skipcq: JS-R1005 -- compiler validates workflow metadata, trigger, steps, branch targets, and defaults together.
+definition: WorkflowDefinition, options?: {
     source?: string;
     sourceHash?: string;
     createdAt?: Date;
@@ -289,6 +350,7 @@ export declare function buildRecipeManifest(input: {
     inputSchema?: JsonSchema;
     bundle: string;
     toolsUsed: string[];
+    visualPlan?: RecipeVisualPlanManifest;
     sourceHash?: string;
     createdAt?: Date;
 }): RecipeManifest;
@@ -370,6 +432,7 @@ export declare const workflowCallSchema: {
             readonly type: "string";
         };
     };
+    readonly required: readonly ["mode"];
 };
 export declare const workflowEventEmitSchema: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
@@ -405,7 +468,7 @@ export declare const workflowEventEmitSchema: {
             readonly enum: readonly ["dry_run", "live", "smoke_test"];
         };
     };
-    readonly required: readonly ["source", "event", "payload"];
+    readonly required: readonly ["source", "event", "payload", "mode"];
 };
 export declare const workflowTriggerSchema: {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
@@ -528,6 +591,7 @@ export declare function getWorkflowSchema(subject?: "apply" | "call" | "event" |
             readonly type: "string";
         };
     };
+    readonly required: readonly ["mode"];
 } | {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly title: "OXYGEN Workflow Event Emit Input";
@@ -562,7 +626,7 @@ export declare function getWorkflowSchema(subject?: "apply" | "call" | "event" |
             readonly enum: readonly ["dry_run", "live", "smoke_test"];
         };
     };
-    readonly required: readonly ["source", "event", "payload"];
+    readonly required: readonly ["source", "event", "payload", "mode"];
 } | {
     readonly $schema: "https://json-schema.org/draft/2020-12/schema";
     readonly title: "OXYGEN Workflow Trigger";
@@ -667,6 +731,7 @@ export declare function getWorkflowSchema(subject?: "apply" | "call" | "event" |
                     readonly type: "string";
                 };
             };
+            readonly required: readonly ["mode"];
         };
         event: {
             readonly $schema: "https://json-schema.org/draft/2020-12/schema";
@@ -702,7 +767,7 @@ export declare function getWorkflowSchema(subject?: "apply" | "call" | "event" |
                     readonly enum: readonly ["dry_run", "live", "smoke_test"];
                 };
             };
-            readonly required: readonly ["source", "event", "payload"];
+            readonly required: readonly ["source", "event", "payload", "mode"];
         };
         trigger: {
             readonly $schema: "https://json-schema.org/draft/2020-12/schema";

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

@@ -115,6 +115,18 @@ export function toolStep(input) {
         payload: input.payload,
     };
 }
+export function branchStep(input) {
+    return {
+        __oxygen_workflow_step: true,
+        kind: "branch",
+        id: input.id,
+        ...(input.description ? { description: input.description } : {}),
+        condition: input.condition,
+        then: input.then,
+        ...(input.else !== undefined ? { else: input.else } : {}),
+        ...(input.join !== undefined ? { join: input.join } : {}),
+    };
+}
 export function isWorkflowDefinition(value) {
     return isRecord(value) && value.__oxygen_workflow_definition === true;
 }
@@ -134,7 +146,8 @@ export function isDurableRecipeManifest(value) {
 export function isAnyWorkflowManifest(value) {
     return isWorkflowManifest(value) || isRecipeManifest(value);
 }
-export function compileWorkflowDefinition(definition, options = {}) {
+export function compileWorkflowDefinition(// skipcq: JS-R1005 -- compiler validates workflow metadata, trigger, steps, branch targets, and defaults together.
+definition, options = {}) {
     const sourceHash = options.sourceHash
         ?? hashWorkflowSource(options.source ?? JSON.stringify(definition, workflowJsonReplacer));
     const manifest = {
@@ -156,6 +169,17 @@ export function compileWorkflowDefinition(definition, options = {}) {
                     run_source: serializeWorkflowFunction(step.run, `steps.${step.id}.run`),
                 };
             }
+            if (step.kind === "branch") {
+                return {
+                    kind: "branch",
+                    id: step.id,
+                    ...(step.description ? { description: step.description } : {}),
+                    condition_source: serializeWorkflowFunction(step.condition, `steps.${step.id}.condition`),
+                    then_id: step.then,
+                    ...(step.else !== undefined ? { else_id: step.else } : {}),
+                    ...(step.join !== undefined ? { join_id: step.join } : {}),
+                };
+            }
             return {
                 kind: "tool",
                 id: step.id,
@@ -192,6 +216,7 @@ export function buildRecipeManifest(input) {
         bundle,
         bundle_format: "esm",
         tools_used: Array.from(new Set((input.toolsUsed ?? []).filter(Boolean))).sort(),
+        ...(input.visualPlan ? { visual_plan: input.visualPlan } : {}),
         source_hash: sourceHash,
         compiler_version: DURABLE_RECIPE_COMPILER_VERSION,
         created_at: (input.createdAt ?? new Date()).toISOString(),
@@ -233,6 +258,15 @@ value, options = {}) {
         add("$.steps", "missing_steps", "At least one workflow step is required.");
     }
     else {
+        // Pre-pass: collect id → declared-index so branch targets can be
+        // validated for existence + forward-only direction in the main pass.
+        const idToIndex = new Map();
+        value.steps.forEach((step, index) => {
+            if (isRecord(step) && isNonEmptyString(step.id)) {
+                if (!idToIndex.has(step.id))
+                    idToIndex.set(step.id, index);
+            }
+        });
         const ids = new Set();
         value.steps.forEach((step, index) => {
             const path = `$.steps.${index}`;
@@ -287,7 +321,23 @@ value, options = {}) {
                 }
                 return;
             }
-            add(`${path}.kind`, "invalid_step_kind", "Step kind must be transform or tool.");
+            if (step.kind === "branch") {
+                if (!isNonEmptyString(step.condition_source)) {
+                    add(`${path}.condition_source`, "missing_step_code", "Branch step condition_source is required.");
+                }
+                else {
+                    validatePureFunctionSource(step.condition_source, `${path}.condition_source`, add);
+                }
+                validateBranchTarget(step.then_id, `${path}.then_id`, "then_id", index, idToIndex, add);
+                if (step.else_id !== undefined) {
+                    validateBranchTarget(step.else_id, `${path}.else_id`, "else_id", index, idToIndex, add);
+                }
+                if (step.join_id !== undefined) {
+                    validateBranchTarget(step.join_id, `${path}.join_id`, "join_id", index, idToIndex, add);
+                }
+                return;
+            }
+            add(`${path}.kind`, "invalid_step_kind", "Step kind must be transform, tool, or branch.");
         });
     }
     if (!isNonEmptyString(value.source_hash)) {
@@ -364,11 +414,97 @@ value, options = {}) {
     else {
         add("$.tools_used", "missing_recipe_tools", "Durable recipes must declare at least one allowed tool.");
     }
+    const declaredTools = Array.isArray(value.tools_used)
+        ? new Set(value.tools_used.filter((toolId) => typeof toolId === "string" && toolId.trim().length > 0))
+        : new Set();
+    if (value.visual_plan !== undefined) {
+        validateRecipeVisualPlan(value.visual_plan, "$.visual_plan", declaredTools, add);
+    }
     if (!isNonEmptyString(value.source_hash)) {
         add("$.source_hash", "missing_source_hash", "Recipe manifest source_hash is required.");
     }
     return { ok: issues.length === 0, issues };
 }
+function validateRecipeVisualPlan(value, path, declaredTools, add) {
+    if (!isRecord(value)) {
+        add(path, "invalid_visual_plan", "Recipe visual_plan must be an object.");
+        return;
+    }
+    if (value.version !== 1) {
+        add(`${path}.version`, "invalid_visual_plan_version", "Recipe visual_plan version must be 1.");
+    }
+    if (!Array.isArray(value.steps)) {
+        add(`${path}.steps`, "invalid_visual_plan_steps", "Recipe visual_plan steps must be an array.");
+        return;
+    }
+    if (value.steps.length === 0) {
+        add(`${path}.steps`, "missing_visual_plan_steps", "Recipe visual_plan must declare at least one step.");
+        return;
+    }
+    const idToIndex = new Map();
+    value.steps.forEach((step, index) => {
+        if (isRecord(step) && isNonEmptyString(step.id) && !idToIndex.has(step.id)) {
+            idToIndex.set(step.id, index);
+        }
+    });
+    const ids = new Set();
+    value.steps.forEach((step, index) => {
+        const stepPath = `${path}.steps.${index}`;
+        if (!isRecord(step)) {
+            add(stepPath, "invalid_visual_plan_step", "Recipe visual_plan step must be an object.");
+            return;
+        }
+        if (!isNonEmptyString(step.id)) {
+            add(`${stepPath}.id`, "invalid_visual_plan_step_id", "Recipe visual_plan step id is required.");
+        }
+        else if (ids.has(step.id)) {
+            add(`${stepPath}.id`, "duplicate_visual_plan_step_id", `Recipe visual_plan step id '${step.id}' is duplicated.`);
+        }
+        else {
+            ids.add(step.id);
+        }
+        if (!isNonEmptyString(step.label)) {
+            add(`${stepPath}.label`, "invalid_visual_plan_step_label", "Recipe visual_plan step label is required.");
+        }
+        if (step.description !== undefined && typeof step.description !== "string") {
+            add(`${stepPath}.description`, "invalid_visual_plan_description", "Recipe visual_plan description must be a string.");
+        }
+        if (step.checkpoint_id !== undefined && !isNonEmptyString(step.checkpoint_id)) {
+            add(`${stepPath}.checkpoint_id`, "invalid_visual_plan_checkpoint", "Recipe visual_plan checkpoint_id must be a non-empty string.");
+        }
+        if (step.kind === "tool") {
+            if (!isNonEmptyString(step.tool)) {
+                add(`${stepPath}.tool`, "missing_visual_plan_tool", "Recipe visual_plan tool step requires a tool id.");
+            }
+            else if (declaredTools.size > 0 && !declaredTools.has(step.tool)) {
+                add(`${stepPath}.tool`, "visual_plan_tool_not_declared", `Recipe visual_plan tool '${step.tool}' must be present in tools_used.`);
+            }
+            if (step.effect !== undefined
+                && step.effect !== "none"
+                && step.effect !== "external_read"
+                && step.effect !== "external_write") {
+                add(`${stepPath}.effect`, "invalid_visual_plan_effect", "Recipe visual_plan tool effect is invalid.");
+            }
+            return;
+        }
+        if (step.kind === "step")
+            return;
+        if (step.kind === "branch") {
+            if (step.condition_label !== undefined && typeof step.condition_label !== "string") {
+                add(`${stepPath}.condition_label`, "invalid_visual_plan_condition", "Recipe visual_plan condition_label must be a string.");
+            }
+            validateBranchTarget(step.then_id, `${stepPath}.then_id`, "then_id", index, idToIndex, add);
+            if (step.else_id !== undefined) {
+                validateBranchTarget(step.else_id, `${stepPath}.else_id`, "else_id", index, idToIndex, add);
+            }
+            if (step.join_id !== undefined) {
+                validateBranchTarget(step.join_id, `${stepPath}.join_id`, "join_id", index, idToIndex, add);
+            }
+            return;
+        }
+        add(`${stepPath}.kind`, "invalid_visual_plan_step_kind", "Recipe visual_plan step kind must be tool, step, or branch.");
+    });
+}
 export function assertRecipeManifest(value, options = {}) {
     const result = lintRecipeManifest(value, options);
     if (result.ok)
@@ -710,6 +846,7 @@ export const workflowCallSchema = {
         mode: { enum: ["dry_run", "live", "smoke_test"] },
         idempotency_key: { type: "string" },
     },
+    required: ["mode"],
 };
 export const workflowEventEmitSchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -726,7 +863,7 @@ export const workflowEventEmitSchema = {
         idempotency_key: { type: "string" },
         mode: { enum: ["dry_run", "live", "smoke_test"] },
     },
-    required: ["source", "event", "payload"],
+    required: ["source", "event", "payload", "mode"],
 };
 export const workflowTriggerSchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -999,6 +1136,20 @@ function serializeWorkflowFunction(fn, path) {
     }
     return source;
 }
+function validateBranchTarget(target, path, fieldLabel, branchIndex, idToIndex, add) {
+    if (typeof target !== "string" || target.trim().length === 0) {
+        add(path, `missing_branch_${fieldLabel}`, `Branch step ${fieldLabel} is required.`);
+        return;
+    }
+    const targetIndex = idToIndex.get(target);
+    if (targetIndex === undefined) {
+        add(path, "invalid_branch_target", `Branch ${fieldLabel} references unknown step id '${target}'.`);
+        return;
+    }
+    if (targetIndex <= branchIndex) {
+        add(path, "branch_back_jump", `Branch ${fieldLabel} must reference a step that comes after the branch in declared order.`);
+    }
+}
 function validatePureFunctionSource(source, path, add) {
     if (!source.trim()) {
         add(path, "empty_function_source", "Workflow function source cannot be empty.");

package/package.json

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