@vendoai/vendo 0.4.0

package/dist/cli.js

@@ -0,0 +1,333 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { isVendoKey } from "./cli/cloud/client.js";
+import { runLoginCommand } from "./cli/cloud/device-login.js";
+import { runCloud } from "./cli/cloud/index.js";
+import { runDoctor } from "./cli/doctor.js";
+import { runEject } from "./cli/eject.js";
+import { runExtractApply } from "./cli/extract/apply.js";
+import { runInit } from "./cli/init.js";
+import { runMcp } from "./cli/mcp/index.js";
+import { runPlayground } from "./cli/playground.js";
+import { runRefineCommand } from "./cli/refine.js";
+import { CLI_VERSION } from "./cli/shared.js";
+import { runSync } from "./cli/sync.js";
+const HELP = `vendo — install your product's agent
+
+Usage: vendo <command> [dir] [options]
+
+Commands:
+  init [dir]      Set up Vendo: wire the handler, extract tools + theme, resolve a model key
+  login [email]   Claim a Vendo Cloud key: approve in the browser; the key lands in .env.local
+  doctor [dir]    Verify the install: wiring, live probes, and one real model turn (--json for agents)
+
+Advanced:
+  sync [dir]      Re-extract tools and baselines (init hooks this into predev/prebuild; --strict is the CI gate)
+  eject <surface> [dir]  Copy a shipped chrome surface's presentation source into your repo (--list to see surfaces)
+  extract [dir]   Apply a coding agent's extraction draft through the deterministic guards (--apply <draft.json>)
+  refine [dir]    Propose compound capabilities, risk corrections, and brief updates as reviewable diffs
+  playground      Render every Vendo surface against scripted data in the browser — no model key needed
+  mcp <command>   Generate MCP registry discovery and domain-verification files
+  cloud <command> Use the public Vendo Cloud API
+
+Options:
+  --agent                    Init only: print a read-only JSON plan — code changes, extracted tools, risk recommendations, the aiPolish delegation contract
+  --apply <draft.json>       Extract only: draft file an external agent produced from the plan's aiPolish contract
+  --yes                      Init: skip the cloud-login offer; refine: approve displayed diffs; doctor: auto-start the dev server
+  --force                    Init/server-json: overwrite owned or generated files; eject: overwrite an ejected dir
+  --auth <preset>            Init only: wire this auth preset without asking (authJs, clerk, supabase, auth0, jwt, none)
+  --framework <name>         Init only: override framework detection (next, express) — required non-interactively when detection fails
+  --cloud-key <key>          Init only: write this Vendo Cloud key to .env.local instead of the login offer
+  --email <address>          Login only: pre-fill the approval page (login hint)
+  --wait <seconds>           Login only: bound this call's polling to N seconds (agents loop re-runs; each resumes the same request), then exit resumably
+  --byo                      Init only: decline the Vendo Cloud offer (bring your own model key)
+  --ai-polish                Init only: consent to the AI extraction pass without a prompt (works non-interactively)
+  --engine <name>            Init only: pin the AI-polish engine (claude, codex, npx) instead of first-available
+  --theme <slot=value>       Init only: override a theme slot value directly (repeatable)
+  --list                     Eject only: show the ejectable surfaces
+  --model-import <specifier> Refine only: module exporting the host's ai-SDK model
+  --ask <text>               Refine only: interview answer (repeatable) for non-interactive runs
+  --url <url>                Doctor/refine/server-json: mounted wire base or public MCP URL
+  --strict                   Sync only: exit 2 on breaking changes, 3 when saved references are impacted
+  --port <port>              Playground only: listen on a fixed port (default: any free port)
+  --no-open                  Playground only: print the URL without opening the browser
+  --json                     Sync/doctor: print one machine-readable report object
+  --report                   Sync only: push the report to Vendo Cloud
+  --key <key>                Sync/cloud: override VENDO_API_KEY
+  --api-url <url>            Sync/cloud/login: override VENDO_CLOUD_URL
+  --version                  Print the version
+`;
+function option(args, name) {
+    const exact = args.indexOf(name);
+    if (exact >= 0)
+        return args[exact + 1];
+    return args.find((value) => value.startsWith(`${name}=`))?.slice(name.length + 1);
+}
+function options(args, name) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === name && args[index + 1] !== undefined)
+            values.push(args[index + 1]);
+        else if (args[index].startsWith(`${name}=`))
+            values.push(args[index].slice(name.length + 1));
+    }
+    return values;
+}
+const INIT_FLAGS = new Set(["--agent", "--yes", "--force", "--byo", "--ai-polish"]);
+const INIT_VALUE_OPTIONS = ["--auth", "--framework", "--cloud-key", "--theme", "--engine"];
+/** Agent-install-dx: every init wizard question has a value-flag answer; a
+    bad value fails as loudly as an unknown flag, with the valid choices. */
+const INIT_AUTH_VALUES = ["authJs", "clerk", "supabase", "auth0", "jwt", "none"];
+const INIT_FRAMEWORK_VALUES = ["next", "express"];
+const INIT_ENGINE_VALUES = ["claude", "codex", "npx"];
+const EXTRACT_FLAGS = new Set(["--force"]);
+const EXTRACT_VALUE_OPTIONS = ["--apply"];
+const DOCTOR_FLAGS = new Set(["--json", "--yes"]);
+const DOCTOR_VALUE_OPTIONS = ["--url"];
+const REFINE_FLAGS = new Set(["--yes"]);
+const REFINE_VALUE_OPTIONS = ["--url", "--model-import", "--ask"];
+const SYNC_FLAGS = new Set(["--strict", "--json", "--report"]);
+const SYNC_VALUE_OPTIONS = ["--url", "--key", "--api-url"];
+const LOGIN_VALUE_OPTIONS = ["--email", "--api-url", "--wait"];
+/** ENG-335: options the CLI does not recognize — or value options missing
+    their value — must fail loudly before anything runs. Silently dropping a
+    flag is how the "--agent writes nothing" promise broke in the field: an
+    older CLI ignored --agent and ran a full, writing init. */
+function optionErrors(args, flags, valueOptions) {
+    const errors = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg.startsWith("--"))
+            continue;
+        if (flags.has(arg))
+            continue;
+        if (valueOptions.includes(arg)) {
+            // A value that looks like another flag is a missing value, not a value —
+            // otherwise `--model-import --force` proceeds with modelImport "--force".
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith("--"))
+                errors.push(`${arg} requires a value`);
+            else
+                index += 1;
+            continue;
+        }
+        if (valueOptions.some((name) => arg.startsWith(`${name}=`)))
+            continue;
+        errors.push(`unknown option: ${arg}`);
+    }
+    return errors;
+}
+/** Playground follows the ENG-335 rule too: unknown flags fail loudly. */
+function playgroundOptionErrors(args) {
+    const errors = [];
+    let port;
+    const parsePort = (value, flag) => {
+        const parsed = value !== undefined && /^\d+$/.test(value) ? Number(value) : NaN;
+        if (Number.isInteger(parsed) && parsed >= 1 && parsed <= 65_535)
+            port = parsed;
+        else
+            errors.push(`${flag} requires a port number (1-65535)`);
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--no-open")
+            continue;
+        if (arg === "--port") {
+            const value = args[index + 1];
+            parsePort(value !== undefined && value.startsWith("--") ? undefined : value, "--port");
+            if (value !== undefined && !value.startsWith("--"))
+                index += 1;
+            continue;
+        }
+        if (arg.startsWith("--port=")) {
+            parsePort(arg.slice("--port=".length), "--port");
+            continue;
+        }
+        errors.push(arg.startsWith("--") ? `unknown option: ${arg}` : `unexpected argument: ${arg}`);
+    }
+    return { errors, port };
+}
+function target(args) {
+    const optionValues = new Set();
+    for (const name of ["--model-import", "--url", "--key", "--api-url", "--ask", "--apply",
+        "--auth", "--framework", "--cloud-key", "--theme"]) {
+        for (let index = 0; index < args.length; index += 1) {
+            if (args[index] === name && args[index + 1] !== undefined)
+                optionValues.add(args[index + 1]);
+        }
+    }
+    return args.find((value) => !value.startsWith("--") && !optionValues.has(value)) ?? process.cwd();
+}
+export async function main(argv) {
+    const [command, ...args] = argv;
+    if (command === undefined || command === "--help" || command === "-h") {
+        console.log(HELP);
+        return 0;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(CLI_VERSION);
+        return 0;
+    }
+    if (command === "login") {
+        const problems = optionErrors(args, new Set(), LOGIN_VALUE_OPTIONS);
+        const wait = option(args, "--wait");
+        if (wait !== undefined && !/^\d+$/.test(wait)) {
+            problems.push("--wait takes a whole number of seconds (example: vendo login --wait 90)");
+        }
+        if (problems.length > 0) {
+            console.error(`vendo login: ${problems.join("; ")}\n\n${HELP}`);
+            return 1;
+        }
+        return runLoginCommand(args);
+    }
+    if (command === "cloud")
+        return runCloud(args);
+    if (command === "mcp")
+        return runMcp(args);
+    if (command === "init") {
+        const problems = optionErrors(args, INIT_FLAGS, INIT_VALUE_OPTIONS);
+        const auth = option(args, "--auth");
+        if (auth !== undefined && !INIT_AUTH_VALUES.includes(auth)) {
+            problems.push(`--auth must be one of ${INIT_AUTH_VALUES.join(", ")} (example: vendo init --auth clerk)`);
+        }
+        const framework = option(args, "--framework");
+        if (framework !== undefined && !INIT_FRAMEWORK_VALUES.includes(framework)) {
+            problems.push("--framework must be next or express (example: vendo init --framework next)");
+        }
+        const cloudKey = option(args, "--cloud-key");
+        if (cloudKey !== undefined && !isVendoKey(cloudKey)) {
+            problems.push("--cloud-key must be a Vendo Cloud key (vnd_ + 40 hex; `vendo login` issues one)");
+        }
+        const engine = option(args, "--engine");
+        if (engine !== undefined && !INIT_ENGINE_VALUES.includes(engine)) {
+            problems.push(`--engine must be one of ${INIT_ENGINE_VALUES.join(", ")} (example: vendo init --engine codex)`);
+        }
+        if (cloudKey !== undefined && args.includes("--byo")) {
+            problems.push("--cloud-key and --byo answer the same question — pass one or the other");
+        }
+        const themePairs = options(args, "--theme");
+        const badTheme = themePairs.find((pair) => !/^[A-Za-z]+=./.test(pair));
+        if (badTheme !== undefined) {
+            problems.push(`--theme takes slot=value (example: vendo init --theme accent=#7c3bed), got ${JSON.stringify(badTheme)}`);
+        }
+        if (problems.length > 0) {
+            console.error(`vendo init: ${problems.join("; ")}\n\n${HELP}`);
+            return 1;
+        }
+        return runInit({
+            targetDir: target(args),
+            agent: args.includes("--agent"),
+            yes: args.includes("--yes"),
+            force: args.includes("--force"),
+            ...(auth === undefined ? {} : { auth: auth }),
+            ...(framework === undefined ? {} : { framework: framework }),
+            ...(cloudKey === undefined ? {} : { cloudKey }),
+            ...(args.includes("--byo") ? { byo: true } : {}),
+            ...(args.includes("--ai-polish") ? { aiPolish: true } : {}),
+            ...(engine === undefined ? {} : { engine }),
+            ...(themePairs.length === 0 ? {} : {
+                themeAnswers: Object.fromEntries(themePairs.map((pair) => {
+                    const at = pair.indexOf("=");
+                    return [pair.slice(0, at), pair.slice(at + 1)];
+                })),
+            }),
+        });
+    }
+    if (command === "extract") {
+        const problems = optionErrors(args, EXTRACT_FLAGS, EXTRACT_VALUE_OPTIONS);
+        if (!args.some((arg) => arg === "--apply" || arg.startsWith("--apply="))) {
+            problems.push("--apply <draft.json> is required");
+        }
+        else if (option(args, "--apply") === "") {
+            // `--apply=` slips past the missing-value check with an empty string,
+            // which would resolve to the cwd instead of failing loudly.
+            problems.push("--apply requires a value");
+        }
+        if (problems.length > 0) {
+            console.error(`vendo extract: ${problems.join("; ")}\n\n${HELP}`);
+            return 1;
+        }
+        return runExtractApply({
+            targetDir: target(args),
+            apply: option(args, "--apply"),
+            force: args.includes("--force"),
+        });
+    }
+    if (command === "eject") {
+        const positional = args.filter((value) => !value.startsWith("--"));
+        const list = args.includes("--list");
+        // `eject --list [dir]` has no surface positional — the first one is the dir.
+        return runEject({
+            surface: list ? undefined : positional[0],
+            targetDir: (list ? positional[0] : positional[1]) ?? process.cwd(),
+            list,
+            force: args.includes("--force"),
+        });
+    }
+    if (command === "doctor") {
+        const problems = optionErrors(args, DOCTOR_FLAGS, DOCTOR_VALUE_OPTIONS);
+        if (problems.length > 0) {
+            console.error(`vendo doctor: ${problems.join("; ")}\n\n${HELP}`);
+            return 1;
+        }
+        return runDoctor({
+            targetDir: target(args),
+            url: option(args, "--url"),
+            json: args.includes("--json"),
+            yes: args.includes("--yes"),
+        });
+    }
+    if (command === "refine") {
+        const problems = optionErrors(args, REFINE_FLAGS, REFINE_VALUE_OPTIONS);
+        if (problems.length > 0) {
+            console.error(`vendo refine: ${problems.join("; ")}\n\n${HELP}`);
+            return 1;
+        }
+        return runRefineCommand({
+            targetDir: target(args),
+            url: option(args, "--url"),
+            modelImport: option(args, "--model-import"),
+            asks: options(args, "--ask"),
+            yes: args.includes("--yes"),
+        });
+    }
+    if (command === "playground") {
+        const { errors, port } = playgroundOptionErrors(args);
+        if (errors.length > 0) {
+            console.error(`vendo playground: ${errors.join("; ")}\n\n${HELP}`);
+            return 1;
+        }
+        return runPlayground({ port, open: !args.includes("--no-open") });
+    }
+    if (command === "sync") {
+        const problems = optionErrors(args, SYNC_FLAGS, SYNC_VALUE_OPTIONS);
+        if (problems.length > 0) {
+            console.error(`vendo sync: ${problems.join("; ")}\n\n${HELP}`);
+            return 1;
+        }
+        return runSync({
+            targetDir: target(args),
+            strict: args.includes("--strict"),
+            url: option(args, "--url"),
+            json: args.includes("--json"),
+            report: args.includes("--report"),
+            apiKey: option(args, "--key"),
+            apiUrl: option(args, "--api-url"),
+        });
+    }
+    console.error(`Unknown command: ${command}\n\n${HELP}`);
+    return 1;
+}
+export function isCliEntrypoint(metaUrl, argv1) {
+    if (argv1 === undefined)
+        return false;
+    try {
+        return metaUrl === pathToFileURL(realpathSync(argv1)).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (isCliEntrypoint(import.meta.url, process.argv[1])) {
+    void main(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+}

package/dist/cloud-apps.d.ts

@@ -0,0 +1,17 @@
+import { type CloudAppsClient } from "@vendoai/apps";
+/** The Cloud share/publish client — the implementation the composition seam
+ * (createVendo) injects into the apps block's CloudAppsClient seam when
+ * VENDO_API_KEY fills the unset slot (adapter rule — see selectConnections in
+ * server.ts; the block itself never reads the environment). Rides the shared
+ * console-client plumbing (cloud-console.ts): Bearer auth + deployment
+ * identity + per-request abort timeout + the honest 401/402 → cloud-required
+ * error table. */
+export interface CloudAppsOptions {
+    apiKey: string;
+    /** Defaults to the Vendo console; the composition seam passes VENDO_CLOUD_URL. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /** Per-request abort budget (default 30s, hosted-store's). */
+    timeoutMs?: number;
+}
+export declare function cloudApps(options: CloudAppsOptions): CloudAppsClient;

package/dist/cloud-apps.js

@@ -0,0 +1,46 @@
+import { publishRecordSchema, shareSnapshotSchema, } from "@vendoai/apps";
+import { consoleSender, raiseCloudError } from "./cloud-console.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** The console mounts the share/publish surface here. */
+const CONSOLE_APPS_PATH = "/api/v1/apps";
+/** Shared console error table: 401/402 → cloud-required, wire-legal envelope
+ * codes forward as VendoErrors, anything else (unknown codes, 5xx, non-JSON
+ * bodies) rides a plain Error with the server's code attached — never a
+ * "validation" error blaming the caller for the console misbehaving. */
+const raiseAppsError = (response) => raiseCloudError(response, "apps", (code, message) => {
+    throw Object.assign(new Error(message), { code: code ?? "unavailable" });
+});
+export function cloudApps(options) {
+    const base = (options.baseUrl ?? "https://console.vendo.run").replace(/\/$/, "");
+    const send = consoleSender({
+        base,
+        mountPath: CONSOLE_APPS_PATH,
+        apiKey: options.apiKey,
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        fetchImpl: options.fetch ?? globalThis.fetch,
+        raise: raiseAppsError,
+    });
+    const post = async (path, appId, doc, schema) => {
+        const response = await send(path, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ appId, doc }),
+        });
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            // hosted-store's malformed-200 posture: a 2xx that isn't JSON means a
+            // misdeployed Cloud base — the SERVICE misbehaving, never the caller's
+            // fault, so this is a plain Error (not a wire-legal "validation" code
+            // that would blame the share/publish input).
+            throw new Error(`Vendo Cloud apps returned a non-JSON ${response.status} response — check VENDO_CLOUD_URL`);
+        }
+        return schema.parse(payload);
+    };
+    return {
+        share: (appId, doc) => post("/share", appId, doc, shareSnapshotSchema),
+        publish: (appId, doc) => post("/publish", appId, doc, publishRecordSchema),
+    };
+}

package/dist/cloud-console.d.ts

@@ -0,0 +1,32 @@
+/** Console-client plumbing shared by the Cloud adapters (cloudSandbox,
+ * hostedStore, cloudConnections, cloudApps): the wire-legal error table, the
+ * enveloped-error raise, and the key-authed sender. Behavior still comes
+ * ONLY from each adapter's constructor arguments (adapter rule — see
+ * selectSandbox/selectStore in server.ts); nothing here reads the
+ * environment. */
+/** Console error codes forwarded as-is when they are wire-legal VendoError
+ * codes (same posture as the cloudApps share/publish client). The
+ * console's "unavailable"/"unauthorized"/"quota-exhausted" have no VendoError
+ * twin; unknown codes fall to each adapter's own tail, and the 402/401 →
+ * cloud-required mapping handles the meter/key cases. */
+export declare const CLOUD_ERROR_CODES: ReadonlySet<string>;
+export declare const toArrayBuffer: (value: Uint8Array) => ArrayBuffer;
+/** Parse the console's error envelope and throw. The console's meter gate
+ * (quota-exhausted) rides HTTP 402 — the one "pay/upgrade to proceed" signal,
+ * same mapping as cloudConnections. 401 (bad/revoked key) is the same "fix
+ * your Cloud standing" story for the host operator, so it keeps the ENG-295
+ * client's cloud-required mapping — with the server's own message preserved.
+ * Wire-legal codes forward as VendoErrors; anything else (unknown codes, 5xx,
+ * non-JSON bodies) goes to the adapter's own `onUnknownCode` tail. */
+export declare function raiseCloudError(response: Response, service: string, onUnknownCode: (code: string | undefined, message: string) => never): Promise<never>;
+/** The key-authed console sender: Bearer auth + deployment identity (the
+ * console meters usage from real traffic) + per-request abort timeout, raising
+ * through the adapter's own error mapping on any non-2xx. */
+export declare function consoleSender(options: {
+    base: string;
+    mountPath: string;
+    apiKey: string;
+    timeoutMs: number;
+    fetchImpl: typeof fetch;
+    raise: (response: Response) => Promise<never>;
+}): (path: string, init?: RequestInit) => Promise<Response>;

package/dist/cloud-console.js

@@ -0,0 +1,72 @@
+import { VendoError } from "@vendoai/core";
+import { deploymentIdentityHeaders } from "./deployment-identity.js";
+/** Console-client plumbing shared by the Cloud adapters (cloudSandbox,
+ * hostedStore, cloudConnections, cloudApps): the wire-legal error table, the
+ * enveloped-error raise, and the key-authed sender. Behavior still comes
+ * ONLY from each adapter's constructor arguments (adapter rule — see
+ * selectSandbox/selectStore in server.ts); nothing here reads the
+ * environment. */
+/** Console error codes forwarded as-is when they are wire-legal VendoError
+ * codes (same posture as the cloudApps share/publish client). The
+ * console's "unavailable"/"unauthorized"/"quota-exhausted" have no VendoError
+ * twin; unknown codes fall to each adapter's own tail, and the 402/401 →
+ * cloud-required mapping handles the meter/key cases. */
+export const CLOUD_ERROR_CODES = new Set([
+    "validation",
+    "blocked",
+    "not-implemented",
+    "cloud-required",
+    "not-found",
+    "conflict",
+]);
+export const toArrayBuffer = (value) => value.slice().buffer;
+/** Parse the console's error envelope and throw. The console's meter gate
+ * (quota-exhausted) rides HTTP 402 — the one "pay/upgrade to proceed" signal,
+ * same mapping as cloudConnections. 401 (bad/revoked key) is the same "fix
+ * your Cloud standing" story for the host operator, so it keeps the ENG-295
+ * client's cloud-required mapping — with the server's own message preserved.
+ * Wire-legal codes forward as VendoErrors; anything else (unknown codes, 5xx,
+ * non-JSON bodies) goes to the adapter's own `onUnknownCode` tail. */
+export async function raiseCloudError(response, service, onUnknownCode) {
+    let payload;
+    try {
+        payload = JSON.parse(await response.text());
+    }
+    catch {
+        payload = undefined;
+    }
+    const error = typeof payload === "object" && payload !== null && "error" in payload
+        ? payload.error
+        : undefined;
+    const message = typeof error?.message === "string"
+        ? error.message
+        : `Vendo Cloud ${service} request failed with ${response.status}`;
+    if (response.status === 402 || response.status === 401) {
+        throw new VendoError("cloud-required", message);
+    }
+    const code = typeof error?.code === "string" ? error.code : undefined;
+    if (code !== undefined && CLOUD_ERROR_CODES.has(code)) {
+        throw new VendoError(code, message);
+    }
+    return onUnknownCode(code, message);
+}
+/** The key-authed console sender: Bearer auth + deployment identity (the
+ * console meters usage from real traffic) + per-request abort timeout, raising
+ * through the adapter's own error mapping on any non-2xx. */
+export function consoleSender(options) {
+    return async (path, init = {}) => {
+        const response = await options.fetchImpl(`${options.base}${options.mountPath}${path}`, {
+            ...init,
+            headers: {
+                authorization: `Bearer ${options.apiKey}`,
+                accept: "application/json",
+                ...(await deploymentIdentityHeaders()),
+                ...init.headers,
+            },
+            signal: AbortSignal.timeout(options.timeoutMs),
+        });
+        if (!response.ok)
+            await options.raise(response);
+        return response;
+    };
+}

package/dist/cloud-tools.d.ts

@@ -0,0 +1,23 @@
+import { type Connector } from "@vendoai/actions";
+/** The Cloud tools adapter — the execution half of the zero-key Composio
+ * seam (cloudConnections is the account half). Tools list and execute ride
+ * the console's broker (`GET /api/v1/tools`, `POST /api/v1/tools/execute`),
+ * which holds Vendo's Composio credentials and namespaces every call by the
+ * caller's org; this connector never sees a Composio key.
+ *
+ * The connector is named "composio" on purpose: connect-required outcomes,
+ * the connect dock's catalog rows, and connection initiation all carry the
+ * same connector name, so the whole connect-then-use loop stays one broker
+ * from the UI's point of view. */
+export interface CloudToolsOptions {
+    apiKey: string;
+    /** Defaults to the Vendo console; the composition seam passes VENDO_CLOUD_URL. */
+    baseUrl?: string;
+    /** Toolkit scoping, same meaning as composioConnector's `apps`. Unset =
+     * everything the console's catalog advertises (enabled auth configs).
+     * When set, pass the SAME list to cloudConnections({ apps }) so the
+     * connect dock's catalog stays in lockstep with the executable tools. */
+    apps?: string[];
+    fetch?: typeof fetch;
+}
+export declare function cloudTools(options: CloudToolsOptions): Connector;