@vendoai/vendo 0.4.2 → 0.4.4

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/framework.d.ts

@@ -2,7 +2,22 @@ export type HostFramework = "next" | "express" | "unknown";
 export interface VendoWiring {
     server: boolean;
     client: boolean;
+    /** A VISIBLE agent surface is mounted — <VendoRoot> alone is a context
+        provider that renders nothing (0.4.1 E2E cert B3: by-the-book installs
+        ended doctor-green with nothing on screen). */
+    surface: boolean;
 }
+/** What counts as a visible surface: the shipped chrome (<VendoOverlay> and
+    the pieces it is built from), the BYO embeds a host chat renders, and the
+    hooks a host uses to drive a custom surface. Deliberately generous — this
+    list gates a doctor FAILURE, so a host with any plausible surface of its
+    own must pass. */
+export declare const SURFACE_MARKERS: readonly string[];
 export declare function detectFramework(root: string): Promise<HostFramework>;
-/** Bounded source scan shared by init and doctor so their wiring verdicts agree. */
-export declare function detectVendoWiring(root: string): Promise<VendoWiring>;
+/** Bounded source scan shared by init and doctor so their wiring verdicts
+    agree. `exclude` skips generated files whose own markers would count as
+    host wiring (init's layout decision excludes the vendo-root wrapper: its
+    <VendoOverlay /> is only real once a layout mounts the wrapper itself). */
+export declare function detectVendoWiring(root: string, options?: {
+    exclude?: string[];
+}): Promise<VendoWiring>;

package/dist/cli/framework.js

@@ -1,6 +1,24 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { walk } from "./theme/walk.js";
+/** What counts as a visible surface: the shipped chrome (<VendoOverlay> and
+    the pieces it is built from), the BYO embeds a host chat renders, and the
+    hooks a host uses to drive a custom surface. Deliberately generous — this
+    list gates a doctor FAILURE, so a host with any plausible surface of its
+    own must pass. */
+export const SURFACE_MARKERS = [
+    "<VendoOverlay",
+    "<VendoThread",
+    "<VendoTrigger",
+    "<VendoPalette",
+    "<VendoSlot",
+    "<VendoAppEmbed",
+    "<VendoApprovalEmbed",
+    "<VendoToolResult",
+    "useVendoOverlay(",
+    "useVendoThread(",
+    "useSlotApp(",
+];
 const SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/;
 const SOURCE_SCAN_MAX_FILES = 2_000;
 export async function detectFramework(root) {
@@ -17,20 +35,29 @@ export async function detectFramework(root) {
         return "unknown";
     }
 }
-/** Bounded source scan shared by init and doctor so their wiring verdicts agree. */
-export async function detectVendoWiring(root) {
+/** Bounded source scan shared by init and doctor so their wiring verdicts
+    agree. `exclude` skips generated files whose own markers would count as
+    host wiring (init's layout decision excludes the vendo-root wrapper: its
+    <VendoOverlay /> is only real once a layout mounts the wrapper itself). */
+export async function detectVendoWiring(root, options = {}) {
     let server = false;
     let client = false;
+    let surface = false;
+    const excluded = new Set(options.exclude ?? []);
     const files = await walk(root, (relativePath) => SOURCE_FILE.test(relativePath), SOURCE_SCAN_MAX_FILES);
     for (const file of files) {
+        if (excluded.has(file))
+            continue;
         const source = await readFile(file, "utf8").catch(() => "");
         const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
         if (code.includes("@vendoai/vendo/server") && /\bcreateVendo\s*\(/.test(code))
             server = true;
-        if (code.includes("<VendoRoot"))
+        if (code.includes("<VendoRoot") || code.includes("<VendoProvider"))
             client = true;
-        if (server && client)
+        if (SURFACE_MARKERS.some((marker) => code.includes(marker)))
+            surface = true;
+        if (server && client && surface)
             break;
     }
-    return { server, client };
+    return { server, client, surface };
 }

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
@@ -8,6 +8,28 @@ export declare function authConfigLines(auth: AuthMatch): string;
     as `catalog` (data fields only), `<VendoRoot components={registry}>` reads
     the component references. Generated only while absent — never clobbered. */
 export declare function registrySource(variant: "tsx" | "mjs"): string;
+/** The anonymous-composition principal line (no auth preset wired). The
+    subject matches the demo principal both existing-agents quickstarts set in
+    their chat routes — the wire route MUST resolve the same subject as the
+    host's agent loop, or every app/approval created in chat is invisible to
+    the embeds, which call this route directly (0.4.1 E2E cert blocker B4:
+    a `() => null` wire against a demo-user chat route rendered an infinite
+    skeleton). Replaced wholesale when an auth preset is wired. */
+export declare function anonymousPrincipalLines(): string;
+/**
+ * The client mount wrapper (visible-surface fix, 0.4.1 E2E cert B3/M3): one
+ * generated "use client" boundary owns the registry + theme imports and
+ * mounts `<VendoOverlay />` — the launcher pill + panel end users actually
+ * see. The registry holds component references, so importing it in a Server
+ * Component layout and passing it into the client provider fails RSC
+ * serialization ("Only plain objects can be passed to Client Components");
+ * this wrapper is the layout-safe mount. Generated only while absent.
+ */
+export declare function vendoRootWrapperSource(options: {
+    /** Posix-style import specifier from the wrapper's dir to .vendo/theme.json,
+        or null when resolveJsonModule is explicitly disabled. */
+    themeSpecifier: string | null;
+}): string;
 export declare function routeSource(options: {
     serverActions: boolean;
     auth: AuthMatch | null;
@@ -24,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
@@ -48,6 +48,56 @@ export function registrySource(variant) {
         ? `${header}import type { ComponentRegistry } from "@vendoai/vendo";\n\nexport const registry = {} satisfies ComponentRegistry;\n`
         : `${header}export const registry = {};\n`;
 }
+/** The anonymous-composition principal line (no auth preset wired). The
+    subject matches the demo principal both existing-agents quickstarts set in
+    their chat routes — the wire route MUST resolve the same subject as the
+    host's agent loop, or every app/approval created in chat is invisible to
+    the embeds, which call this route directly (0.4.1 E2E cert blocker B4:
+    a `() => null` wire against a demo-user chat route rendered an infinite
+    skeleton). Replaced wholesale when an auth preset is wired. */
+export function anonymousPrincipalLines() {
+    return `  // Who the wire's callers act as. This must resolve the SAME subject your\n` +
+        `  // agent loop uses (the docs' chat routes set this demo principal), or apps\n` +
+        `  // and approvals created in chat are invisible to the embeds, which call\n` +
+        `  // this route directly. Replace both sides with your real session lookup.\n` +
+        `  principal: async () => ({ kind: "user" as const, subject: "demo-user" }),\n`;
+}
+/**
+ * The client mount wrapper (visible-surface fix, 0.4.1 E2E cert B3/M3): one
+ * generated "use client" boundary owns the registry + theme imports and
+ * mounts `<VendoOverlay />` — the launcher pill + panel end users actually
+ * see. The registry holds component references, so importing it in a Server
+ * Component layout and passing it into the client provider fails RSC
+ * serialization ("Only plain objects can be passed to Client Components");
+ * this wrapper is the layout-safe mount. Generated only while absent.
+ */
+export function vendoRootWrapperSource(options) {
+    const withTheme = options.themeSpecifier !== null;
+    return `"use client";\n\n` +
+        `/**\n` +
+        ` * The Vendo client mount — generated by \`vendo init\`, then yours.\n` +
+        ` * This "use client" boundary owns the registry${withTheme ? " and theme" : ""} imports: the\n` +
+        ` * registry carries component references, which cannot cross a Server\n` +
+        ` * Component boundary as props (RSC serialization). <VendoOverlay /> is the\n` +
+        ` * visible surface — the launcher pill + panel. Swap it for your own\n` +
+        ` * surface (<VendoThread />, the BYO embeds) whenever you like.\n` +
+        ` */\n` +
+        `import { VendoOverlay, VendoRoot as VendoClientRoot } from "@vendoai/vendo/react";\n` +
+        `import type { ReactNode } from "react";\n` +
+        `import { registry } from "./registry";\n` +
+        (withTheme
+            ? `import theme from ${JSON.stringify(options.themeSpecifier)};\n` +
+                `import type { VendoTheme } from "@vendoai/vendo";\n`
+            : "") +
+        `\nexport function VendoRoot({ children }: { children: ReactNode }) {\n` +
+        `  return (\n` +
+        `    <VendoClientRoot components={registry}${withTheme ? " theme={theme as VendoTheme}" : ""}>\n` +
+        `      {children}\n` +
+        `      <VendoOverlay />\n` +
+        `    </VendoClientRoot>\n` +
+        `  );\n` +
+        `}\n`;
+}
 /** The preset's own import line (its own subpath, never "@vendoai/vendo/server"
     — corpus-triage Task 9: a shared barrel meant any host importing the
     server entry statically re-resolved every preset's optional peer dep,
@@ -61,7 +111,7 @@ export function routeSource(options) {
         (options.serverActions ? `import { serverActions } from "./vendo-actions";\n` : "") +
         `import { registry } from ${JSON.stringify(options.registrySpecifier)};\n` +
         `\nconst vendo = createVendo({\n` +
-        (options.auth === null ? `  principal: async () => null,\n` : authConfigLines(options.auth)) +
+        (options.auth === null ? anonymousPrincipalLines() : authConfigLines(options.auth)) +
         `  catalog: registry,\n` +
         (options.serverActions ? `  serverActions,\n` : "") +
         `  policy: {}, // .vendo/policy.json: destructive asks, reads run\n` +
@@ -111,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` +
@@ -143,17 +285,19 @@ export function expressServerSource(typescript, auth = null) {
     const registrySpecifier = typescript ? "./registry" : "./registry.mjs";
     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` +
-            ` *   import { VendoRoot } from "@vendoai/vendo/react";\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 /></VendoRoot>);\n`
-        : ` *   // in the client entry — theme.json adopts the host brand (08 §4):\n` +
-            ` *   import { VendoRoot } from "@vendoai/vendo/react";\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 /></VendoRoot>);\n`;
+            ` *   root.render(<VendoRoot components={registry} theme={theme}><App /><VendoOverlay /></VendoRoot>);\n`;
     return `/**\n` +
         ` * Add these wiring lines in your host:\n` +
         ` *   app.use("/api/vendo", mountVendo());\n` +
@@ -165,7 +309,7 @@ export function expressServerSource(typescript, auth = null) {
         `import { registry } from ${JSON.stringify(registrySpecifier)};\n` +
         types +
         `\nconst vendo = createVendo({\n` +
-        (auth === null ? `  principal: async () => null,\n` : authConfigLines(auth)) +
+        (auth === null ? anonymousPrincipalLines() : authConfigLines(auth)) +
         `  catalog: registry,\n` +
         `  policy: {}, // .vendo/policy.json: destructive asks, reads run\n` +
         `});\n\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,14 +14,15 @@ export interface RiskRecommendation {
     recommendation: string;
 }
 export interface InitPlan {
-    framework: HostFramework;
+    framework: Exclude<HostFramework, "unknown"> | "custom";
     root: string;
     writes: string[];
     codeChanges: Array<{
         path: string;
         diff: string;
     }>;
-    /** The one line init never writes itself: the user pastes it. */
+    /** Whatever wiring the run could not do safely itself (empty when the
+        layout auto-wire landed): the paste lines for the user. */
     manualSteps: string[];
     /** --agent only: deterministic extraction results, so an agent can act on
         real tool names instead of re-deriving them. */
@@ -53,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;
@@ -114,5 +115,14 @@ export interface StarProcess {
     repo URL instead, one line, no error noise. Exported for the timeout's
     direct unit test only. */
 export declare function starViaGh(spawnStar: NonNullable<InitOptions["spawnStar"]>, timeoutMs?: number): Promise<boolean>;
+/**
+ * The one bounded edit init makes to user-authored code (visible-surface fix,
+ * 0.4.1 E2E cert B3): mount the generated client wrapper around the layout's
+ * `{children}` and import it. Null — leave the file untouched, fall back to
+ * the printed paste — whenever a Vendo mount already exists (idempotence) or
+ * the file doesn't have exactly one JSX `{children}` to wrap (ambiguity).
+ * Exported for direct unit tests.
+ */
+export declare function wireNextLayout(source: string, wrapperSpecifier: string): string | null;
 /** 09-vendo §5 — idempotent, zero-question setup. */
 export declare function runInit(options: InitOptions): Promise<number>;