@vendoai/vendo 0.4.3 → 0.4.5

package/dist/capability-misses.js

@@ -1,6 +1,6 @@
 import { canonicalJson, sha256Hex, } from "@vendoai/core";
 import { envOptOut, loadConfig } from "@vendoai/telemetry";
-import { cloudFetch } from "./cli/cloud/client.js";
+import { cloudKeyFetch } from "./cloud-key-fetch.js";
 const DEFAULT_DATA_DIR = ".vendo/data";
 const DEFAULT_BATCH_SIZE = 100;
 const DEFAULT_QUEUE_LIMIT = 1_000;
@@ -60,8 +60,7 @@ function createMissUploader(options) {
             unrefTimer(timeout);
             try {
                 const surface = await options.surface;
-                const response = await cloudFetch("/api/v1/misses", {
-                    auth: "key",
+                const response = await cloudKeyFetch("/api/v1/misses", {
                     apiKey: options.apiKey,
                     env: options.env,
                     fetchImpl: options.fetchImpl,

package/dist/cli/cloud/client.d.ts

@@ -5,11 +5,8 @@ export declare class CloudError extends Error {
     readonly status: number;
     constructor(code: string, message: string, status: number);
 }
-export interface CloudUrlOptions {
-    apiUrl?: string;
-    env?: Record<string, string | undefined>;
-}
-export declare function resolveCloudBaseUrl(options?: CloudUrlOptions): string;
+export { resolveCloudBaseUrl, type CloudUrlOptions } from "../../cloud-key-fetch.js";
+import { type CloudUrlOptions } from "../../cloud-key-fetch.js";
 export interface SessionStore {
     read(): Promise<CloudSession | null>;
     write(session: CloudSession): Promise<void>;

package/dist/cli/cloud/client.js

@@ -15,10 +15,10 @@ export class CloudError extends Error {
         this.status = status;
     }
 }
-export function resolveCloudBaseUrl(options = {}) {
-    const value = options.apiUrl ?? (options.env ?? process.env).VENDO_CLOUD_URL ?? DEFAULT_CLOUD_URL;
-    return value.replace(/\/+$/, "");
-}
+// Base-URL resolution lives with the portable runtime helper so server-side
+// code (capability misses) never imports this Node/CLI module.
+export { resolveCloudBaseUrl } from "../../cloud-key-fetch.js";
+import { resolveCloudBaseUrl } from "../../cloud-key-fetch.js";
 function requestUrl(path, options) {
     const base = resolveCloudBaseUrl(options);
     const suffix = base.endsWith("/api/v1") && path.startsWith("/api/v1/")

package/dist/cli/dep-versions.d.ts

@@ -23,4 +23,4 @@ export declare function installedAiVersion(root: string): Promise<string | null>
  * Read the host project's dependency versions (deps + devDeps) for telemetry.
  * Non-throwing: a missing or malformed package.json returns {}.
  */
-export declare function detectDepVersions(root: string, framework: HostFramework): Promise<DepVersions>;
+export declare function detectDepVersions(root: string, framework: HostFramework | "custom"): Promise<DepVersions>;

package/dist/cli/dep-versions.js

@@ -56,7 +56,7 @@ export async function detectDepVersions(root, framework) {
         const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
         const dependencies = { ...manifest.devDependencies, ...manifest.dependencies };
         const out = {};
-        const frameworkPackage = framework === "unknown" ? undefined : FRAMEWORK_PACKAGE[framework];
+        const frameworkPackage = framework === "unknown" || framework === "custom" ? undefined : FRAMEWORK_PACKAGE[framework];
         const frameworkVersion = frameworkPackage === undefined ? undefined : bareVersion(dependencies[frameworkPackage]);
         if (frameworkVersion !== undefined)
             out.frameworkVersion = frameworkVersion;

package/dist/cli/doctor-codes.d.ts

@@ -18,6 +18,8 @@ export declare const DOCTOR_ERROR_CODES: {
     readonly "E-WIRE-004": "the Next.js root layout is not wrapped in <VendoRoot>";
     readonly "E-WIRE-005": "the @vendoai/vendo (or vendoai alias) dependency is not declared";
     readonly "E-WIRE-006": "no visible agent surface is mounted (<VendoRoot> alone renders nothing)";
+    readonly "E-WIRE-007": "no createVendo server wiring found in an unknown-framework host";
+    readonly "E-WIRE-008": "no <VendoRoot> found in an unknown-framework host's source";
     readonly "E-CFG-001": "a required .vendo/ config file is missing";
     readonly "E-CFG-002": ".vendo/data/.gitignore is missing";
     readonly "E-DEP-001": "the installed ai package is a major version @vendoai/vendo does not support";
@@ -30,6 +32,7 @@ export declare const DOCTOR_ERROR_CODES: {
     readonly "E-LIVE-004": "no execution venue is configured";
     readonly "E-LIVE-005": "the host /status does not report an execution venue (version skew)";
     readonly "E-LIVE-006": "the app's root page returns a server error while the wire answers";
+    readonly "E-LIVE-007": "the selected e2b execution venue is unusable (E2B_API_KEY or the e2b package is missing)";
     readonly "E-AUTH-001": "present credentials did not reach the host API";
     readonly "E-AUTH-002": "the present credential probe is unreachable";
     readonly "E-AUTH-003": "the present credential probe cannot run while the dev server is down";
@@ -49,6 +52,8 @@ export declare const DOCTOR_ERROR_CODES: {
     readonly "E-TURN-001": "the live model turn did not answer";
     readonly "E-TURN-002": "the live model turn cannot run while the dev server is down";
     readonly "E-CLOUD-001": "VENDO_API_KEY is set but not usable";
+    readonly "E-TOOLS-001": "every extracted host tool is disabled or excluded (zero live host tools)";
+    readonly "E-TOOLS-002": "the extracted tool surface is empty (zero host tools)";
 };
 export type DoctorErrorCode = keyof typeof DOCTOR_ERROR_CODES;
 /** Complete list of every code doctor can emit, for CI enumeration. */

package/dist/cli/doctor-codes.js

@@ -19,6 +19,8 @@ export const DOCTOR_ERROR_CODES = {
     "E-WIRE-004": "the Next.js root layout is not wrapped in <VendoRoot>",
     "E-WIRE-005": "the @vendoai/vendo (or vendoai alias) dependency is not declared",
     "E-WIRE-006": "no visible agent surface is mounted (<VendoRoot> alone renders nothing)",
+    "E-WIRE-007": "no createVendo server wiring found in an unknown-framework host",
+    "E-WIRE-008": "no <VendoRoot> found in an unknown-framework host's source",
     "E-CFG-001": "a required .vendo/ config file is missing",
     "E-CFG-002": ".vendo/data/.gitignore is missing",
     "E-DEP-001": "the installed ai package is a major version @vendoai/vendo does not support",
@@ -31,6 +33,7 @@ export const DOCTOR_ERROR_CODES = {
     "E-LIVE-004": "no execution venue is configured",
     "E-LIVE-005": "the host /status does not report an execution venue (version skew)",
     "E-LIVE-006": "the app's root page returns a server error while the wire answers",
+    "E-LIVE-007": "the selected e2b execution venue is unusable (E2B_API_KEY or the e2b package is missing)",
     "E-AUTH-001": "present credentials did not reach the host API",
     "E-AUTH-002": "the present credential probe is unreachable",
     "E-AUTH-003": "the present credential probe cannot run while the dev server is down",
@@ -50,6 +53,8 @@ export const DOCTOR_ERROR_CODES = {
     "E-TURN-001": "the live model turn did not answer",
     "E-TURN-002": "the live model turn cannot run while the dev server is down",
     "E-CLOUD-001": "VENDO_API_KEY is set but not usable",
+    "E-TOOLS-001": "every extracted host tool is disabled or excluded (zero live host tools)",
+    "E-TOOLS-002": "the extracted tool surface is empty (zero host tools)",
 };
 /** Complete list of every code doctor can emit, for CI enumeration. */
 export const doctorErrorCodes = Object.keys(DOCTOR_ERROR_CODES);

package/dist/cli/doctor.d.ts

@@ -34,6 +34,7 @@ export interface DoctorOptions {
         ok: boolean;
         stop: () => void;
     }>;
+    e2bResolvable?: (root: string) => boolean;
 }
 /** Doctor runs standalone, so unlike the dev server it gets no framework
  *  dotenv loading — without this, `VENDO_API_KEY` sitting in `.env.local`

package/dist/cli/doctor.js

@@ -1,14 +1,30 @@
 import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { join, resolve } from "node:path";
 import { stdin, stdout } from "node:process";
 import { cloudDoctor, liveModelTurn, startDevServerForProbe, } from "./doctor-live.js";
 import { installedAiVersion } from "./dep-versions.js";
 import { doctorFixRef } from "./doctor-codes.js";
 import { EJECT_MANIFEST_FILE } from "./eject.js";
+import { overridesFileSchema, toolsFileSchema } from "@vendoai/actions";
 import { detectFramework, detectVendoWiring } from "./framework.js";
 import { walk } from "./theme/walk.js";
 import { remoteUrls, sameUrl, validateRegistryServer } from "./mcp/registry.js";
 import { askYesNo, CLI_VERSION, consoleOutput, exists, normalizeDotEnvValue, readOptional, toolingTelemetry } from "./shared.js";
+/** Whether the optional `e2b` SDK resolves from the target project — the same
+ *  node_modules walk the running wire's dynamic `import("e2b")` performs, so
+ *  doctor certifies the venue against the resolution that will actually be
+ *  asked to load it (0.4.4 defect C: /status said e2b on a host without the
+ *  SDK, and the first build died in an unusable venue). */
+function e2bResolvableFrom(root) {
+    try {
+        createRequire(join(root, "__vendo-doctor-probe__.js")).resolve("e2b");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function hasDependency(root) {
     try {
         const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
@@ -112,7 +128,21 @@ export async function runDoctor(options) {
     }
     const scanned = await detectVendoWiring(root, { exclude: wrapperCandidates });
     const wiring = { ...scanned, surface: scanned.surface || (scanned.client && wrapperWithOverlay) };
-    if (framework === "express") {
+    if (framework === "unknown") {
+        // No framework to pattern-match (field case: a Cloudflare Worker + Vite
+        // host failed E-WIRE-003/004 forever) — judge the wiring by the same
+        // bounded source scan init uses, never by another framework's file
+        // layout. The surface check below still runs; it is source-generic.
+        if (scanned.server)
+            pass("wiring/server", "createVendo server wiring found");
+        else
+            fail("wiring/server", "E-WIRE-007", "no createVendo server wiring found — import createVendo from @vendoai/vendo/server and mount vendo.handler on your runtime's request entry");
+        if (scanned.client)
+            pass("wiring/client", "<VendoRoot> wraps the client");
+        else
+            warn("wiring/client", "E-WIRE-008", "no <VendoRoot> found in the host source — the @vendoai/ui hooks and embeds need it; ignore this if the host renders a fully custom surface");
+    }
+    else if (framework === "express") {
         if (wiring.server)
             pass("wiring/express-server", "Express server is wired");
         else
@@ -184,6 +214,42 @@ export async function runDoctor(options) {
     }
     if (!await exists(join(root, ".vendo", "data", ".gitignore")))
         warn("config/data-gitignore", "E-CFG-002", ".vendo/data/.gitignore is missing");
+    // The core promise, statically checkable: does the agent have any HOST
+    // tool it may actually call? All-disabled is an explicit misconfiguration
+    // (fail); an empty extraction is a strong warning — connector-only hosts
+    // are legitimate, but a fresh install landing here means extraction found
+    // nothing user-facing (field case: an infra product whose surface was all
+    // internal endpoints ended with tools: [] and a silently useless agent).
+    const toolsRaw = await readOptional(join(root, ".vendo", "tools.json"));
+    const overridesRaw = await readOptional(join(root, ".vendo", "overrides.json"));
+    if (toolsRaw !== null) {
+        try {
+            const toolsFile = toolsFileSchema.parse(JSON.parse(toolsRaw));
+            let overridesTools = {};
+            if (overridesRaw !== null) {
+                try {
+                    overridesTools = overridesFileSchema.parse(JSON.parse(overridesRaw)).tools;
+                }
+                catch {
+                    // Malformed overrides are their own (pre-existing) failure surface.
+                }
+            }
+            const live = toolsFile.tools.filter((tool) => (overridesTools[tool.name]?.disabled ?? tool.disabled ?? false) !== true);
+            if (toolsFile.tools.length === 0) {
+                warn("tools/live-surface", "E-TOOLS-002", "the extracted tool surface is empty — the agent cannot act on this product's API; re-run `vendo init` extraction (or ignore if this deployment is connector-only)");
+            }
+            else if (live.length === 0) {
+                fail("tools/live-surface", "E-TOOLS-001", `zero live host tools — all ${toolsFile.tools.length} extracted tools are disabled or excluded; review the audience exclusions in .vendo/overrides.json and re-enable the end-user surface (disabled: false)`);
+            }
+            else {
+                pass("tools/live-surface", `${live.length} live host tool${live.length === 1 ? "" : "s"}`);
+            }
+        }
+        catch {
+            // Not the vendo/tools@1 shape (e.g. a placeholder {}) — the config
+            // checks above already govern presence; nothing to grade here.
+        }
+    }
     // §4 customization ladder — ejected chrome drift. The ejected pixels are the
     // host's code, so a version gap is awareness (warn), never breakage (fail):
     // the hooks/wire dependency keeps working; only new presentation is missed.
@@ -279,7 +345,25 @@ export async function runDoctor(options) {
             // 10-mcp §1 — the door flag lives under blocks.mcp.
             mcpEnabled = body.blocks.mcp === true;
             sandboxVenue = body.blocks.sandbox;
-            if (sandboxVenue === "e2b" || sandboxVenue === "cloud" || sandboxVenue === "custom") {
+            if (sandboxVenue === "e2b") {
+                // 0.4.4 defect C — "ok: execution venue: e2b" on a host that cannot
+                // actually run e2b is a false blessing: the venue must be USABLE
+                // (key set and SDK resolvable from this project), or every server-app
+                // build dies in it instead of riding the Cloud sandbox.
+                const keyPresent = typeof env.E2B_API_KEY === "string" && env.E2B_API_KEY.trim() !== "";
+                const installed = (options.e2bResolvable ?? e2bResolvableFrom)(root);
+                if (keyPresent && installed) {
+                    pass("live/venue", "execution venue: e2b");
+                }
+                else {
+                    const missing = [
+                        ...(keyPresent ? [] : ["E2B_API_KEY is not set"]),
+                        ...(installed ? [] : ["the e2b package does not resolve from this project"]),
+                    ].join(" and ");
+                    fail("live/venue", "E-LIVE-007", `the running wire selected the e2b execution venue but ${missing}; server-app builds will fail in an unusable sandbox. Fix: install the e2b package and set E2B_API_KEY, or remove E2B_API_KEY from the server env (with VENDO_API_KEY set, the managed Cloud sandbox takes over), then restart the dev server and re-run doctor`);
+                }
+            }
+            else if (sandboxVenue === "cloud" || sandboxVenue === "custom") {
                 pass("live/venue", `execution venue: ${sandboxVenue}`);
             }
             else if (sandboxVenue === false) {

package/dist/cli/extract/apply.js

@@ -1,6 +1,6 @@
 import { join, resolve } from "node:path";
 import { z } from "zod";
-import { vendoSync } from "@vendoai/actions";
+import { vendoSync } from "@vendoai/actions/sync";
 import { detectDepVersions } from "../dep-versions.js";
 import { detectFramework } from "../framework.js";
 import { applyDraft, reportApplied } from "./extraction.js";

package/dist/cli/extract/delegate.js

@@ -41,6 +41,10 @@ export const EXTRACTION_DRAFT_JSON_SCHEMA = {
                         type: "boolean",
                         description: "false = wake a statically-unclassifiable tool (requires reasoning and risk).",
                     },
+                    audience: {
+                        enum: ["end-user", "operator", "internal"],
+                        description: "Who the handler's own auth admits; non-end-user grades exclude the tool by default.",
+                    },
                     reasoning: { type: "string", maxLength: 500 },
                 },
             },
@@ -66,10 +70,14 @@ export function composeDelegatedInstructions(tools, appName) {
         "",
         "Rules:",
         "- Produce ONE json document matching the provided draftSchema:",
-        '  { "brief": string, "tools": [{ "name", "description", "risk"?, "critical"?, "disabled"?, "reasoning"? }], "missedSurfaces"?: string[] }',
+        '  { "brief": string, "tools": [{ "name", "description", "risk"?, "critical"?, "disabled"?, "audience"?, "reasoning"? }], "missedSurfaces"?: string[] }',
         "- tools: include ONLY names from the list above. Rewrite each description so an agent choosing tools understands what it actually does (read the handler source). <= 200 chars each.",
         "- risk: you may RAISE risk (read->write->destructive) when the handler is more dangerous than labeled; never lower it. Mark irreversible operations critical: true.",
         "- A tool listed as disabled was statically unclassifiable. If you can read its handler and grade it, set disabled: false WITH a risk and one-line reasoning. Leave it out otherwise.",
+        "- audience: who the handler's own auth admits — \"end-user\" (a signed-in customer acting on their own data),",
+        "  \"operator\" (admin/staff/support consoles), or \"internal\" (machine-to-machine: webhooks, cron, reconciliation,",
+        "  service tokens). Read the auth checks, not the route name. When unsure, default to internal — non-end-user",
+        "  tools are excluded from the embedded agent by default, and a wrong \"end-user\" grade exposes a privileged surface.",
         "- missedSurfaces: API surfaces you found that the list is missing (path + one line). Do not invent tools for them.",
         "- brief: one paragraph — what the product does, who uses it, the jobs the agent should help with. Written from the actual code, no marketing fluff.",
         `- Save the draft to a json file and apply it with \`${APPLY_COMMAND}\` — deterministic guards validate every entry before anything lands in .vendo/.`,

package/dist/cli/extract/extraction.d.ts

@@ -8,6 +8,10 @@ export interface AppliedSummary {
     riskRaised: number;
     critical: number;
     woken: number;
+    /** Non-end-user-audience tools excluded (disabled) this apply. */
+    excluded: number;
+    /** Tools still live after this apply — zero means the agent cannot act on the host API at all. */
+    enabledAfter: number;
     briefWritten: boolean;
     refused: string[];
     missedSurfaces: string[];

package/dist/cli/extract/extraction.js

@@ -50,7 +50,7 @@ export async function applyDraft(input) {
         ? { format: "vendo/overrides@1", tools: {} }
         : overridesSchema.parse(JSON.parse(raw));
     const summary = {
-        described: 0, riskRaised: 0, critical: 0, woken: 0,
+        described: 0, riskRaised: 0, critical: 0, woken: 0, excluded: 0, enabledAfter: 0,
         briefWritten: false, refused: [], missedSurfaces: input.draft.missedSurfaces ?? [],
     };
     for (const entry of input.draft.tools) {
@@ -70,7 +70,10 @@ export async function applyDraft(input) {
         // evidence, so a reasoned wake carries the model's grade without tripping
         // the downgrade guard (Greptile P1 / Devin on #363). A human-set risk or
         // disabled decision always wins.
-        const isWake = entry.disabled === false && fact.disabled === true;
+        // A wake claiming a non-end-user audience is contradictory; audience
+        // exclusion (fail-closed) wins and the wake leg never runs.
+        const nonEndUser = entry.audience === "operator" || entry.audience === "internal";
+        const isWake = entry.disabled === false && fact.disabled === true && !nonEndUser;
         if (isWake && existing.disabled === undefined) {
             if (entry.reasoning === undefined || entry.risk === undefined) {
                 summary.refused.push(`${entry.name}: waking a disabled tool needs reasoning and a risk grade`);
@@ -96,9 +99,27 @@ export async function applyDraft(input) {
             next.critical = true;
             summary.critical += 1;
         }
+        // Audience: recorded as provenance; a non-end-user grade excludes the
+        // tool by default. A human decision on either field always wins — a
+        // hand-set disabled (true OR false) or audience is never touched.
+        if (entry.audience !== undefined && existing.audience === undefined) {
+            next.audience = entry.audience;
+            if (nonEndUser && existing.disabled === undefined && next.disabled !== false) {
+                if (next.disabled !== true)
+                    summary.excluded += 1;
+                next.disabled = true;
+            }
+        }
         if (JSON.stringify(next) !== JSON.stringify(existing))
             overrides.tools[entry.name] = next;
     }
+    // The number that actually matters to an end user: how many tools the
+    // agent can still call once static grades and overrides settle. Zero means
+    // the product's core promise silently degraded — reportApplied warns.
+    summary.enabledAfter = input.tools.filter((tool) => {
+        const override = overrides.tools[tool.name] ?? {};
+        return (override.disabled ?? tool.disabled ?? false) !== true;
+    }).length;
     await writeText(overridesPath, `${JSON.stringify(overrides, null, 2)}\n`);
     const briefPath = join(input.root, ".vendo", "brief.md");
     const currentBrief = ((await readOptional(briefPath)) ?? "").trim();
@@ -117,6 +138,7 @@ export function reportApplied(input) {
         ...(applied.riskRaised > 0 ? [`${applied.riskRaised} risk raises`] : []),
         ...(applied.critical > 0 ? [`${applied.critical} critical marks`] : []),
         ...(applied.woken > 0 ? [`${applied.woken} tools woken`] : []),
+        ...(applied.excluded > 0 ? [`${applied.excluded} operator/internal tools excluded`] : []),
         ...(input.briefDrafted ? ["brief drafted"] : []),
     ];
     output.log(`AI polish applied: ${parts.join(" · ")} → .vendo/overrides.json, .vendo/brief.md${input.artifactsNote ?? ""}`);
@@ -124,6 +146,11 @@ export function reportApplied(input) {
         output.error(`  ${note}`);
     for (const refused of applied.refused)
         output.error(`  refused: ${refused}`);
+    if (applied.enabledAfter === 0) {
+        output.error("  WARNING: zero live tools after apply — every extracted tool is disabled or excluded, so the embedded "
+            + "agent cannot act on this product's API. Review the audience exclusions in .vendo/overrides.json "
+            + "(re-enable the end-user surface with disabled: false) or re-run extraction.");
+    }
     for (const missed of applied.missedSurfaces)
         output.log(`  missed surface (not extracted yet): ${missed}`);
 }

package/dist/cli/extract/harness.d.ts

@@ -15,10 +15,14 @@ export declare const draftToolSchema: z.ZodObject<{
     critical: z.ZodOptional<z.ZodBoolean>;
     /** false = wake a statically-unclassifiable tool (needs reasoning). */
     disabled: z.ZodOptional<z.ZodBoolean>;
+    /** Who the handler's own auth admits; non-end-user grades exclude the tool
+     *  by default (applyDraft). */
+    audience: z.ZodOptional<z.ZodEnum<["end-user", "operator", "internal"]>>;
     reasoning: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     description: string;
+    audience?: "end-user" | "operator" | "internal" | undefined;
     risk?: "read" | "write" | "destructive" | undefined;
     critical?: boolean | undefined;
     disabled?: boolean | undefined;
@@ -26,6 +30,7 @@ export declare const draftToolSchema: z.ZodObject<{
 }, {
     name: string;
     description: string;
+    audience?: "end-user" | "operator" | "internal" | undefined;
     risk?: "read" | "write" | "destructive" | undefined;
     critical?: boolean | undefined;
     disabled?: boolean | undefined;
@@ -42,10 +47,14 @@ export declare const extractionDraftSchema: z.ZodObject<{
         critical: z.ZodOptional<z.ZodBoolean>;
         /** false = wake a statically-unclassifiable tool (needs reasoning). */
         disabled: z.ZodOptional<z.ZodBoolean>;
+        /** Who the handler's own auth admits; non-end-user grades exclude the tool
+         *  by default (applyDraft). */
+        audience: z.ZodOptional<z.ZodEnum<["end-user", "operator", "internal"]>>;
         reasoning: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         description: string;
+        audience?: "end-user" | "operator" | "internal" | undefined;
         risk?: "read" | "write" | "destructive" | undefined;
         critical?: boolean | undefined;
         disabled?: boolean | undefined;
@@ -53,6 +62,7 @@ export declare const extractionDraftSchema: z.ZodObject<{
     }, {
         name: string;
         description: string;
+        audience?: "end-user" | "operator" | "internal" | undefined;
         risk?: "read" | "write" | "destructive" | undefined;
         critical?: boolean | undefined;
         disabled?: boolean | undefined;
@@ -65,6 +75,7 @@ export declare const extractionDraftSchema: z.ZodObject<{
     tools: {
         name: string;
         description: string;
+        audience?: "end-user" | "operator" | "internal" | undefined;
         risk?: "read" | "write" | "destructive" | undefined;
         critical?: boolean | undefined;
         disabled?: boolean | undefined;
@@ -76,6 +87,7 @@ export declare const extractionDraftSchema: z.ZodObject<{
     tools: {
         name: string;
         description: string;
+        audience?: "end-user" | "operator" | "internal" | undefined;
         risk?: "read" | "write" | "destructive" | undefined;
         critical?: boolean | undefined;
         disabled?: boolean | undefined;

package/dist/cli/extract/harness.js

@@ -15,6 +15,9 @@ export const draftToolSchema = z.object({
     critical: z.boolean().optional(),
     /** false = wake a statically-unclassifiable tool (needs reasoning). */
     disabled: z.boolean().optional(),
+    /** Who the handler's own auth admits; non-end-user grades exclude the tool
+     *  by default (applyDraft). */
+    audience: z.enum(["end-user", "operator", "internal"]).optional(),
     reasoning: z.string().max(500).optional(),
 });
 export const extractionDraftSchema = z.object({

package/dist/cli/extract/stages.js

@@ -115,10 +115,14 @@ export function composeInstructions(tools, appName, surface) {
         "",
         "Rules:",
         "- Reply with ONLY one fenced json block matching:",
-        '  { "tools": [{ "name", "description", "risk"?, "critical"?, "disabled"?, "reasoning"? }], "missedSurfaces"?: string[] }',
+        '  { "tools": [{ "name", "description", "risk"?, "critical"?, "disabled"?, "audience"?, "reasoning"? }], "missedSurfaces"?: string[] }',
         "- tools: include ONLY names from the list above. Rewrite each description so an agent choosing tools understands what it actually does (read the handler source). <= 200 chars each.",
         "- risk: you may RAISE risk (read->write->destructive) when the handler is more dangerous than labeled; never lower it. Mark irreversible operations critical: true.",
         "- A tool listed as disabled was statically unclassifiable. If you can read its handler and grade it, set disabled: false WITH a risk and one-line reasoning. Leave it out otherwise.",
+        "- audience: who the handler's own auth admits — \"end-user\" (a signed-in customer acting on their own data),",
+        "  \"operator\" (admin/staff/support consoles), or \"internal\" (machine-to-machine: webhooks, cron, reconciliation,",
+        "  service tokens). Read the auth checks, not the route name. When unsure, default to internal — non-end-user",
+        "  tools are excluded from the embedded agent by default, and a wrong \"end-user\" grade exposes a privileged surface.",
         "- missedSurfaces: API surfaces you found that the list is missing (path + one line). Do not invent tools for them.",
     ].join("\n");
 }

package/dist/cli/init-scaffolds.d.ts

@@ -1,4 +1,4 @@
-import { type ServerActionRegistration } from "@vendoai/actions";
+import { type ServerActionRegistration } from "@vendoai/actions/sync";
 import { type AuthMatch } from "./init-auth.js";
 /** The wired preset line plus its escape-hatch comment. The lead-in stays
     honest about how the preset got here: detection cites the found
@@ -46,5 +46,14 @@ export declare function wiringServerActions(root: string): Promise<ServerActionR
  * sorted registrations, stable aliases — so re-init stays idempotent.
  */
 export declare function serverActionsModuleSource(root: string, wiringDir: string, registrations: ServerActionRegistration[]): string;
+/** The runtime-neutral composition (`--framework custom`): plain Request →
+ *  Response with env passed per call, so ONE generated module serves any
+ *  Web-standard host — Cloudflare Workers, Bun, Deno, Hono, Lambda adapters.
+ *  Construction is lazy (first request): the safe shape everywhere and the
+ *  only legal one at Workers module scope. With a Vendo Cloud key the four
+ *  infrastructure seams wire the Cloud adapters explicitly per the adapter
+ *  rule (reference shape: the vendo-on-Workers field integration,
+ *  2026-07-21). */
+export declare function customServerSource(typescript: boolean, auth?: AuthMatch | null): string;
 export declare function expressServerSource(typescript: boolean, auth?: AuthMatch | null): string;
 export declare const VENDO_ENV_EXAMPLE: string;

package/dist/cli/init-scaffolds.js

@@ -1,5 +1,5 @@
 import { join, relative, sep } from "node:path";
-import { extractServerActions, serverActionRegistrations, } from "@vendoai/actions";
+import { extractServerActions, serverActionRegistrations, } from "@vendoai/actions/sync";
 import { AUTH_FAMILY_INFO, AUTH_PRESET_SPECIFIER } from "./init-auth.js";
 /** The wired preset line plus its escape-hatch comment. The lead-in stays
     honest about how the preset got here: detection cites the found
@@ -161,6 +161,98 @@ export function serverActionsModuleSource(root, wiringDir, registrations) {
     return `${header}${imports.join("\n")}\n\n` +
         `export const serverActions = {\n${entries.join("\n")}\n};\n`;
 }
+/** The runtime-neutral composition (`--framework custom`): plain Request →
+ *  Response with env passed per call, so ONE generated module serves any
+ *  Web-standard host — Cloudflare Workers, Bun, Deno, Hono, Lambda adapters.
+ *  Construction is lazy (first request): the safe shape everywhere and the
+ *  only legal one at Workers module scope. With a Vendo Cloud key the four
+ *  infrastructure seams wire the Cloud adapters explicitly per the adapter
+ *  rule (reference shape: the vendo-on-Workers field integration,
+ *  2026-07-21). */
+export function customServerSource(typescript, auth = null) {
+    const registrySpecifier = typescript ? "./registry" : "./registry.mjs";
+    const envType = typescript
+        ? `\nexport interface VendoEnv {\n` +
+            `  VENDO_API_KEY?: string;\n` +
+            `  VENDO_CLOUD_URL?: string;\n` +
+            `  VENDO_BASE_URL?: string;\n` +
+            `}\n`
+        : "";
+    const signatures = typescript
+        ? {
+            vendoVar: `let vendo: ReturnType<typeof createVendo> | null = null;`,
+            getVendo: `(env: VendoEnv = {})`,
+            handle: `(request: Request, env: VendoEnv = {}): Promise<Response>`,
+        }
+        : {
+            vendoVar: `let vendo = null;`,
+            getVendo: `(env = {})`,
+            handle: `(request, env = {})`,
+        };
+    const clientHint = typescript
+        ? ` *   // in the client entry — theme.json adopts the host brand (08 §4);\n` +
+            ` *   // the cast narrows TypeScript's widened JSON-module string literals;\n` +
+            ` *   // <VendoOverlay /> is the visible surface (launcher pill + panel):\n` +
+            ` *   import { VendoOverlay, VendoRoot } from "@vendoai/vendo/react";\n` +
+            ` *   import { registry } from "<path-to>/vendo/registry";\n` +
+            ` *   import theme from "<path-to>/.vendo/theme.json";\n` +
+            ` *   import type { VendoTheme } from "@vendoai/vendo";\n` +
+            ` *   root.render(<VendoRoot components={registry} theme={theme as VendoTheme}><App /><VendoOverlay /></VendoRoot>);\n`
+        : ` *   // in the client entry — theme.json adopts the host brand (08 §4);\n` +
+            ` *   // <VendoOverlay /> is the visible surface (launcher pill + panel):\n` +
+            ` *   import { VendoOverlay, VendoRoot } from "@vendoai/vendo/react";\n` +
+            ` *   import { registry } from "<path-to>/vendo/registry.mjs";\n` +
+            ` *   import theme from "<path-to>/.vendo/theme.json";\n` +
+            ` *   root.render(<VendoRoot components={registry} theme={theme}><App /><VendoOverlay /></VendoRoot>);\n`;
+    return `/**\n` +
+        ` * Route your runtime's requests through this module:\n` +
+        ` *   // Cloudflare Workers:\n` +
+        ` *   //   export default { fetch: (request, env) => handleVendoRequest(request, env) };\n` +
+        ` *   // Bun / Deno / Hono / Node: serve your /api/vendo routes through\n` +
+        ` *   //   handleVendoRequest(request)\n` +
+        clientHint +
+        ` * Deployed hosts must set VENDO_BASE_URL to their public origin\n` +
+        ` * (credential forwarding fails closed without it — vendo doctor checks).\n` +
+        ` */\n` +
+        `import { createAnthropic } from "@ai-sdk/anthropic";\n` +
+        authImportLine(auth) +
+        `import { cloudConnections, cloudSandbox, cloudTools, createVendo, hostedStore } from "@vendoai/vendo/server";\n` +
+        `import { registry } from ${JSON.stringify(registrySpecifier)};\n` +
+        envType +
+        `\n${signatures.vendoVar}\n` +
+        `\n/** Lazy singleton: constructed on the first request, never at module\n` +
+        `    scope — Workers forbids I/O and timers there, and lazy is correct on\n` +
+        `    every other runtime too. */\n` +
+        `function getVendo${signatures.getVendo} {\n` +
+        `  if (vendo === null) {\n` +
+        `    const processEnv = globalThis.process?.env ?? {};\n` +
+        `    const apiKey = env.VENDO_API_KEY ?? processEnv.VENDO_API_KEY;\n` +
+        `    const baseUrl = (env.VENDO_CLOUD_URL ?? processEnv.VENDO_CLOUD_URL ?? "https://console.vendo.run").replace(/\\/+$/, "");\n` +
+        `    const cloud = apiKey === undefined || apiKey === "" ? undefined : { apiKey, baseUrl };\n` +
+        `    vendo = createVendo({\n` +
+        (auth === null ? anonymousPrincipalLines() : authConfigLines(auth))
+            .split("\n").map((line) => (line === "" ? line : `    ${line}`)).join("\n") +
+        `      catalog: registry,\n` +
+        `      policy: {}, // .vendo/policy.json: destructive asks, reads run\n` +
+        `      // With a Vendo Cloud key the infrastructure seams wire the Cloud\n` +
+        `      // adapters EXPLICITLY (composition decides; blocks never read the\n` +
+        `      // environment). Without one, pass your own adapters here — model,\n` +
+        `      // store, connections, sandbox all accept custom implementations.\n` +
+        `      ...(cloud === undefined ? {} : {\n` +
+        `        model: createAnthropic({ apiKey: cloud.apiKey, baseURL: \`\${cloud.baseUrl}/api/v1\` })("vendo-default"),\n` +
+        `        store: hostedStore(cloud),\n` +
+        `        connections: cloudConnections(cloud),\n` +
+        `        connectors: [cloudTools(cloud)],\n` +
+        `        sandbox: cloudSandbox(cloud),\n` +
+        `      }),\n` +
+        `    });\n` +
+        `  }\n` +
+        `  return vendo;\n` +
+        `}\n` +
+        `\nexport function handleVendoRequest${signatures.handle} {\n` +
+        `  return getVendo(env).handler(request);\n` +
+        `}\n`;
+}
 export function expressServerSource(typescript, auth = null) {
     const imports = typescript
         ? `import { once } from "node:events";\n` +

package/dist/cli/init.d.ts

@@ -1,4 +1,4 @@
-import { type ExtractedTool } from "@vendoai/actions";
+import type { ExtractedTool } from "@vendoai/actions";
 import { type CloudStepOptions } from "./cloud-init.js";
 import { type AiExtractionOptions } from "./extract/extraction.js";
 import { type DevCredential } from "../dev-creds/resolve.js";
@@ -14,7 +14,7 @@ export interface RiskRecommendation {
     recommendation: string;
 }
 export interface InitPlan {
-    framework: HostFramework;
+    framework: Exclude<HostFramework, "unknown"> | "custom";
     root: string;
     writes: string[];
     codeChanges: Array<{
@@ -54,7 +54,7 @@ export interface InitOptions {
         detection comes back "unknown" (there is no safe default to guess).
         "unknown" is excluded: an override that answers nothing would silently
         bypass the non-interactive framework guard. */
-    framework?: Exclude<HostFramework, "unknown">;
+    framework?: Exclude<HostFramework, "unknown"> | "custom";
     /** --cloud-key: answer the cloud-login offer with an existing key — landed
         in .env.local exactly where the mint would put it. */
     cloudKey?: string;