@vendoai/vendo 0.4.0

package/dist/wire/threads.js

@@ -0,0 +1,68 @@
+import { VendoError } from "@vendoai/core";
+import { registerActiveTurn, touchActiveTurn, trackTurnResponse } from "../turn-liveness.js";
+import { json, requestJson, route, string } from "./shared.js";
+/** The effective thread id the agent stamps on every turn response (03 §1). */
+const THREAD_ID_HEADER = "x-vendo-thread-id";
+/** 09 §3 — the /threads wire area: chat streaming plus thread list/get/delete. */
+export const threadRoutes = [
+    route("POST", "/threads", async ({ request, deps, context }) => {
+        const body = await requestJson(request);
+        const ctx = await context("chat");
+        void deps.telemetry?.track("agent_run", {});
+        // AGENT-3 (fast path): a propagated client disconnect aborts the request,
+        // which cancels the agent loop — provider calls stop instead of running to
+        // completion for a reader that is gone.
+        // ENG-353 (fallback): some runtimes never surface a graceful disconnect
+        // (`next dev` fires neither the signal nor a cancel), so a heartbeat-armed
+        // idle watchdog can abort the turn through the same controller. Consumers
+        // that never beat keep run-to-completion semantics.
+        const turnAbort = new AbortController();
+        if (request.signal.aborted)
+            turnAbort.abort();
+        else
+            request.signal.addEventListener("abort", () => turnAbort.abort(), { once: true });
+        const turn = await deps.agent.stream({
+            ...(body["threadId"] === undefined ? {} : { threadId: string(body["threadId"], "threadId") }),
+            message: body["message"],
+            ctx,
+            signal: turnAbort.signal,
+        });
+        const threadId = turn.headers.get(THREAD_ID_HEADER);
+        if (threadId === null)
+            return turn;
+        const unregister = registerActiveTurn({
+            threadId,
+            subject: ctx.principal.subject,
+            abort: () => turnAbort.abort(),
+        });
+        return trackTurnResponse(turn, unregister);
+    }),
+    // ENG-353 — turn-liveness beat. Principal-scoped: it refreshes only the
+    // caller's own in-flight turns, and unknown/foreign ids answer
+    // `active: false` (no oracle).
+    route("POST", "/threads/:id/heartbeat", async ({ context, params }) => {
+        const ctx = await context("chat");
+        const id = string(params["id"], "thread id");
+        return json({ active: touchActiveTurn(id, ctx.principal.subject) });
+    }),
+    route("GET", "/threads", async ({ deps, context }) => {
+        return json(await deps.agent.threads.list(await context("chat")));
+    }),
+    // Grouped like the old if-chain arm: ANY method resolves context first, and
+    // an unhandled method falls through to the table's not-found.
+    route("*", "/threads/:id", async ({ request, deps, context, params }) => {
+        const ctx = await context("chat");
+        const id = string(params["id"], "thread id");
+        if (request.method === "GET") {
+            const thread = await deps.agent.threads.get(id, ctx);
+            if (thread === null)
+                throw new VendoError("not-found", `thread not found: ${id}`);
+            return json(thread);
+        }
+        if (request.method === "DELETE") {
+            await deps.agent.threads.delete(id, ctx);
+            return json({});
+        }
+        return undefined;
+    }),
+];

package/package.json

@@ -0,0 +1,151 @@
+{
+  "name": "@vendoai/vendo",
+  "version": "0.4.0",
+  "description": "The Vendo umbrella: default composition, public wire routes, React provider, and the vendo CLI.",
+  "keywords": [
+    "ai",
+    "agent",
+    "genui",
+    "react",
+    "vendo"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/runvendo/vendo.git",
+    "directory": "packages/vendo"
+  },
+  "homepage": "https://vendo.run",
+  "bugs": "https://github.com/runvendo/vendo/issues",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "vendo": "bin/vendo.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./extract": {
+      "types": "./dist/cli/extract/index.d.ts",
+      "default": "./dist/cli/extract/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./ai-sdk": {
+      "types": "./dist/ai-sdk.d.ts",
+      "default": "./dist/ai-sdk.js"
+    },
+    "./mastra": {
+      "types": "./dist/mastra.d.ts",
+      "default": "./dist/mastra.js"
+    },
+    "./auth/auth0": {
+      "types": "./dist/auth-presets/auth0.d.ts",
+      "default": "./dist/auth-presets/auth0.js"
+    },
+    "./auth/auth-js": {
+      "types": "./dist/auth-presets/auth-js.d.ts",
+      "default": "./dist/auth-presets/auth-js.js"
+    },
+    "./auth/clerk": {
+      "types": "./dist/auth-presets/clerk.d.ts",
+      "default": "./dist/auth-presets/clerk.js"
+    },
+    "./auth/jwt": {
+      "types": "./dist/auth-presets/jwt.d.ts",
+      "default": "./dist/auth-presets/jwt.js"
+    },
+    "./auth/supabase": {
+      "types": "./dist/auth-presets/supabase.d.ts",
+      "default": "./dist/auth-presets/supabase.js"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "zod": "^3.25.0",
+    "@vendoai/actions": "0.4.0",
+    "@vendoai/core": "0.4.0",
+    "@vendoai/apps": "0.4.0",
+    "@vendoai/guard": "0.4.0",
+    "@vendoai/mcp": "0.4.0",
+    "@vendoai/agent": "0.4.0",
+    "@vendoai/automations": "0.4.0",
+    "@vendoai/ui": "0.4.0",
+    "@vendoai/telemetry": "0.3.0",
+    "@vendoai/store": "0.4.0"
+  },
+  "peerDependencies": {
+    "@auth/core": "^0.34.3",
+    "@clerk/backend": ">=1.0.0",
+    "@mastra/core": ">=1.0.0 <2",
+    "ai": ">=6.0.0 <7",
+    "jose": ">=5.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@auth/core": {
+      "optional": true
+    },
+    "@mastra/core": {
+      "optional": true
+    },
+    "@clerk/backend": {
+      "optional": true
+    },
+    "jose": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ai-sdk/anthropic": "3.0.12",
+    "@auth/core": "^0.34.3",
+    "@clerk/backend": "^3.11.7",
+    "@mastra/core": "1.51.0",
+    "@types/json-schema": "^7.0.15",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "ai": "6.0.28",
+    "jose": "^6.2.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build:playground": "node scripts/build-playground.mjs",
+    "prebuild": "pnpm run build:playground",
+    "build": "tsc -p tsconfig.json",
+    "pretest": "pnpm run build:playground",
+    "test": "vitest run",
+    "pretypecheck": "pnpm run build:playground",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest:coverage": "pnpm run build:playground",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/skills/vendo-setup/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: vendo-setup
+description: Install and configure Vendo (the embedded product agent) in a host repo. Use when asked to add Vendo to an app, run vendo init/doctor/sync, wire the Vendo handler or VendoRoot, or debug a Vendo install until doctor exits 0.
+---
+
+# Vendo setup
+
+Vendo embeds an agent inside a host product: it extracts the host's API as
+tools, renders generated UI in a sandboxed brand-native surface, and acts as
+the signed-in user. This skill installs and verifies Vendo in a host repo.
+
+The canonical agent playbook lives at https://vendo.run/agents.md —
+fetch it when you need more detail than this skill carries.
+
+## Stage 1 — base install
+
+1. Install the umbrella package (either name; `vendoai` is a thin alias):
+
+   ```bash
+   npm install @vendoai/vendo
+   ```
+
+2. Run init. As an agent, plan first, then apply:
+
+   ```bash
+   npx vendo init --agent   # read-only JSON plan: framework, code diffs, extracted tools, risk recommendations, aiPolish delegation contract
+   npx vendo init --yes
+   ```
+
+   `--agent` writes nothing. Init applies its bounded change set and lists
+   it; the only questions are an auth confirm when detection is uncertain, a
+   review of uncertain theme slots, and the end-of-init cloud-login offer
+   (`--yes` skips it). Each question has a non-interactive answer flag:
+   `--auth <preset>`, `--framework <name>`, `--theme <slot=value>`
+   (repeatable), `--cloud-key <key>` or `--byo`, and `--ai-polish` to consent
+   to the AI extraction pass. Prefer the interactive run when a human is
+   present.
+
+3. What init does (framework detected from `package.json`, `next` beats
+   `express`; anything else is treated as Next):
+   - Writes `.vendo/` — `tools.json` (extracted tools), `overrides.json`
+     (your risk/critical edits, respected forever), `policy.json`,
+     `brief.md`, `theme.json` (brand extracted from the host CSS), and a
+     gitignored `.vendo/data/` for the PGlite store. Commit `.vendo/`,
+     never `.vendo/data/`.
+   - Next.js: proposes `app/api/vendo/[...vendo]/route.ts` (or under
+     `src/app`), wraps the root layout in `<VendoRoot theme={...}>`, and
+     scaffolds a starter model module when the import cannot resolve.
+   - Express: proposes `vendo/server.ts` (`.mjs` without a tsconfig) plus a
+     starter `vendo/ai.ts`; you must still mount
+     `app.use("/api/vendo", mountVendo())` and wrap the client in
+     `<VendoRoot>` yourself.
+   - Adds `predev`/`prebuild` sync hooks to `package.json` (consent-gated).
+
+4. Model credential: the starter model module uses
+   `createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY })`. Install its
+   pinned peers and set the key:
+
+   ```bash
+   npm install ai@^6 @ai-sdk/anthropic@^3
+   echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env.local
+   ```
+
+   Never invent a key; ask the user for one if none is set. Any AI SDK
+   provider works — point `vendo refine --model-import` at the host's own
+   model module when one exists.
+
+5. Verify. Start the dev server, then:
+
+   ```bash
+   npx vendo doctor
+   ```
+
+   Doctor checks wiring plus one live `/status` round-trip against
+   `http://localhost:3000/api/vendo` (override with `--url` or `VENDO_URL`).
+   Exit 0 = green; exit 1 prints each `broken:` line. Fix and re-run until 0.
+   Common fixes: dev server not running (start it), missing `.vendo/*` file
+   (re-run `npx vendo init`), layout not wrapped (apply the skipped diff by
+   re-running init and approving it).
+
+## Stage 2 — review and keep extraction fresh
+
+- AI polish, delegated to you: the `--agent` plan's `aiPolish` object is a
+  contract you can execute yourself. Read the codebase per
+  `aiPolish.instructions` (task-oriented tool descriptions, risk review,
+  wakes with reasoning, the product brief), write one JSON draft matching
+  `aiPolish.draftSchema` to a file, then:
+
+  ```bash
+  npx vendo extract --apply draft.json
+  ```
+
+  Vendo runs the same deterministic guards as init's built-in pass (only
+  extracted tool names accepted, risk raised never lowered, wakes need
+  reasoning plus a grade, human decisions win), writes
+  `.vendo/overrides.json` and `.vendo/brief.md`, and re-syncs. Non-zero exit
+  means the draft was rejected with the reason printed; fix and re-apply.
+  `--force` replaces a hand-edited brief; leave it off otherwise.
+- Re-extract after API changes: `npx vendo sync` (fail-soft). In CI use
+  `npx vendo sync --strict` — exit 2 on breaking tool changes, 3 when saved
+  apps/automations/grants are impacted. `--json` emits one machine-readable
+  report object on stdout.
+- Review `.vendo/tools.json`; put corrections in `.vendo/overrides.json`
+  (`{"tools": {"host_invoices_delete": {"critical": true}}}`) — never edit
+  `tools.json` by hand, sync regenerates it.
+- Tighten `.vendo/policy.json` rules (`ask` for destructive, `run` for read)
+  and write a real product brief in `.vendo/brief.md`.
+
+## Stage 3 — unlocks
+
+- **MCP door** (agents like Claude/ChatGPT use the product's tools): a host
+  decision, never a default. Needs a `HostOAuthAdapter` and
+  `createVendo({ mcp: true, oauth })`, then `npx vendo mcp server-json` and
+  `npx vendo mcp verify-domain`. Doctor validates the discovery documents.
+- **Sandbox / connectors / voice / persistence on Postgres**: doctor's final
+  ladder line names what each remaining block unlocks; see
+  https://docs.vendo.run for each capability.
+- **Vendo Cloud**: sharing, org overlays, and hosted automations activate
+  with `VENDO_API_KEY` (`npx vendo login`).
+
+## Rules
+
+- Show the user every proposed code diff before applying it unless they
+  explicitly asked for unattended setup.
+- Do not hand-edit generated files (`.vendo/tools.json`, theme regeneration);
+  use `overrides.json` and re-run sync.
+- Done means `npx vendo doctor` exits 0 against a running dev server, not
+  merely that files exist.