@vendoai/vendo 0.4.0

package/dist/sandbox.js

@@ -0,0 +1,389 @@
+import { VendoError } from "@vendoai/core";
+import { deploymentIdentityHeaders } from "./deployment-identity.js";
+import { CLOUD_BOX_PORT, CLOUD_SANDBOX_PATH, CLOUD_SNAPSHOT_REF_PREFIX, CLOUD_SNAPSHOTS_SUBPATH, CONSOLE_SNAPSHOT_REF_PREFIX, } from "./sandbox-wire.js";
+/** Console error codes forwarded as-is when they are wire-legal VendoError
+ * codes (same posture as the apps block's cloud share/publish client). The
+ * console's "unavailable"/"quota-exhausted" have no VendoError twin; they fall
+ * to sandbox-unavailable and the 402 → cloud-required mapping respectively. */
+const CLOUD_ERROR_CODES = new Set([
+    "validation",
+    "blocked",
+    "not-implemented",
+    "cloud-required",
+    "not-found",
+    "conflict",
+]);
+/** Same default as the e2b adapter and the retired ENG-295 broker client:
+ * generous enough for a slow machine boot, small enough that a hung console
+ * request can't wedge a generation forever. */
+const DEFAULT_TIMEOUT_MS = 300_000;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const toBytes = (data) => typeof data === "string" ? encoder.encode(data) : data;
+const toArrayBuffer = (value) => value.slice().buffer;
+/** btoa/atob-based codecs (the console speaks base64 JSON envelopes); chunked
+ * like the console's own encoder, and Buffer-free so the umbrella's server
+ * surface keeps loading on edge/Worker targets. */
+function encodeBase64(bytes) {
+    let binary = "";
+    for (let offset = 0; offset < bytes.length; offset += 32_768) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + 32_768));
+    }
+    return btoa(binary);
+}
+function decodeBase64(value) {
+    try {
+        return Uint8Array.from(atob(value), (character) => character.charCodeAt(0));
+    }
+    catch {
+        // Console garbage is the SERVICE misbehaving, never the caller's fault —
+        // same posture as every malformed-success branch below.
+        throw new VendoError("sandbox-unavailable", "Vendo Cloud sandbox returned invalid base64 content");
+    }
+}
+async function raiseCloudError(response) {
+    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 sandbox request failed with ${response.status}`;
+    // 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.
+    if (response.status === 402 || response.status === 401) {
+        throw new VendoError("cloud-required", message);
+    }
+    const code = typeof error?.code === "string" && CLOUD_ERROR_CODES.has(error.code)
+        ? error.code
+        : "sandbox-unavailable";
+    throw new VendoError(code, message);
+}
+const parsePort = (env) => {
+    const port = Number(env.PORT ?? CLOUD_BOX_PORT);
+    return Number.isInteger(port) && port > 0 && port <= 65_535 ? port : CLOUD_BOX_PORT;
+};
+const toBase64Url = (value) => encodeBase64(encoder.encode(value)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+const encodeSnapshotRef = (state) => `${CLOUD_SNAPSHOT_REF_PREFIX}${toBase64Url(JSON.stringify(state))}`;
+const decodeSnapshotRef = (snapshotRef) => {
+    try {
+        if (!snapshotRef.startsWith(CLOUD_SNAPSHOT_REF_PREFIX)
+            || snapshotRef.length <= CLOUD_SNAPSHOT_REF_PREFIX.length) {
+            throw new Error("unknown prefix");
+        }
+        const payload = snapshotRef.slice(CLOUD_SNAPSHOT_REF_PREFIX.length)
+            .replaceAll("-", "+").replaceAll("_", "/");
+        const state = JSON.parse(decoder.decode(Uint8Array.from(atob(payload), (character) => character.charCodeAt(0))));
+        if (state.version !== 2
+            || typeof state.machineId !== "string" || state.machineId.length === 0
+            || typeof state.ref !== "string" || !state.ref.startsWith(CONSOLE_SNAPSHOT_REF_PREFIX)) {
+            throw new Error("invalid payload");
+        }
+        if (state.allowedDomains !== undefined && !(Array.isArray(state.allowedDomains)
+            && state.allowedDomains.every((host) => typeof host === "string"))) {
+            throw new Error("invalid allowedDomains policy");
+        }
+        if (state.port !== undefined && !(Number.isInteger(state.port)
+            && state.port > 0 && state.port <= 65_535)) {
+            throw new Error("invalid port");
+        }
+        return {
+            version: 2,
+            machineId: state.machineId,
+            ref: state.ref,
+            ...(state.allowedDomains === undefined ? {} : { allowedDomains: [...state.allowedDomains] }),
+            ...(state.port === undefined ? {} : { port: state.port }),
+        };
+    }
+    catch {
+        throw new VendoError("validation", `Vendo Cloud snapshot references must start with "${CLOUD_SNAPSHOT_REF_PREFIX}" and carry a valid payload`);
+    }
+};
+/** True exactly for the "that state is already gone" answer that the seam's
+ * idempotent transitions (destroy twice, stop of a dead machine) absorb. */
+const isGone = (error) => error instanceof VendoError && error.code === "not-found";
+/** The Cloud sandbox adapter — the OSS side of the managed-sandbox seam: the
+ * execution-v2 SandboxAdapter speaking HTTP to the console's /api/v1/sandboxes
+ * routes (Vendo's pooled provider capacity, metered as sandbox_minutes). The
+ * wire contract — the ARTIFACT model, verified live — lives in
+ * sandbox-wire.ts. Cloned from cloudConnections' shape: behavior comes ONLY
+ * from constructor arguments (adapter rule — see selectSandbox in server.ts);
+ * the adapter never reads the environment.
+ *
+ * Provider particulars, versus the e2b reference port:
+ * - Snapshots are persistent artifacts that survive the machine; resume
+ *   boots a NEW machine from one (fork when the source lives, wake when it
+ *   is gone) and inherits NO network config, so every resume sends the
+ *   applicable allowlist explicitly — the ref-recorded one bare, the
+ *   caller's SandboxResumePolicy when a wake re-polices (Lane E replace
+ *   semantics, native on the wire).
+ * - stop() destroys the machine: Cloud has no pause, and with artifacts
+ *   surviving it, snapshot-then-destroy IS the sleep semantics; previously
+ *   minted refs stay valid through it (the seam law).
+ * - Composite refs: the seam sees `vendo:v2:<base64url state>` carrying the
+ *   console artifact ref, the source machine id (destroy-by-ref reaps a
+ *   still-running source best-effort before the artifact GC), and the
+ *   snapshot-time allowlist a bare resume re-applies.
+ * - `spec.template` is dropped from the wire: the create route takes none —
+ *   the pooled base image (Node + the in-box agent) is Cloud's own.
+ *
+ * The machine object also carries adapter-private exec/files/url used for
+ * live-lane bootstrap and diagnostics — NOT part of the public seam (the
+ * in-box agent owns the inside of the box). */
+export function cloudSandbox(options) {
+    const base = (options.baseUrl ?? "https://console.vendo.run").replace(/\/$/, "");
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const send = async (path, init = {}) => {
+        const response = await fetchImpl(`${base}${CLOUD_SANDBOX_PATH}${path}`, {
+            ...init,
+            headers: {
+                authorization: `Bearer ${options.apiKey}`,
+                accept: "application/json",
+                // Interaction model: key-authed Cloud requests carry the deployment
+                // identity; the console meters usage from real traffic.
+                ...(await deploymentIdentityHeaders()),
+                ...init.headers,
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok)
+            await raiseCloudError(response);
+        return response;
+    };
+    const sendJson = async (path, method, body) => {
+        const response = await send(path, {
+            method,
+            ...(body === undefined ? {} : {
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(body),
+            }),
+        });
+        try {
+            return await response.json();
+        }
+        catch {
+            return {};
+        }
+    };
+    const parseHandle = (payload) => {
+        const handle = payload;
+        if (typeof handle.id !== "string" || typeof handle.url !== "string") {
+            throw new VendoError("sandbox-unavailable", "Vendo Cloud sandbox returned no machine handle");
+        }
+        return { id: handle.id, url: handle.url };
+    };
+    const wrap = (handle, state) => {
+        const prefix = `/${encodeURIComponent(handle.id)}`;
+        /** POST /{id}/snapshot — mint a persistent artifact; the source keeps running. */
+        const mintArtifact = async () => {
+            const payload = await sendJson(`${prefix}/snapshot`, "POST");
+            if (typeof payload.ref !== "string" || payload.ref.length === 0) {
+                throw new VendoError("sandbox-unavailable", "Vendo Cloud sandbox returned no snapshot reference");
+            }
+            // A ref this adapter would itself refuse to carry must never reach a
+            // document — reject it as console garbage here instead.
+            if (!payload.ref.startsWith(CONSOLE_SNAPSHOT_REF_PREFIX)
+                || payload.ref.length <= CONSOLE_SNAPSHOT_REF_PREFIX.length) {
+                throw new VendoError("sandbox-unavailable", `Vendo Cloud sandbox returned a foreign snapshot reference (expected the "${CONSOLE_SNAPSHOT_REF_PREFIX}" prefix)`);
+            }
+            return payload.ref;
+        };
+        const remove = async () => {
+            try {
+                await sendJson(prefix, "DELETE");
+            }
+            catch (error) {
+                if (!isGone(error))
+                    throw error;
+            }
+        };
+        // Seam rule: sleeping or destroying twice is not an error, and destroy is
+        // final. The one-shot promises make that hold under concurrency too —
+        // each transition is assigned synchronously, so racing callers share one
+        // console call chain, and a destroy during an in-flight stop serializes
+        // after it (e2b-adapter pattern).
+        let sleeping;
+        let destroying;
+        return {
+            id: handle.id,
+            async request(req) {
+                let payload;
+                try {
+                    payload = await sendJson(`${prefix}/request`, "POST", {
+                        method: req.method,
+                        path: req.path.startsWith("/") ? req.path : `/${req.path}`,
+                        // Absent port targets the canonical box port server-side; explicit
+                        // ports (e.g. the in-box agent control port) route as-is.
+                        ...(req.port === undefined ? {} : { port: req.port }),
+                        ...(req.headers === undefined ? {} : { headers: req.headers }),
+                        ...(req.body === undefined ? {} : { body_b64: encodeBase64(toBytes(req.body)) }),
+                    });
+                }
+                catch (error) {
+                    // Wave 7 — the seam's dead-machine signal. Cloud stop is final (no
+                    // pause), so a conflict ("Sandbox is stopped") on the DATA path
+                    // means the sweep destroyed the machine out from under this handle,
+                    // exactly like a purged id's not-found: both become the thrown
+                    // not-found the lifecycle's eviction/re-wake recovery keys on.
+                    if (error instanceof VendoError && error.code === "conflict") {
+                        throw new VendoError("not-found", `Vendo Cloud sandbox ${handle.id} is gone (destroyed by the provider): ${error.message}`);
+                    }
+                    throw error;
+                }
+                const proxied = payload;
+                if (typeof proxied.status !== "number" || typeof proxied.body_b64 !== "string") {
+                    throw new VendoError("sandbox-unavailable", "Vendo Cloud sandbox returned an invalid proxy response");
+                }
+                const headers = typeof proxied.headers === "object" && proxied.headers !== null
+                    ? Object.fromEntries(Object.entries(proxied.headers)
+                        .filter((entry) => typeof entry[1] === "string"))
+                    : {};
+                return { status: proxied.status, headers, body: decodeBase64(proxied.body_b64) };
+            },
+            async snapshot() {
+                // A checkpoint through a machine object that already slept or was
+                // destroyed is a caller bug — say so crisply instead of relaying
+                // whatever the console answers for the dead machine.
+                if (sleeping !== undefined || destroying !== undefined) {
+                    throw new VendoError("conflict", "the machine is asleep or destroyed; resume its snapshot ref instead of checkpointing it");
+                }
+                return encodeSnapshotRef({
+                    version: 2,
+                    machineId: handle.id,
+                    ref: await mintArtifact(),
+                    ...(state.allowedDomains === undefined ? {} : { allowedDomains: [...state.allowedDomains] }),
+                    port: state.port,
+                });
+            },
+            async stop() {
+                if (destroying !== undefined) {
+                    await destroying;
+                    return;
+                }
+                // Cloud sleep IS destruction: there is no pause, and snapshot
+                // artifacts survive the machine — the sleep flows mint their ref
+                // BEFORE stopping (machine-lifecycle.ts) and wake by resuming it.
+                sleeping ??= remove();
+                await sleeping;
+            },
+            async destroy() {
+                destroying ??= (sleeping ?? Promise.resolve())
+                    .catch(() => undefined)
+                    .then(remove);
+                await destroying;
+            },
+            // ——— adapter-private below this line (live-lane bootstrap + diagnostics) ———
+            async exec(cmd, execOptions) {
+                const payload = await sendJson(`${prefix}/exec`, "POST", {
+                    cmd,
+                    ...(execOptions?.cwd === undefined ? {} : { cwd: execOptions.cwd }),
+                    ...(execOptions?.timeoutMs === undefined ? {} : { timeout_ms: execOptions.timeoutMs }),
+                });
+                if (typeof payload.code !== "number") {
+                    throw new VendoError("sandbox-unavailable", "Vendo Cloud sandbox returned an invalid exec response");
+                }
+                return {
+                    code: payload.code,
+                    stdout: typeof payload.stdout === "string" ? payload.stdout : "",
+                    stderr: typeof payload.stderr === "string" ? payload.stderr : "",
+                };
+            },
+            files: {
+                async read(path) {
+                    const response = await send(`${prefix}/files?path=${encodeURIComponent(path)}`);
+                    return new Uint8Array(await response.arrayBuffer());
+                },
+                async write(path, bytes) {
+                    await send(`${prefix}/files?path=${encodeURIComponent(path)}`, {
+                        method: "PUT",
+                        headers: { "content-type": "application/octet-stream" },
+                        body: toArrayBuffer(toBytes(bytes)),
+                    });
+                },
+                async list(dir) {
+                    const payload = await sendJson(`${prefix}/files/list?dir=${encodeURIComponent(dir)}`, "GET");
+                    return Array.isArray(payload.entries)
+                        ? payload.entries.filter((entry) => typeof entry === "string")
+                        : [];
+                },
+            },
+            async url(port) {
+                // Wave 4 (layer 3) — the browser→box serving path. The handle URL
+                // from create/resume IS the canonical-port ingress: single-label
+                // `<id-suffix>-m.vendo.run` as shipped by the console (vendo-web
+                // #85; -m is a SUFFIX because Cloudflare routes only allow leading
+                // wildcards, `*-m.vendo.run/*`). Other ports insert before the
+                // suffix — `<id-suffix>-<port>-m.vendo.run` — matching the
+                // machine-proxy parse (sandbox-wire.ts ingress entry). Hosts
+                // without a -m label (custom consoles) keep the e2b-style prefix.
+                const target = port ?? state.port;
+                if (target === CLOUD_BOX_PORT)
+                    return handle.url;
+                const ingress = new URL(handle.url);
+                const suffixed = /^(.+)-m(\..+)$/.exec(ingress.host);
+                ingress.host = suffixed === null
+                    ? `${target}-${ingress.host}`
+                    : `${suffixed[1]}-${target}-m${suffixed[2]}`;
+                return ingress.origin;
+            },
+        };
+    };
+    return {
+        async create(spec) {
+            // spec.template is dropped: the create route takes none — the pooled
+            // base image (Node + the in-box agent harness) is Cloud's own
+            // (sandbox-wire.ts).
+            return wrap(parseHandle(await sendJson("", "POST", {
+                env: spec.env,
+                // Seam semantics carried verbatim: absent = unrestricted, [] = deny-all
+                // (deny-by-default lives ABOVE the seam — Lane E's grant flow).
+                ...(spec.allowedDomains === undefined ? {} : { egress: [...spec.allowedDomains] }),
+                // Defensive copy: later refs must record the policy the machine was
+                // CREATED with, immune to caller-side mutation of the array.
+            })), {
+                allowedDomains: spec.allowedDomains === undefined ? undefined : [...spec.allowedDomains],
+                port: parsePort(spec.env),
+            });
+        },
+        async resume(snapshotRef, policy) {
+            const state = decodeSnapshotRef(snapshotRef);
+            // The new machine inherits NO network config from the artifact
+            // (sandbox-wire.ts), so every resume states the applicable allowlist:
+            // Lane E's replace semantics when the caller re-polices the wake, the
+            // ref-recorded snapshot-time policy otherwise. undefined stays the
+            // seam's "unrestricted" (absent field on the wire).
+            const allowedDomains = policy === undefined ? state.allowedDomains : policy.allowedDomains;
+            return wrap(parseHandle(await sendJson("/resume", "POST", {
+                ref: state.ref,
+                ...(allowedDomains === undefined ? {} : { egress: [...allowedDomains] }),
+            })), {
+                allowedDomains: allowedDomains === undefined ? undefined : [...allowedDomains],
+                port: state.port ?? CLOUD_BOX_PORT,
+            });
+        },
+        async destroy(snapshotRef) {
+            const state = decodeSnapshotRef(snapshotRef);
+            // Best-effort reap of the recorded source machine (it is usually
+            // already gone — the sleep flow destroyed it), then the artifact GC.
+            // A 404 from either is the seam's idempotent no-op.
+            await sendJson(`/${encodeURIComponent(state.machineId)}`, "DELETE").catch(() => undefined);
+            try {
+                await sendJson(`${CLOUD_SNAPSHOTS_SUBPATH}/${encodeURIComponent(state.ref)}`, "DELETE");
+            }
+            catch (error) {
+                if (!isGone(error))
+                    throw error;
+            }
+        },
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,216 @@
+import { type ActionsRegistry, type Connector, type ServerActionHandler } from "@vendoai/actions";
+import { type VendoAgent } from "@vendoai/agent";
+import { type AppsConfig, type AppsRuntime, type SandboxAdapter } from "@vendoai/apps";
+import { type AutomationsEngine } from "@vendoai/automations";
+import { type ActAs, type ComponentCatalog, type ComponentRegistry, type Json, type Principal, type RunId, type SecretsProvider, type ToolRegistry } from "@vendoai/core";
+import { type Judge, type PolicyConfig, type VendoGuard } from "@vendoai/guard";
+import { type HostOAuthAdapter } from "@vendoai/mcp";
+import { type VendoStore } from "@vendoai/store";
+export { eraseStore, type EraseReport, type EraseTable } from "@vendoai/store";
+export { createStore, envSecrets, secretStore, storeSecrets } from "@vendoai/store";
+export { hostAuthPresetConformance, type HostAuthPreset, type HostAuthPresetConformanceOptions, type HostAuthPresetOptions, type HostAuthPresetUser, type HostAuthPresetUserResolver, type SupabaseHostAuthPresetOptions, } from "./auth-presets/index.js";
+import type { HostAuthPreset } from "./auth-presets/index.js";
+import type { LanguageModel } from "ai";
+export { devModel, type DevModelOptions } from "./dev-creds/model.js";
+import { type ConnectionsService } from "./connections.js";
+export { byoConnections, cloudConnections, unconfiguredConnections, type CloudConnectionsOptions, type ConnectionsService, } from "./connections.js";
+export { cloudSandbox, type CloudSandboxOptions } from "./sandbox.js";
+export { cloudTools, type CloudToolsOptions } from "./cloud-tools.js";
+export { hostedStore, type HostedStore, type HostedStoreOptions } from "./hosted-store.js";
+export interface Vendo {
+    handler: (req: Request) => Promise<Response>;
+    emit(event: string, payload: Json, principal: Principal): Promise<RunId[]>;
+    agent: VendoAgent;
+    guard: VendoGuard;
+    /** Existing-agents — the guard-bound registry with BYO approval parking:
+        the registry the `vendo_*` tool pack executes through. Same binding
+        chat, apps, and automations ride (no unguarded route); the one addition
+        is that a `pending-approval` outcome parks the exact call so the wire
+        resumes it on approve, discards it on deny, and expires it on the
+        parked-call TTL sweep. */
+    guardedTools: ToolRegistry;
+    apps: AppsRuntime;
+    automations: AutomationsEngine;
+    actions: ActionsRegistry;
+    connections: ConnectionsService;
+    store: VendoStore;
+}
+export interface CreateVendoConfig {
+    /** The agent's LLM — the inference adapter seam (03-agent §1): any ai-SDK
+        LanguageModel. Optional since install-dx v1: an explicitly passed model
+        always wins (BYO-LLM); when absent the seam resolves a real key from the
+        environment — provider keys via devModel's ladder, then VENDO_API_KEY →
+        Vendo Cloud managed inference — and fails honestly with instructions
+        when none exists (precedence: selectModel). */
+    model?: LanguageModel;
+    /** v2 spec §4 — tier-0 paint lane knob for app generation. `model` is the
+        no-think switch (a thinking-disabled model instance for the instant
+        paint); `disabled` forces single-lane generation. */
+    paint?: AppsConfig["paint"];
+    /** 09-vendo §2.1 — ONE host-identity preset filling the principal, actAs, and
+        oauth seams from one config key. Mutually exclusive with all three:
+        mixing throws VendoError("validation") at compose time. */
+    auth?: HostAuthPreset;
+    /** Per-seam escape hatch: host session → principal; null → the per-client
+        ephemeral anonymous principal. With neither `auth` nor `principal`, every
+        session is anonymous (the null path is the default resolver — 09 §2). */
+    principal?: (req: Request) => Promise<Principal | null>;
+    /** Host components available to generated apps: the name-keyed registry
+        object (01 §14 — the same object serves <VendoRoot>; the server ignores
+        each entry's `component` reference) or the array form. Entry names must
+        mirror the client-side components map 1:1. */
+    catalog?: ComponentCatalog | ComponentRegistry;
+    store?: VendoStore;
+    sandbox?: SandboxAdapter;
+    connectors?: Connector[];
+    /** 04-actions §3 — an explicit connections adapter; always wins over the
+        defaults (precedence: selectConnections). */
+    connections?: ConnectionsService;
+    actAs?: ActAs;
+    /** 04-actions §1 (ENG-248): the server-action registration map emitted by the
+        generated wiring file, keyed `"<module>#<exportName>"`. Server-action tools
+        dispatch in-process through it; a missing key fails closed at execution. */
+    serverActions?: Record<string, ServerActionHandler>;
+    policy?: PolicyConfig;
+    judge?: Judge;
+    secrets?: SecretsProvider;
+    telemetry?: boolean;
+    /** Development-only source capture. NODE_ENV=development enables this with
+        cwd/.vendo defaults; an explicit object supplies a host root for adapters
+        whose process cwd differs. `false` disables the environment default. */
+    development?: boolean | {
+        root?: string;
+        out?: string;
+    };
+    /** 10-mcp §1 — the one flag: open the MCP door so outside agents (Claude,
+        ChatGPT, Cursor) reach the host's tools through the SAME guard-bound path.
+        Opening it is a host decision (10-mcp §2), so it is off by default.
+        The additive object form opens the door with options: `baseUrl` is the
+        canonical PUBLIC base URL the door's discovery metadata, issuer, resource
+        identifiers, and RFC 8707 audience binding derive from — set it (or
+        `VENDO_BASE_URL`, the default) behind a reverse proxy, where the request
+        URL carries the proxy-internal origin. Forwarded headers are never
+        trusted. `remoteAs` (10-mcp §3.1) trusts an external authorization server
+        — e.g. the hosted broker at `{tenant}.mcp.vendo.run` — instead of serving
+        the door's local OAuth surface, and `federation` (10-mcp §3.2) answers
+        that server's signed login handshake at `{mount}/federate`. */
+    mcp?: boolean | {
+        baseUrl?: string;
+        remoteAs?: {
+            issuer: string;
+            jwksUri?: string;
+            audience: string;
+        };
+        federation?: {
+            secret: string;
+        };
+    };
+    /** 10-mcp §3 plus its additive prebuilt flow — the host's session + identity seam. Threaded top-level like
+        `actAs`/`principal` (the door is agnostic; the umbrella owns the shape).
+        REQUIRED when `mcp` is true: the door cannot mint principals without it. */
+    oauth?: HostOAuthAdapter;
+    /** 03-agent — chat context controls. All optional. `toolOutputCap` defaults to
+        DEFAULT_TOOL_OUTPUT_CAP so one huge host-tool response can't blow the context;
+        pass 0 to disable. `historyWindow` bounds messages re-sent per turn (default: full). */
+    agent?: {
+        toolOutputCap?: number;
+        maxOutputTokens?: number;
+        historyWindow?: number;
+        /** ENG-252 — cap on the uncurated initial tool loadout; the rest stay
+            discoverable via `vendo_tools_search`. Defaults to the agent block's
+            DEFAULT_MAX_INITIAL_TOOLS. */
+        maxInitialTools?: number;
+        /** ENG-252 — explicit curated initial loadout by tool name. When set,
+            exactly these host tools (that exist and are enabled) start active —
+            the cap is not applied; the rest stay discoverable via
+            `vendo_tools_search`. Vendo's own `vendo_*` tools are always active. */
+        loadout?: string[];
+        /** AGENT-7: agent-loop step cap per turn (default 20). Exhaustion streams a
+            renderable `data-vendo-step-limit` part instead of ending silently. */
+        maxSteps?: number;
+    };
+    /** 02-store §4 (kill-list B3) — ephemeral (anonymous) session lifecycle.
+        Anonymous visitors get a TTL-based session on disk: every request touches
+        it; an idle session is swept — its rows erased from the store and its
+        in-memory threads cascaded away. All optional.
+        - `ttlMs` idle timeout before a session is swept (default 30 min). `0`
+          disables TTL eviction.
+        - `sweepIntervalMs` how often the amortized on-request sweep and the
+          unref'd background timer run (default 60 s).
+        - `now` internal clock seam (tests only). */
+    sessions?: {
+        ttlMs?: number;
+        sweepIntervalMs?: number;
+        now?: () => number;
+    };
+    /** Existing-agents — approval lifecycle knobs.
+        - `parkedCallTtlMs` idle timeout for a guarded call parked from a BYO
+          agent loop (a `vendo/approval-ref@1` envelope with no Vendo thread to
+          resume through). Past it, the sweep denies the approval through the
+          existing abandonment semantics and `<VendoApprovalEmbed>` reads
+          "expired". Default 60 min; `0` disables expiry. Vendo-thread approvals
+          are untouched — their abandonment stays turn-driven (AGENT-6). */
+    approvals?: {
+        parkedCallTtlMs?: number;
+    };
+    /** execution-v2 Waves 4+9 — apps-block options. `experimentalMachines` is
+        the per-project layer-2 opt-in: NEW box graduation (the escalation
+        ladder's last rung) and machine provisioning refuse with a typed
+        VendoError naming this flag until the host enables it; steps/agentic
+        automations (the ladder's first two rungs) never need it, and apps that
+        already carry a machine keep every runtime path. `experimentalServedApps`
+        is the layer-3 opt-in on top: a machine may serve the app surface itself
+        (the host embeds its URL in a sandboxed iframe) — it REQUIRES
+        `experimentalMachines` (layer 3 is served by a layer-2 machine). OFF by
+        default — layer-3 generation, the 2→3 surface flip, and open() on a
+        served app all refuse with a typed VendoError naming the flag. */
+    apps?: {
+        experimentalServedApps?: boolean;
+        experimentalMachines?: boolean;
+        /** Host design rules for app generation (spec 2026-07-20): the same prose
+            `.vendo/design-rules.md` carries, for hosts that prefer programmatic
+            config. A non-blank string wins over the file and is fixed for the
+            instance lifetime; unset/blank falls through to a PER-GENERATION read
+            of the file, so editing it applies to the next create/edit without a
+            restart. */
+        designRules?: string;
+    };
+}
+/** 09-vendo §2 — compose every live block around the guard choke point. */
+export declare function createVendo(config: CreateVendoConfig): Vendo;
+/** 09-vendo §2 — adapt the fetch handler to a Next.js catch-all route module.
+    PATCH stays exported even with no PATCH-only wire route left: Next.js
+    405s any method the module does not export before the request ever
+    reaches `vendo.handler`, so dropping it would turn e.g. `PATCH
+    /api/vendo/orgs/:id/members/:subject` into a framework 405 instead of
+    the wire's own `cloud-required` seam (the org routes matched ANY
+    method — orgsRoutes in wire/misc.ts). PUT carries the box callback
+    surface's durable-row writes (execution-v2 Lane C:
+    PUT /api/vendo/box/rows/:collection/:id). */
+export declare function nextVendoHandler(vendo: Vendo): {
+    GET(request: Request): Promise<Response>;
+    POST(request: Request): Promise<Response>;
+    PUT(request: Request): Promise<Response>;
+    PATCH(request: Request): Promise<Response>;
+    DELETE(request: Request): Promise<Response>;
+};
+/** 10-mcp §5 — adapt the fetch handler to a Next.js `app/.well-known/[...vendo]/
+    route.ts` module. The four discovery documents the door serves (RFC 9728/
+    8414 metadata for its fixed mount, plus the SEP-2127 server card) live at
+    ORIGIN-ROOT paths, outside BASE_PATH — a host's `/api/vendo` catch-all route
+    never sees them, because Next.js dispatches by directory structure, not by
+    the wire's own routing. This file exists so that directory gets a handler
+    too, one that shares DOOR_WELL_KNOWN_PATHS with the wire itself (the SAME
+    set `isDoorPath` matches) instead of a hand-copied allowlist that can drift
+    from it. A request whose pathname is exactly one of those four paths
+    forwards to `vendo.handler` (which independently confirms it's a door path
+    and, if `mcp` is configured, serves it — the check here is only about
+    which requests reach the wire at all); anything else answers 404 with an
+    empty body, mirroring the hand-written route this replaces. With `mcp` left
+    unconfigured, `vendo.handler` still recognizes these four paths but has no
+    door to serve them, so the request falls through to the wire's ordinary
+    not-found response — never a 500. */
+export declare function wellKnownVendoHandler(vendo: Vendo): {
+    GET(request: Request): Promise<Response>;
+    POST(request: Request): Promise<Response>;
+};