@vendoai/vendo 0.4.0

package/dist/mastra.d.ts

@@ -0,0 +1,46 @@
+import { type VendoToolPackFilter } from "@vendoai/agent";
+import { type Tool } from "@mastra/core/tools";
+import type { Vendo } from "./server.js";
+/**
+ * `@vendoai/vendo/mastra` — the BYO-agent seam for Mastra agents (frozen
+ * contract: docs/superpowers/specs/2026-07-20-existing-agents-contracts.md §2,
+ * async return amended Wave 1). The same framework-neutral tool pack as
+ * `./ai-sdk`, in Mastra `createTool` shape for the `Agent({ tools })` map.
+ *
+ * A Mastra agent definition is STATIC — one definition serves every user — so
+ * this shim takes no principal. Each call resolves its principal (and optional
+ * session id) lazily from Mastra's request context:
+ *
+ * ```ts
+ * const requestContext = new RequestContext();
+ * requestContext.set(VENDO_PRINCIPAL_KEY, { kind: "user", subject: userId });
+ * requestContext.set(VENDO_SESSION_KEY, hostSessionId); // optional
+ * await agent.stream(messages, { requestContext });
+ * ```
+ */
+export { VENDO_CREATE_APP_TOOL, VENDO_DELEGATE_TOOL, VENDO_TOOL_PACK_PREFIX, type VendoDelegateResult, type VendoToolPackFilter, } from "@vendoai/agent";
+/** Request-context key holding the caller's Vendo `Principal` (`{ kind, subject }`).
+ *  REQUIRED on every request that may reach a `vendo_*` tool — a missing or
+ *  malformed principal fails the call closed. */
+export declare const VENDO_PRINCIPAL_KEY = "vendo-principal";
+/** Optional request-context key carrying the host session id into Vendo's
+ *  audit trail; unset, the shim mints one per call. */
+export declare const VENDO_SESSION_KEY = "vendo-session-id";
+export type VendoMastraTool = Tool<unknown, unknown>;
+/**
+ * Build the Vendo tool pack as Mastra tools. Async (the pack enumerates the
+ * live registry), which composes with a static agent either way:
+ *
+ * ```ts
+ * // ESM top-level await:
+ * const agent = new Agent({ tools: { ...weatherTool, ...(await vendoMastraTools(vendo)) } });
+ * // or Mastra's dynamic tools function:
+ * const agent = new Agent({ tools: () => vendoMastraTools(vendo) });
+ * ```
+ *
+ * A `vendo_*` tool returns either a versioned envelope — `vendo/app-ref@1`
+ * (render with `<VendoAppEmbed>`) or `vendo/approval-ref@1` (parks server-side;
+ * render with `<VendoApprovalEmbed>`) — or plain data, meaning the guarded
+ * call executed cleanly.
+ */
+export declare function vendoMastraTools(vendo: Vendo, options?: VendoToolPackFilter): Promise<Record<string, VendoMastraTool>>;

package/dist/mastra.js

@@ -0,0 +1,88 @@
+import { buildVendoToolPack } from "@vendoai/agent";
+import { VendoError } from "@vendoai/core";
+// Static import of an OPTIONAL peer: this module only loads when the host
+// imports `@vendoai/vendo/mastra`, and a Mastra host has @mastra/core by
+// definition. Nothing outside this subpath touches it.
+import { createTool } from "@mastra/core/tools";
+/**
+ * `@vendoai/vendo/mastra` — the BYO-agent seam for Mastra agents (frozen
+ * contract: docs/superpowers/specs/2026-07-20-existing-agents-contracts.md §2,
+ * async return amended Wave 1). The same framework-neutral tool pack as
+ * `./ai-sdk`, in Mastra `createTool` shape for the `Agent({ tools })` map.
+ *
+ * A Mastra agent definition is STATIC — one definition serves every user — so
+ * this shim takes no principal. Each call resolves its principal (and optional
+ * session id) lazily from Mastra's request context:
+ *
+ * ```ts
+ * const requestContext = new RequestContext();
+ * requestContext.set(VENDO_PRINCIPAL_KEY, { kind: "user", subject: userId });
+ * requestContext.set(VENDO_SESSION_KEY, hostSessionId); // optional
+ * await agent.stream(messages, { requestContext });
+ * ```
+ */
+export { VENDO_CREATE_APP_TOOL, VENDO_DELEGATE_TOOL, VENDO_TOOL_PACK_PREFIX, } from "@vendoai/agent";
+/** Request-context key holding the caller's Vendo `Principal` (`{ kind, subject }`).
+ *  REQUIRED on every request that may reach a `vendo_*` tool — a missing or
+ *  malformed principal fails the call closed. */
+export const VENDO_PRINCIPAL_KEY = "vendo-principal";
+/** Optional request-context key carrying the host session id into Vendo's
+ *  audit trail; unset, the shim mints one per call. */
+export const VENDO_SESSION_KEY = "vendo-session-id";
+function principalFrom(context) {
+    const candidate = context?.requestContext?.get(VENDO_PRINCIPAL_KEY);
+    if (typeof candidate?.kind !== "string" || typeof candidate.subject !== "string") {
+        throw new VendoError("validation", `vendo tools need the caller's principal: set requestContext "${VENDO_PRINCIPAL_KEY}" to { kind, subject } before invoking the agent`);
+    }
+    return candidate;
+}
+function runContextFrom(context) {
+    const session = context?.requestContext?.get(VENDO_SESSION_KEY);
+    return {
+        principal: principalFrom(context),
+        // The frozen BYO context tuple — a chat surface that is not Vendo's, with
+        // the user present. Park-and-resume replays pin this tuple.
+        venue: "chat",
+        presence: "present",
+        sessionId: typeof session === "string" && session.length > 0
+            ? session
+            : `session_${globalThis.crypto.randomUUID()}`,
+    };
+}
+/**
+ * Build the Vendo tool pack as Mastra tools. Async (the pack enumerates the
+ * live registry), which composes with a static agent either way:
+ *
+ * ```ts
+ * // ESM top-level await:
+ * const agent = new Agent({ tools: { ...weatherTool, ...(await vendoMastraTools(vendo)) } });
+ * // or Mastra's dynamic tools function:
+ * const agent = new Agent({ tools: () => vendoMastraTools(vendo) });
+ * ```
+ *
+ * A `vendo_*` tool returns either a versioned envelope — `vendo/app-ref@1`
+ * (render with `<VendoAppEmbed>`) or `vendo/approval-ref@1` (parks server-side;
+ * render with `<VendoApprovalEmbed>`) — or plain data, meaning the guarded
+ * call executed cleanly.
+ */
+export async function vendoMastraTools(vendo, options) {
+    const pack = await buildVendoToolPack({
+        registry: vendo.guardedTools,
+        runner: vendo.agent.asRunner(),
+        ...(options?.include === undefined ? {} : { include: options.include }),
+        ...(options?.exclude === undefined ? {} : { exclude: options.exclude }),
+    });
+    const tools = {};
+    for (const entry of pack) {
+        tools[entry.name] = createTool({
+            id: entry.name,
+            description: entry.description,
+            inputSchema: entry.inputSchema,
+            execute: (inputData, context) => entry.execute(inputData, {
+                ctx: runContextFrom(context),
+                ...(context?.agent?.toolCallId === undefined ? {} : { callId: context.agent.toolCallId }),
+            }),
+        });
+    }
+    return tools;
+}

package/dist/react.d.ts

@@ -0,0 +1,10 @@
+import { VendoProvider } from "@vendoai/ui";
+import { type ComponentProps } from "react";
+export { createVendoClient, type VendoClient, type VendoClientConfig, VendoProvider, hostComponentMap, useVendoContext, useVendoDiscoverability, useVendoGreeting, useVendoTheme, useVendoTools, type ConnectorOption, type HostComponentsInput, defaultVendoGreeting, type VendoDiscoverability, type VendoGreeting, type ToolMeta, type ToolMetaMap, VendoAppEmbed, VendoApprovalEmbed, VendoToolResult, useActivity, useApp, useApps, useApprovals, useAutomations, useConnections, useConnectorCatalog, useGrants, useMobileTakeover, type MobileTakeover, type PollOptions, useSlotApp, useThreads, useVendoOverlay, type VendoOverlayController, useVendoStatus, useVendoThread, type VendoThreadApproval, ScriptedTransport, type DirectorCue, type DirectorScript, defaultVendoTheme, resolveTheme, themeCssVariables, useVoice, type UseVoiceResult, type OpenSurface, type InClientVenue, type PinDrift, type ShipDiff, type EditResult, type PinRebaseResult, type VersionEntry, type ConnectionAccount, type InitiatedConnection, type RunStatus, type RunRecord, type RunPlan, type AutomationEntry, type EnableResult, type Thread, type ThreadSummary, type GuardPosture, type VendoStatus, } from "@vendoai/ui";
+export { remixable, type RemixableRegistration, type RemixableReportOptions } from "./remixable.js";
+type ProviderProps = ComponentProps<typeof VendoProvider>;
+/** 09-vendo §1 — the UI provider prewired to the default wire base. */
+export declare function VendoRoot(props: Omit<ProviderProps, "client"> & {
+    client?: ProviderProps["client"];
+    baseUrl?: string;
+}): ReturnType<typeof VendoProvider>;

package/dist/react.js

@@ -0,0 +1,32 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createVendoClient, VendoProvider } from "@vendoai/ui";
+import { useMemo } from "react";
+// Named re-exports, not `export *`: this file is a "use client" boundary, and
+// Next's flight loader builds the client-reference manifest by statically
+// enumerating a client module's named exports — it cannot do that through
+// `export *`. This list must stay in exact parity with @vendoai/ui's public
+// surface (packages/ui/src/index.ts); react-export-parity.test.ts fails loudly
+// if a future ui export is missing here.
+export { 
+// client.ts
+createVendoClient, 
+// context.ts
+VendoProvider, hostComponentMap, useVendoContext, useVendoDiscoverability, useVendoGreeting, useVendoTheme, useVendoTools, 
+// chrome/discoverability.ts
+defaultVendoGreeting, 
+// chrome/embeds.tsx — the BYO-agent embeds (existing-agents)
+VendoAppEmbed, VendoApprovalEmbed, VendoToolResult, 
+// hooks/*
+useActivity, useApp, useApps, useApprovals, useAutomations, useConnections, useConnectorCatalog, useGrants, useMobileTakeover, useSlotApp, useThreads, useVendoOverlay, useVendoStatus, useVendoThread, ScriptedTransport, 
+// theme.ts
+defaultVendoTheme, resolveTheme, themeCssVariables, 
+// voice/use-voice.ts
+useVoice, } from "@vendoai/ui";
+export { remixable } from "./remixable.js";
+/** 09-vendo §1 — the UI provider prewired to the default wire base. */
+export function VendoRoot(props) {
+    const { client: configuredClient, baseUrl = "/api/vendo", ...providerProps } = props;
+    const defaultClient = useMemo(() => createVendoClient({ baseUrl }), [baseUrl]);
+    return _jsx(VendoProvider, { ...providerProps, client: configuredClient ?? defaultClient });
+}

package/dist/refine.d.ts

@@ -0,0 +1,244 @@
+import { type CapabilityMissEvent } from "@vendoai/core";
+import type { LanguageModel } from "ai";
+import { z } from "zod";
+export interface RefineOptions {
+    /** Host app root: `.vendo/` artifacts and source are read from here. */
+    root: string;
+    /** BYO ai-SDK model — the same provider-agnostic seam as `createVendo({ model })`. */
+    model: LanguageModel;
+    /** Mounted Vendo wire base of the running dev app (e.g. http://localhost:3000/api/vendo). */
+    url?: string;
+    fetchImpl?: typeof fetch;
+    /** Dev-interview answers (the CLI collects them; a hosted run passes transcripts). */
+    interview?: string[];
+    /** Injected miss feed; default reads `.vendo/data/misses.jsonl`. */
+    misses?: CapabilityMissEvent[];
+    /** Char budget for the source-context leg. */
+    sourceBudget?: number;
+    maxMisses?: number;
+}
+export interface RefineProbeCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+export interface RefineProbe {
+    tool: string;
+    /** verified = at least one live check passed and none failed; static-only = no live check possible. */
+    status: "verified" | "static-only" | "failed";
+    checks: RefineProbeCheck[];
+}
+export interface RefineChange {
+    /** Path relative to root (e.g. `.vendo/capabilities.json`). */
+    path: string;
+    before: string | null;
+    after: string;
+    diff: string;
+    /** Human-visible cautions (e.g. a proposed risk downgrade) shown beside the diff. */
+    warnings: string[];
+}
+export interface RefineDrop {
+    kind: "compound" | "brief" | "override" | "description" | "brief-update";
+    target: string;
+    reason: string;
+}
+/** The cloud-seam run record: inputs digest, raw proposals, probe results, and
+ * (once the caller applies) decisions. Plain JSON under `.vendo/data/refine/`
+ * — deliberately NOT a `vendo/*@N` contract format. */
+export interface RefineTranscript {
+    version: 0;
+    startedAt: string;
+    root: string;
+    url?: string;
+    inputs: {
+        tools: number;
+        misses: number;
+        interview: string[];
+        sourceFiles: string[];
+    };
+    proposals: RefineProposals;
+    dropped: RefineDrop[];
+    probes: RefineProbe[];
+    decisions: Array<{
+        path: string;
+        applied: boolean;
+    }>;
+}
+export interface RefineResult {
+    changes: RefineChange[];
+    probes: RefineProbe[];
+    dropped: RefineDrop[];
+    transcript: RefineTranscript;
+}
+declare const proposalsSchema: z.ZodObject<{
+    compounds: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        steps: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            tool: z.ZodString;
+            args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            if: z.ZodOptional<z.ZodString>;
+            forEach: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            tool: string;
+            id: string;
+            forEach?: string | undefined;
+            if?: string | undefined;
+            args?: Record<string, string> | undefined;
+        }, {
+            tool: string;
+            id: string;
+            forEach?: string | undefined;
+            if?: string | undefined;
+            args?: Record<string, string> | undefined;
+        }>, "many">;
+        rationale: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        steps: {
+            tool: string;
+            id: string;
+            forEach?: string | undefined;
+            if?: string | undefined;
+            args?: Record<string, string> | undefined;
+        }[];
+        inputSchema?: Record<string, unknown> | undefined;
+        rationale?: string | undefined;
+    }, {
+        name: string;
+        description: string;
+        steps: {
+            tool: string;
+            id: string;
+            forEach?: string | undefined;
+            if?: string | undefined;
+            args?: Record<string, string> | undefined;
+        }[];
+        inputSchema?: Record<string, unknown> | undefined;
+        rationale?: string | undefined;
+    }>, "many">>;
+    briefs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        text: z.ZodString;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        text: string;
+        tools?: string[] | undefined;
+    }, {
+        name: string;
+        text: string;
+        tools?: string[] | undefined;
+    }>, "many">>;
+    riskCorrections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        risk: z.ZodEnum<["read", "write", "destructive"]>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        risk: "read" | "write" | "destructive";
+        reason?: string | undefined;
+    }, {
+        tool: string;
+        risk: "read" | "write" | "destructive";
+        reason?: string | undefined;
+    }>, "many">>;
+    curation: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        disabled: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        disabled: boolean;
+        reason?: string | undefined;
+    }, {
+        tool: string;
+        disabled: boolean;
+        reason?: string | undefined;
+    }>, "many">>;
+    descriptions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        tool: string;
+        description: string;
+    }, {
+        tool: string;
+        description: string;
+    }>, "many">>;
+    briefUpdate: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    compounds?: {
+        name: string;
+        description: string;
+        steps: {
+            tool: string;
+            id: string;
+            forEach?: string | undefined;
+            if?: string | undefined;
+            args?: Record<string, string> | undefined;
+        }[];
+        inputSchema?: Record<string, unknown> | undefined;
+        rationale?: string | undefined;
+    }[] | undefined;
+    briefs?: {
+        name: string;
+        text: string;
+        tools?: string[] | undefined;
+    }[] | undefined;
+    riskCorrections?: {
+        tool: string;
+        risk: "read" | "write" | "destructive";
+        reason?: string | undefined;
+    }[] | undefined;
+    curation?: {
+        tool: string;
+        disabled: boolean;
+        reason?: string | undefined;
+    }[] | undefined;
+    descriptions?: {
+        tool: string;
+        description: string;
+    }[] | undefined;
+    briefUpdate?: string | undefined;
+}, {
+    compounds?: {
+        name: string;
+        description: string;
+        steps: {
+            tool: string;
+            id: string;
+            forEach?: string | undefined;
+            if?: string | undefined;
+            args?: Record<string, string> | undefined;
+        }[];
+        inputSchema?: Record<string, unknown> | undefined;
+        rationale?: string | undefined;
+    }[] | undefined;
+    briefs?: {
+        name: string;
+        text: string;
+        tools?: string[] | undefined;
+    }[] | undefined;
+    riskCorrections?: {
+        tool: string;
+        risk: "read" | "write" | "destructive";
+        reason?: string | undefined;
+    }[] | undefined;
+    curation?: {
+        tool: string;
+        disabled: boolean;
+        reason?: string | undefined;
+    }[] | undefined;
+    descriptions?: {
+        tool: string;
+        description: string;
+    }[] | undefined;
+    briefUpdate?: string | undefined;
+}>;
+export type RefineProposals = z.infer<typeof proposalsSchema>;
+export declare function runRefine(options: RefineOptions): Promise<RefineResult>;
+export {};