@vendoai/vendo 0.4.0

package/dist/cloud-tools.js

@@ -0,0 +1,196 @@
+import { composioToolRisk, normalizeToolName } from "@vendoai/actions";
+import { deploymentIdentityHeaders } from "./deployment-identity.js";
+function errorOutcome(message) {
+    return { status: "error", error: { code: "connector-error", message } };
+}
+function withIdentity(outcome, identity) {
+    return Object.assign({}, outcome, { connectorAccount: identity });
+}
+export function cloudTools(options) {
+    const base = (options.baseUrl ?? "https://console.vendo.run").replace(/\/$/, "");
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    let normalizedToRaw = new Map();
+    async function cloudFetch(path, init) {
+        const response = await fetchImpl(`${base}${path}`, {
+            ...init,
+            headers: {
+                authorization: `Bearer ${options.apiKey}`,
+                accept: "application/json",
+                ...(await deploymentIdentityHeaders()),
+                ...(init?.body === undefined ? {} : { "content-type": "application/json" }),
+                ...init?.headers,
+            },
+        });
+        let payload = {};
+        try {
+            payload = await response.json();
+        }
+        catch {
+            // Non-JSON bodies fall through to the caller's status handling.
+        }
+        return { ok: response.ok, status: response.status, payload };
+    }
+    // Connection-scoped tool loading (spec 2026-07-20): without explicit `apps`
+    // the connector is LAZY — nothing fetches eagerly; discovery rides the
+    // console catalog and schemas load per toolkit on expansion.
+    const lazy = options.apps === undefined;
+    const expandedToolkits = new Set();
+    const toolkitToolCache = new Map();
+    let indexPromise;
+    /** One toolkits= fetch, degrade-never-throw (a failed toolkit just loads
+     * nothing this round; the memo is dropped so a later read retries). */
+    function fetchToolkitTools(toolkits) {
+        let promise = toolkitToolCache.get(toolkits);
+        if (!promise) {
+            promise = (async () => {
+                let response;
+                try {
+                    response = await cloudFetch(`/api/v1/tools?toolkits=${encodeURIComponent(toolkits)}`);
+                }
+                catch (error) {
+                    toolkitToolCache.delete(toolkits);
+                    console.warn("[vendo] Vendo Cloud tools broker unreachable; no connector tools loaded:", error instanceof Error ? error.message : error);
+                    return [];
+                }
+                if (!response.ok) {
+                    toolkitToolCache.delete(toolkits);
+                    const message = response.payload.error?.message;
+                    console.warn(`[vendo] Vendo Cloud tools broker returned ${response.status}; no connector tools loaded${typeof message === "string" && message ? `: ${message}` : "."}`);
+                    return [];
+                }
+                const items = response.payload && typeof response.payload === "object"
+                    ? response.payload.tools
+                    : undefined;
+                return (Array.isArray(items) ? items : []);
+            })();
+            toolkitToolCache.set(toolkits, promise);
+        }
+        return promise;
+    }
+    async function buildIndex() {
+        let response;
+        try {
+            response = await cloudFetch("/api/v1/connections/catalog");
+        }
+        catch (error) {
+            indexPromise = undefined;
+            console.warn("[vendo] Vendo Cloud catalog unreachable; connector discovery is empty:", error instanceof Error ? error.message : error);
+            return [];
+        }
+        if (!response.ok) {
+            indexPromise = undefined;
+            console.warn(`[vendo] Vendo Cloud catalog returned ${response.status}; connector discovery is empty.`);
+            return [];
+        }
+        const available = response.payload && typeof response.payload === "object"
+            ? response.payload.available
+            : undefined;
+        if (!Array.isArray(available))
+            return [];
+        return available
+            .filter((entry) => !!entry && typeof entry === "object" && typeof entry.toolkit === "string")
+            .map((entry) => ({
+            toolkit: entry.toolkit,
+            ...(typeof entry.label === "string" ? { label: entry.label } : {}),
+            ...(typeof entry.description === "string" ? { description: entry.description } : {}),
+        }));
+    }
+    return {
+        name: "composio",
+        discoveryIndex: () => (indexPromise ??= buildIndex()),
+        async expandToolkits(toolkits) {
+            if (!lazy)
+                return false;
+            const connectable = new Set((await (indexPromise ??= buildIndex())).map((entry) => entry.toolkit));
+            let changed = false;
+            for (const toolkit of toolkits) {
+                if (!connectable.has(toolkit) || expandedToolkits.has(toolkit))
+                    continue;
+                expandedToolkits.add(toolkit);
+                changed = true;
+            }
+            return changed;
+        },
+        async descriptors() {
+            // The auto-composed cloud default must never brick the host: a thrown
+            // descriptors() fails the ENTIRE registry load, host tools included.
+            // Every fetch below degrades to "no connector tools" with one warn.
+            let items;
+            if (lazy) {
+                if (expandedToolkits.size === 0) {
+                    normalizedToRaw = new Map();
+                    return [];
+                }
+                const lists = await Promise.all([...expandedToolkits].map((toolkit) => fetchToolkitTools(toolkit)));
+                items = lists.flat();
+            }
+            else {
+                items = await fetchToolkitTools(options.apps.join(","));
+            }
+            const nextNormalizedToRaw = new Map();
+            const descriptors = [];
+            for (const item of items) {
+                if (typeof item.slug !== "string" || typeof item.toolkit !== "string")
+                    continue;
+                const name = normalizeToolName(item.toolkit, item.slug);
+                if (nextNormalizedToRaw.has(name))
+                    throw new Error(`Cloud tools name collision: ${name}`);
+                nextNormalizedToRaw.set(name, { raw: item.slug, toolkit: item.toolkit });
+                const tags = Array.isArray(item.tags)
+                    ? item.tags.filter((tag) => typeof tag === "string")
+                    : undefined;
+                descriptors.push({
+                    name,
+                    description: typeof item.description === "string" ? item.description : item.slug,
+                    inputSchema: item.inputParameters && typeof item.inputParameters === "object" && !Array.isArray(item.inputParameters)
+                        ? item.inputParameters
+                        : {},
+                    // The same curated risk labels BYO Composio tools get — the guard
+                    // and approval cards behave identically across postures.
+                    risk: composioToolRisk(item.slug, item.toolkit, tags),
+                });
+            }
+            // Swapped atomically so a concurrent execute() never sees a half map.
+            normalizedToRaw = nextNormalizedToRaw;
+            return descriptors;
+        },
+        async execute(call, ctx) {
+            const entry = normalizedToRaw.get(call.tool);
+            if (!entry) {
+                return { status: "error", error: { code: "not-found", message: `Unknown cloud tool: ${call.tool}` } };
+            }
+            const subject = ctx.principal.subject;
+            const identity = {
+                connector: "composio",
+                toolkit: entry.toolkit,
+                entityId: subject,
+                credential: "per-principal",
+            };
+            try {
+                const response = await cloudFetch("/api/v1/tools/execute", {
+                    method: "POST",
+                    body: JSON.stringify({
+                        subject,
+                        toolkit: entry.toolkit,
+                        tool: entry.raw,
+                        arguments: call.args,
+                    }),
+                });
+                if (!response.ok) {
+                    const message = response.payload.error?.message;
+                    return withIdentity(errorOutcome(typeof message === "string" && message
+                        ? message
+                        : `Vendo Cloud tool execution failed with ${response.status}`), identity);
+                }
+                const outcome = response.payload.outcome;
+                if (!outcome || typeof outcome !== "object") {
+                    return withIdentity(errorOutcome("Vendo Cloud tool execution returned no outcome"), identity);
+                }
+                return withIdentity(outcome, identity);
+            }
+            catch (error) {
+                return withIdentity(errorOutcome(error instanceof Error ? error.message : "Vendo Cloud tool execution failed"), identity);
+            }
+        },
+    };
+}

package/dist/connections.d.ts

@@ -0,0 +1,71 @@
+import { type Principal } from "@vendoai/core";
+import type { Connector, ConnectorAccount, ConnectorConnections } from "@vendoai/actions";
+export interface InitiateOptions {
+    connector?: string;
+    toolkit: string;
+    callbackUrl?: string;
+}
+export interface InitiatedConnection {
+    id: string;
+    connector: string;
+    redirectUrl: string;
+}
+/** One row of the connect dock's auto catalog: a toolkit a user could finish
+ * connecting, tagged with the broker that would carry it. */
+export interface ConnectableToolkit {
+    toolkit: string;
+    connector: string;
+    label?: string;
+    /** One-line capability blurb — feeds the OSS discovery index. */
+    description?: string;
+}
+/** 04-actions §3 (block-actions design §B) — the umbrella's per-principal
+ * connected-accounts surface. Which implementation composes is decided at the
+ * seam, never in here (adapter rule — see selectConnections in server.ts).
+ * Composio is the sole broker; two postures:
+ *   - "byo": the host's own connector (its Composio key) carries connections;
+ *   - "cloud": connections ride the Vendo Cloud broker endpoint using Vendo's
+ *     Composio credentials — cloud users bring zero keys.
+ * Subject scoping IS the security model: every call passes exactly the
+ * resolved principal's subject; no caller-supplied subject exists on the wire. */
+export interface ConnectionsService {
+    posture: "byo" | "cloud" | false;
+    list(principal: Principal): Promise<ConnectorAccount[]>;
+    initiate(principal: Principal, options: InitiateOptions): Promise<InitiatedConnection>;
+    status(principal: Principal, connector: string, connectionId: string): Promise<ConnectorAccount | null>;
+    disconnect(principal: Principal, connector: string, connectionId: string): Promise<void>;
+    /** The connect dock's auto catalog — host-level (every principal sees the
+     * same rows), unlike everything above. Empty when nothing is connectable. */
+    catalog(): Promise<ConnectableToolkit[]>;
+}
+/** The BYO capability predicate — the same test the composition seam selects
+ * on and byoConnections builds brokers from. */
+export declare function hasConnections(connector: Connector): connector is Connector & {
+    connections: ConnectorConnections;
+};
+/** The BYO adapter: connections live on the host's own connector(s), because
+ * they must live where the connector executes. Built from every passed
+ * connector that carries a connections capability. */
+export declare function byoConnections(connectors: Connector[]): ConnectionsService;
+export interface CloudConnectionsOptions {
+    apiKey: string;
+    /** Defaults to the Vendo console; the composition seam passes VENDO_CLOUD_URL. */
+    baseUrl?: string;
+    /** Catalog scoping, mirroring cloudTools' `apps`: a host that scopes its
+     * cloud tools explicitly passes the same list here so the connect dock
+     * never advertises a toolkit the agent cannot invoke. Unset = everything
+     * the console's catalog serves. */
+    apps?: string[];
+    fetch?: typeof fetch;
+    /** Per-request abort budget (default 30s, hosted-store's) — a hung console
+     * must never wedge the connections surface. */
+    timeoutMs?: number;
+}
+/** The Cloud adapter — the OSS side of the zero-key cloud seam: same surface,
+ * brokered by the Vendo Cloud console (which holds Vendo's Composio
+ * credentials). The console implementation is out of scope here; this defines
+ * the wire it must serve. */
+export declare function cloudConnections(options: CloudConnectionsOptions): ConnectionsService;
+/** The no-broker fallback adapter: listing is honestly empty (the panel
+ * renders an empty state), any mutation explains what to configure. */
+export declare function unconfiguredConnections(): ConnectionsService;

package/dist/connections.js

@@ -0,0 +1,192 @@
+import { VendoError } from "@vendoai/core";
+import { consoleSender, raiseCloudError } from "./cloud-console.js";
+/** Subjects the runtime mints for machine principals (automations webhook
+ * triggers today; the reserved `vendo:` namespace going forward). A synthetic
+ * subject must never accrue human connected accounts — and it has no browser
+ * to complete an OAuth redirect anyway. */
+const SYNTHETIC_SUBJECT_PREFIXES = ["webhook:", "vendo:"];
+function guardInitiatePrincipal(principal) {
+    if (principal.ephemeral === true) {
+        throw new VendoError("blocked", "connecting external accounts requires a signed-in user; sign in first");
+    }
+    if (SYNTHETIC_SUBJECT_PREFIXES.some((prefix) => principal.subject.startsWith(prefix))) {
+        throw new VendoError("validation", "reserved synthetic subjects cannot hold connected accounts");
+    }
+}
+function guardCallbackUrl(callbackUrl) {
+    if (callbackUrl === undefined)
+        return;
+    let parsed;
+    try {
+        parsed = new URL(callbackUrl);
+    }
+    catch {
+        throw new VendoError("validation", "callbackUrl must be an absolute http(s) URL");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new VendoError("validation", "callbackUrl must be an absolute http(s) URL");
+    }
+}
+/** The BYO capability predicate — the same test the composition seam selects
+ * on and byoConnections builds brokers from. */
+export function hasConnections(connector) {
+    return connector.connections !== undefined;
+}
+/** The BYO adapter: connections live on the host's own connector(s), because
+ * they must live where the connector executes. Built from every passed
+ * connector that carries a connections capability. */
+export function byoConnections(connectors) {
+    const brokers = connectors
+        .filter(hasConnections)
+        .map((connector) => ({ name: connector.name, connections: connector.connections }));
+    if (brokers.length === 0) {
+        throw new VendoError("validation", "byoConnections requires at least one connector with a connections capability");
+    }
+    function broker(name) {
+        if (name === undefined)
+            return brokers[0];
+        const found = brokers.find((candidate) => candidate.name === name);
+        if (!found)
+            throw new VendoError("not-found", `no connector named ${name} supports connections`);
+        return found;
+    }
+    return {
+        posture: "byo",
+        async list(principal) {
+            const lists = await Promise.all(brokers.map((candidate) => candidate.connections.list(principal.subject)));
+            return lists.flat();
+        },
+        async initiate(principal, options) {
+            guardInitiatePrincipal(principal);
+            guardCallbackUrl(options.callbackUrl);
+            const target = broker(options.connector);
+            const initiated = await target.connections.initiate(principal.subject, options.toolkit, {
+                ...(options.callbackUrl === undefined ? {} : { callbackUrl: options.callbackUrl }),
+            });
+            return { ...initiated, connector: target.name };
+        },
+        async status(principal, connector, connectionId) {
+            return broker(connector).connections.status(principal.subject, connectionId);
+        },
+        async disconnect(principal, connector, connectionId) {
+            await broker(connector).connections.disconnect(principal.subject, connectionId);
+        },
+        async catalog() {
+            const catalogs = await Promise.all(brokers.map(async (candidate) => {
+                const entries = await candidate.connections.listConnectable?.() ?? [];
+                return entries.map((entry) => ({ ...entry, connector: candidate.name }));
+            }));
+            return catalogs.flat();
+        },
+    };
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** The shared console error table (cloud-console.ts): 401/402 → cloud-required
+ * (fix your Cloud standing), wire-legal envelope codes forward as VendoErrors,
+ * and 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 (hosted-store's posture). */
+const raiseConnectionsError = (response) => raiseCloudError(response, "connections", (code, message) => {
+    throw Object.assign(new Error(message), { code: code ?? "unavailable" });
+});
+/** The Cloud adapter — the OSS side of the zero-key cloud seam: same surface,
+ * brokered by the Vendo Cloud console (which holds Vendo's Composio
+ * credentials). The console implementation is out of scope here; this defines
+ * the wire it must serve. */
+export function cloudConnections(options) {
+    const base = (options.baseUrl ?? "https://console.vendo.run").replace(/\/$/, "");
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    // The key-authed console sender (cloud-console.ts): Bearer auth + deployment
+    // identity (the console meters usage from real traffic) + per-request abort
+    // timeout, raising through the shared error table on any non-2xx.
+    const send = consoleSender({
+        base,
+        mountPath: "",
+        apiKey: options.apiKey,
+        timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        fetchImpl,
+        raise: raiseConnectionsError,
+    });
+    async function cloudFetch(path, init) {
+        const response = await send(path, {
+            ...init,
+            headers: {
+                ...(init?.body === undefined ? {} : { "content-type": "application/json" }),
+                ...init?.headers,
+            },
+        });
+        try {
+            return await response.json();
+        }
+        catch {
+            // A 2xx that isn't JSON means a misdeployed Cloud base (an SPA host or
+            // reverse proxy that 200s unknown paths with text/html). Fail loudly —
+            // hosted-store's malformed-200 posture — instead of reading as an empty
+            // connections list (or a not-found account) forever.
+            throw new VendoError("validation", `Vendo Cloud connections returned a non-JSON ${response.status} response — check VENDO_CLOUD_URL`);
+        }
+    }
+    const subjectQuery = (principal) => `subject=${encodeURIComponent(principal.subject)}`;
+    return {
+        posture: "cloud",
+        async list(principal) {
+            const payload = await cloudFetch(`/api/v1/connections?${subjectQuery(principal)}`);
+            if (!Array.isArray(payload.connections)) {
+                // A 2xx without the envelope is the SERVICE misbehaving — never
+                // indistinguishable from a genuinely empty connections panel.
+                throw new VendoError("validation", "Vendo Cloud connections returned an invalid list response (no connections array)");
+            }
+            return payload.connections;
+        },
+        async initiate(principal, options) {
+            guardInitiatePrincipal(principal);
+            guardCallbackUrl(options.callbackUrl);
+            const payload = await cloudFetch("/api/v1/connections/initiate", {
+                method: "POST",
+                body: JSON.stringify({
+                    subject: principal.subject,
+                    toolkit: options.toolkit,
+                    ...(options.connector === undefined ? {} : { connector: options.connector }),
+                    ...(options.callbackUrl === undefined ? {} : { callbackUrl: options.callbackUrl }),
+                }),
+            });
+            if (typeof payload.id !== "string" || typeof payload.redirectUrl !== "string") {
+                throw new VendoError("validation", "Vendo Cloud connect initiation returned no redirect URL");
+            }
+            return {
+                id: payload.id,
+                connector: typeof payload.connector === "string" ? payload.connector : "composio",
+                redirectUrl: payload.redirectUrl,
+            };
+        },
+        async status(principal, connector, connectionId) {
+            const payload = await cloudFetch(`/api/v1/connections/${encodeURIComponent(connectionId)}?${subjectQuery(principal)}&connector=${encodeURIComponent(connector)}`);
+            return payload.connection ?? null;
+        },
+        async disconnect(principal, connector, connectionId) {
+            await cloudFetch(`/api/v1/connections/${encodeURIComponent(connectionId)}?${subjectQuery(principal)}&connector=${encodeURIComponent(connector)}`, { method: "DELETE" });
+        },
+        async catalog() {
+            const payload = await cloudFetch("/api/v1/connections/catalog");
+            const available = Array.isArray(payload.available) ? payload.available : [];
+            return options.apps === undefined
+                ? available
+                : available.filter((entry) => options.apps.includes(entry.toolkit));
+        },
+    };
+}
+/** The no-broker fallback adapter: listing is honestly empty (the panel
+ * renders an empty state), any mutation explains what to configure. */
+export function unconfiguredConnections() {
+    const refuse = () => {
+        throw new VendoError("not-implemented", "connected accounts are not configured: pass a Composio connector (composioConnector) to createVendo({ connectors }) or set VENDO_API_KEY for the Vendo Cloud broker");
+    };
+    return {
+        posture: false,
+        list: async () => [],
+        initiate: async () => refuse(),
+        status: async () => refuse(),
+        disconnect: async () => refuse(),
+        catalog: async () => [],
+    };
+}

package/dist/deployment-identity.d.ts

@@ -0,0 +1,12 @@
+/** Deployment-identity headers (cloud definition, interaction model): every
+ * key-authenticated Vendo Cloud request carries `x-vendo-deployment-host` and
+ * `x-vendo-deployment-name`; the console's shared auth middleware upserts the
+ * deployment inventory and meters usage from these on real service calls —
+ * there is no heartbeat. Shared by the CLI cloud client and the runtime Cloud
+ * adapters (connections, sandbox), so this module carries NO static Node
+ * import: builtins load through the runtime accessor (server.ts precedent)
+ * and every lookup fails soft to "unknown" on edge/Worker targets — identity
+ * headers must never take a request down. The console truncates and fails
+ * open on its side (parseDeploymentHeaders), so sending is always safe. */
+/** The two identity headers for a key-authenticated Cloud request. */
+export declare function deploymentIdentityHeaders(): Promise<Record<string, string>>;

package/dist/deployment-identity.js

@@ -0,0 +1,69 @@
+/** Deployment-identity headers (cloud definition, interaction model): every
+ * key-authenticated Vendo Cloud request carries `x-vendo-deployment-host` and
+ * `x-vendo-deployment-name`; the console's shared auth middleware upserts the
+ * deployment inventory and meters usage from these on real service calls —
+ * there is no heartbeat. Shared by the CLI cloud client and the runtime Cloud
+ * adapters (connections, sandbox), so this module carries NO static Node
+ * import: builtins load through the runtime accessor (server.ts precedent)
+ * and every lookup fails soft to "unknown" on edge/Worker targets — identity
+ * headers must never take a request down. The console truncates and fails
+ * open on its side (parseDeploymentHeaders), so sending is always safe. */
+function runtimeProcess() {
+    return globalThis.process;
+}
+function builtinModule(id) {
+    try {
+        return runtimeProcess()?.getBuiltinModule?.(id);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Non-Latin-1 or CR/LF header values make fetch throw "Cannot convert
+ *  argument to a ByteString"; identity headers must never take a command
+ *  down, so strip to printable ASCII and never send an empty value. */
+function headerSafe(value) {
+    const printable = value.replace(/[^\x20-\x7e]+/g, "").trim();
+    return printable.length > 0 ? printable : "unknown";
+}
+/** Name is the nearest project identity: the cwd package name, cached per
+ *  directory (a process can chdir between calls). */
+const deploymentNames = new Map();
+function resolveDeploymentName(cwd) {
+    let name = deploymentNames.get(cwd);
+    if (name === undefined) {
+        name = (async () => {
+            const path = builtinModule("node:path");
+            const fs = builtinModule("node:fs");
+            try {
+                const manifestPath = path === undefined ? `${cwd}/package.json` : path.join(cwd, "package.json");
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+                if (typeof manifest.name === "string" && manifest.name.length > 0)
+                    return manifest.name;
+            }
+            catch {
+                // no manifest (or no filesystem) — fall through to the directory name
+            }
+            if (path !== undefined)
+                return path.basename(cwd);
+            return cwd.split(/[/\\]/).filter(Boolean).pop() ?? "";
+        })();
+        deploymentNames.set(cwd, name);
+    }
+    return name;
+}
+/** The two identity headers for a key-authenticated Cloud request. */
+export async function deploymentIdentityHeaders() {
+    const os = builtinModule("node:os");
+    let cwd;
+    try {
+        cwd = runtimeProcess()?.cwd?.();
+    }
+    catch {
+        cwd = undefined;
+    }
+    return {
+        "x-vendo-deployment-host": headerSafe(os === undefined ? "" : os.hostname()),
+        "x-vendo-deployment-name": headerSafe(cwd === undefined ? "" : await resolveDeploymentName(cwd)),
+    };
+}

package/dist/dev-creds/model.d.ts

@@ -0,0 +1,65 @@
+import type { LanguageModel } from "ai";
+import { type DevCredential } from "./resolve.js";
+/**
+ * `devModel()` — the env-resolving model createVendo composes when the host
+ * passes none (install-dx v1: `model` is optional; real keys only). It IS an
+ * ai-SDK LanguageModel (BYO seam unchanged, 03-agent §1), resolving the
+ * credential lazily on first use:
+ *
+ * - env-key rungs delegate to the host-installed @ai-sdk provider (^3, spec
+ *   v3) with full native tool calling — works in production too.
+ * - VENDO_API_KEY delegates to the Vendo Cloud model gateway: the
+ *   host-installed @ai-sdk/anthropic pointed at `<console>/api/v1`, whose
+ *   Anthropic-compatible /messages endpoint serves the metered dev-mode
+ *   allowance under curated model aliases (vendo-default by default).
+ * - nothing available → every call fails with the exact instructions.
+ */
+export interface DevModelOptions {
+    /** Host app root; providers resolve from here. Default cwd. */
+    root?: string;
+    env?: Record<string, string | undefined>;
+    /** Test seam for host-module resolution (providers). */
+    importModule?: (root: string, specifier: string) => Promise<Record<string, unknown>>;
+}
+interface LanguageModelV3Like {
+    specificationVersion: "v3";
+    provider: string;
+    modelId: string;
+    supportedUrls: Record<string, RegExp[]>;
+    doGenerate(options: unknown): PromiseLike<unknown>;
+    doStream(options: unknown): PromiseLike<unknown>;
+}
+type Resolution = {
+    mode: "delegate";
+    credential: DevCredential;
+    model: LanguageModelV3Like;
+} | {
+    mode: "unavailable";
+    credential: DevCredential;
+    message: string;
+};
+export declare const NO_CREDENTIAL_MESSAGE: string;
+export declare class DevModelController {
+    private readonly root;
+    private readonly env;
+    private readonly importModule;
+    private resolution;
+    private announced;
+    constructor(options?: DevModelOptions);
+    /** Resolve the credential once per process; state it on the server log once.
+     *  An unavailable resolution logs its full instructions HERE — the wire
+     *  deliberately shows clients only a generic error, so the operator's
+     *  terminal is where the honest message must land. */
+    resolve(): Promise<Resolution>;
+    private announce;
+    /** The shared delegate rung: load the provider module (an install failure
+     *  resolves unavailable with the exact install command), pick the model id
+     *  (env override or the spec default), and hand the factory-built model back. */
+    private delegate;
+    private resolveOnce;
+    doGenerate(callOptions: unknown): Promise<unknown>;
+    doStream(callOptions: unknown): Promise<unknown>;
+}
+/** The env-resolving model (see module doc). */
+export declare function devModel(options?: DevModelOptions): LanguageModel;
+export {};