@waniwani/kit 0.1.4 → 0.1.6-beta.0

package/README.md

@@ -529,6 +529,54 @@ flowchart LR
 project carrying a `vercel.json`, which is what lets `vercel deploy` inside it
 work with no special support.
 
+### Deploying is a git push
+
+`waniwani build` writes a Vercel Build Output tree inside `.waniwani/`: the
+bundled function, the static assets, the routing config. A git-connected project
+builds that tree itself on push, and the first build writes the config it needs
+into the app repo:
+
+```json
+// vercel.json, generated once, yours to edit afterwards
+{
+  "framework": null,
+  "buildCommand": "waniwani build && rm -rf .vercel/output && cp -R .waniwani/.vercel/output .vercel/output",
+  "routes": [{ "src": "/api(/.*)?", "dest": "/mcp" }]
+}
+```
+
+Each line answers something Vercel would otherwise get wrong.
+
+`framework: null` stops the project's preset from hunting for a dependency the
+repo does not have, which is what produces `No Next.js version detected` on a
+repo holding no framework at all.
+
+The `buildCommand` moves the tree from `.waniwani/`, which is gitignored and
+absent from the clone, up to the one path where Vercel adopts the Build Output
+API and serves the function as built.
+
+The `routes` entry exists because Vercel reserves a root `api/` directory: it
+compiles every file under one into a serverless function of its own, and an
+endpoint module is not a Vercel handler. That entry is emitted ahead of Vercel's
+filesystem layer, so `/api/*` reaches the server the kit built and the functions
+Vercel made are never routed to. Deleting the directory during the build is not
+an alternative, since the file list is read before the build command runs:
+
+```
+Error: File not found: /vercel/path0/api/cal/book.ts
+```
+
+Deploying without a build works too, once `build` has run:
+
+```bash
+cd .waniwani && vercel deploy --prebuilt
+```
+
+Environment variables live on the platform for both, since `.env` is read from
+disk and a hosted build has no such file. A project that sets its variables for
+production alone gets previews with none, which for an app whose flow reads
+`WANIWANI_API_KEY` at import time means a function that fails to boot.
+
 ### Secrets live in the app's .env
 
 `.env` and `.env.local` sit next to `waniwani.config.ts`, and every command reads

package/cli/codegen.mjs

@@ -44,9 +44,34 @@ import { fileURLToPath } from "node:url";
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const RUNTIME_SRC = join(PACKAGE_ROOT, "src");
-const PACKAGE_VERSION = JSON.parse(
-	readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"),
-).version;
+/** This package's own manifest, which is where every version below comes from. */
+const MANIFEST = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf-8"));
+const PACKAGE_VERSION = MANIFEST.version;
+
+/**
+ * A version this package declares, read back out so it is stated once.
+ *
+ * Every version the generator forces on an app is a version the generator was
+ * built and verified against, which makes this manifest the only honest source
+ * for it. Writing the same range a second time as a literal down in `PINS` gave
+ * one fact two homes, and a bump could update either one alone: the manifest
+ * carried `skybridge@^1.3.5` while the pin forced `1.4.0`, and they agreed only
+ * because that is what the lockfile happened to resolve.
+ *
+ * Missing throws rather than defaults. `undefined` here would land in a
+ * generated `package.json` as a dependency with no version and fail at install
+ * time in someone else's project, a long way from the rename that caused it.
+ */
+function declared(name, field = "dependencies") {
+	const version = MANIFEST[field]?.[name];
+	if (!version) {
+		throw new Error(
+			`@waniwani/kit declares no ${field}.${name}, and the generator pins apps to it — ` +
+				"add it back to packages/kit/package.json or drop it from PINS",
+		);
+	}
+	return version;
+}
 
 /**
  * The template comes across whole, minus an explicit list.
@@ -160,17 +185,27 @@ const SEAM = { file: "src/server.ts", symbol: "registerApp" };
  *
  * Each entry carries its reason, and the CLI reports what it changed.
  */
-/** Forced to an exact version: the generated code is built against these. */
+/**
+ * Forced to what this package declares: the generated code is built against
+ * these, and `declared()` is what keeps the two statements of that one fact
+ * from drifting apart.
+ */
 const PINS = {
 	dependencies: {
 		skybridge: {
-			version: "1.4.0",
+			version: declared("skybridge"),
 			why: "the template's range floats within 1.x; the runtime is built and verified against this one",
 		},
-		"@waniwani/sdk": { version: "^0.19.5", why: "flows and tracking need the current SDK" },
+		"@waniwani/sdk": {
+			version: declared("@waniwani/sdk"),
+			why: "flows and tracking need the current SDK",
+		},
 	},
 	devDependencies: {
-		"@skybridge/devtools": { version: "1.4.0", why: "must match the framework" },
+		"@skybridge/devtools": {
+			version: declared("@skybridge/devtools", "devDependencies"),
+			why: "must match the framework",
+		},
 	},
 };
 
@@ -186,6 +221,36 @@ const ENSURED = {
 	},
 };
 
+/**
+ * What the vendored runtime needs declared, for the eject layout only.
+ *
+ * A build reaches the runtime through `@waniwani/kit`, so express, cors and
+ * their types arrive as that package's own dependencies — which is why it
+ * declares them (see its `//dependencies` and `//express` notes). Ejecting drops
+ * the package and copies `src/` in as source, and the imports come with it: the
+ * vendored tree imports `express` and `cors` by name, and `tsc` needs their
+ * types. Nothing was putting either back, so an ejected project installed and
+ * then failed to compile on ten TS7006/TS7016 errors, with express and cors
+ * present in `node_modules` only as a transitive hoist out of the framework.
+ *
+ * Only the two the runtime imports and the app does not already get: `skybridge`
+ * and `zod` are the other bare specifiers under `src/`, and both are declared
+ * for every layout already.
+ */
+const VENDORED = {
+	dependencies: {
+		express: { version: declared("express"), why: "the vendored runtime imports express" },
+		cors: { version: declared("cors"), why: "the vendored runtime mounts CORS per endpoint" },
+	},
+	devDependencies: {
+		"@types/express": {
+			version: declared("@types/express"),
+			why: "the vendored runtime is typed against express",
+		},
+		"@types/cors": { version: declared("@types/cors"), why: "same, for cors" },
+	},
+};
+
 /**
  * Scripts the generated layout needs, added only when the template has no
  * script by that name. The template's own scripts are left untouched.
@@ -625,6 +690,13 @@ export const app = {
 	title: config.title,
 	version: config.version ?? ${JSON.stringify(version ?? "0.0.0")},
 	instructions: config.instructions,
+	// Forwarded whole, for the template to read if it has anything to read them
+	// with: \`search\` tunes the search tool a template ships, \`tracking\` reaches
+	// the SDK's withWaniwani(). A template that uses neither ignores both, so
+	// emitting them unconditionally keeps one generator working across templates
+	// that read them and templates that do not.
+	search: config.search,
+	tracking: config.tracking,
 };
 
 export async function registerApp(server: McpServer): Promise<void> {
@@ -779,6 +851,16 @@ function generatePackageJson(app, appPackageJson, template, layout) {
 			overrides.push({ name, to: version, why });
 		}
 
+		// Same rule as ENSURED — an app or template declaring its own keeps it —
+		// but only where the runtime arrives as source rather than as a package.
+		if (layout.vendored) {
+			for (const [name, { version, why }] of Object.entries(VENDORED[kind] ?? {})) {
+				if (merged[name]) continue;
+				merged[name] = version;
+				overrides.push({ name, to: version, why });
+			}
+		}
+
 		return merged;
 	};
 
@@ -875,6 +957,51 @@ function readProvenance(root) {
 	}
 }
 
+/**
+ * What a git-connected Vercel project needs at the app root, written there when
+ * the app has none.
+ *
+ * The build output lands in `.waniwani/`, which is gitignored and absent from
+ * the clone, so a hosted build has to run the kit itself and move the tree to
+ * the one path where Vercel adopts the Build Output API. Every line here is
+ * about this kit's own layout, which is why the file is generated rather than
+ * taken from the template: the template knows nothing about `waniwani build` or
+ * `.waniwani/`.
+ *
+ * The `routes` entry is the part that is not obvious. Vercel reserves a root
+ * `api/` directory and compiles every file under it into a serverless function
+ * of its own, which for an app folder means one broken function per endpoint
+ * (`defineEndpoint({ ... })` is an object, not a Vercel handler) sitting in the
+ * filesystem layer ahead of the server that actually serves them. A legacy
+ * `routes` entry is emitted before that layer, so `/api/*` reaches the kit's
+ * function and Vercel's own are never routed to. There is no way to stop it
+ * building them: it reads the file list before the build command runs, so a
+ * build that deletes the directory fails with `File not found`, and
+ * `outputDirectory` does not suppress it either.
+ */
+const VERCEL_JSON = {
+	$schema: "https://openapi.vercel.sh/vercel.json",
+	// Otherwise the project's framework preset decides, and a preset looking for a
+	// dependency an app folder does not have fails the build outright.
+	framework: null,
+	buildCommand:
+		"waniwani build && rm -rf .vercel/output && cp -R .waniwani/.vercel/output .vercel/output",
+	// Ahead of Vercel's filesystem layer, which is where its own api/ functions sit.
+	routes: [{ src: "/api(/.*)?", dest: "/mcp" }],
+};
+
+/**
+ * @returns true when the file was written, for the CLI to report
+ */
+function ensureVercelJson(appRoot) {
+	const file = join(appRoot, "vercel.json");
+	// An app that has edited its own deploy config keeps it. Overwriting would
+	// throw away a `maxDuration`, a region, or a cron someone needed.
+	if (existsSync(file)) return false;
+	writeFileSync(file, `${JSON.stringify(VERCEL_JSON, null, 2)}\n`);
+	return true;
+}
+
 /** Keep `.waniwani/` out of the app repo, the way `.next/` is kept out. */
 function ignoreBuildOutput(appRoot) {
 	const file = join(appRoot, ".gitignore");
@@ -1037,6 +1164,17 @@ export function generate(app, { template, layout: layoutName = "build", outDir }
 				sha: template.sha,
 				local: template.local,
 				manifest: manifest ? MANIFEST_FILE : undefined,
+				// Which generator wrote this tree, and the versions it forced
+				// while doing it. A deployed app misbehaving is the case this
+				// serves: the tree itself then answers which template commit and
+				// which SDK it was built from, without a guess from the app's
+				// lockfile or from whatever the CLI happens to pin today.
+				kit: PACKAGE_VERSION,
+				pins: Object.fromEntries(
+					Object.values(PINS).flatMap((group) =>
+						Object.entries(group).map(([name, pin]) => [name, pin.version]),
+					),
+				),
 				// What survived to the end, copied and generated alike. The
 				// copy is the raw list minus whatever a generated file replaced,
 				// and the generated half is here so that a build which stops
@@ -1055,11 +1193,23 @@ export function generate(app, { template, layout: layoutName = "build", outDir }
 		)}\n`,
 	);
 
+	let vercelJson = false;
 	if (layoutName === "build") {
 		// A .gitignore inside the output would stop `vercel deploy` uploading
 		// anything, so the ignore goes in the app repo instead.
 		ignoreBuildOutput(app.root);
+		// Same reasoning for the deploy config: what Vercel reads on a git build is
+		// the app repo's root, not the output directory.
+		vercelJson = ensureVercelJson(app.root);
 	}
 
-	return { outDir: root, written, overrides, fromTemplate, moved, manifest: Boolean(manifest) };
+	return {
+		outDir: root,
+		written,
+		overrides,
+		fromTemplate,
+		moved,
+		vercelJson,
+		manifest: Boolean(manifest),
+	};
 }

package/cli/index.mjs

@@ -143,7 +143,12 @@ async function prepare(appRoot, flags, { quiet = false } = {}) {
 		console.log(`${yellow("!")} ${dim("GitHub unreachable — using the cached template")}`);
 	}
 
-	const { outDir, overrides, fromTemplate, manifest } = generate(app, { template });
+	const { outDir, overrides, fromTemplate, manifest, vercelJson } = generate(app, { template });
+	// Written into the app's own repo rather than the output, so it is worth a
+	// line even outside debug: it is a tracked file that appeared.
+	if (!quiet && vercelJson) {
+		console.log(`${green("+")} ${bold("vercel.json")} ${dim("— deploy config for a git-connected project")}`);
+	}
 	if (!quiet && DEBUG) {
 		console.log(
 			`${dim(`${fromTemplate.length} files copied`)} ${dim(

package/cli/template.mjs

@@ -19,13 +19,35 @@ import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
 /**
- * `beta`, not `main`. The generator is written against the template's current
- * layout — `vite.config.ts`, `src/server.ts`, `src/views/` — and `main` is still
- * the older `server/` + `web/` + `api/` split, which it cannot absorb. When beta
- * merges down, this goes back to a ref on `main` (a tag, ideally — see the
- * README's known gaps).
+ * A commit, not a branch.
+ *
+ * A published version of this package is frozen, and what it generates has to
+ * be frozen with it. While the default was `beta`, the ref was re-resolved on
+ * the customer's machine at every command, so a push to that branch changed the
+ * output of every installed copy, and the assertions that catch a layout move
+ * (`REQUIRED` and `assertSeam` in `./codegen.mjs`) fired in a customer's
+ * terminal. Pinning a commit moves that failure into this repo's CI, where
+ * `scripts/template-contract.mjs` builds a real app against the pin before a
+ * release goes out.
+ *
+ * Bumping it is a one-line diff, and `scripts/bump-deps.mjs` proposes it. The
+ * commit is on the template's `beta` branch: the generator is written against
+ * that branch's layout (`vite.config.ts`, `src/server.ts`, `src/views/`), and
+ * `main` is still the older `server/` + `web/` + `api/` split, which it cannot
+ * absorb. An annotated tag can replace the SHA here whenever the template grows
+ * one, with no change to the resolver.
+ *
+ * This commit is `beta`'s head, and it reads `search` and `tracking` off
+ * `src/waniwani.ts` — the two fields `generateServerApp` emits from the app's
+ * `defineApp({ ... })`. That pairing is the reason to bump the two together:
+ * moving the pin here without the generator emitting those fields compiles to
+ * TS2339, and the contract is what catches it.
+ *
+ * Working on the template itself does not need a release: pass `--template` or
+ * set `WANIWANI_TEMPLATE` to a branch ref or a local checkout.
  */
-export const DEFAULT_TEMPLATE = "github:WaniWani-AI/mcp-distribution-template#beta";
+export const DEFAULT_TEMPLATE =
+	"github:WaniWani-AI/mcp-distribution-template#c0d00e72a3733a5f42389731fe6bbaf7e0e07863";
 
 const CACHE_ROOT = join(homedir(), ".cache", "waniwani", "templates");
 
@@ -36,11 +58,21 @@ function parseGithub(source) {
 	return { owner: match[1], repo: match[2], ref: match[3] ?? "main" };
 }
 
+/** A full commit SHA, which is already the thing a ref has to be resolved to. */
+function isSha(ref) {
+	return /^[0-9a-f]{40}$/i.test(ref);
+}
+
 /**
  * Resolve a ref to a commit SHA, so a cache entry is content-addressed and two
  * builds of the same ref cannot silently differ.
  */
 async function resolveSha({ owner, repo, ref }) {
+	// The pinned default is a commit, and asking the API to resolve a commit to
+	// itself is a round trip that can rate-limit, fail, or go down. A cached
+	// pin then needs no network at all, which is the point of pinning.
+	if (isSha(ref)) return ref.toLowerCase();
+
 	let response;
 	try {
 		response = await fetch(`https://api.github.com/repos/${owner}/${repo}/commits/${ref}`, {
@@ -148,5 +180,11 @@ export async function resolveTemplate(source = DEFAULT_TEMPLATE) {
 export function describeTemplate(template) {
 	if (template.local) return `${template.dir} (local)`;
 	const state = template.offline ? "offline, cached" : template.cached ? "cached" : "downloaded";
-	return `${template.source} @ ${template.sha?.slice(0, 7)} (${state})`;
+	// A pinned source already carries the commit, so printing the source verbatim
+	// would repeat all 40 characters of it next to the short form. Collapse to
+	// the repo, and say that the commit came from a pin rather than a branch.
+	const github = parseGithub(template.source);
+	const pinned = github && isSha(github.ref);
+	const origin = pinned ? `github:${github.owner}/${github.repo}` : template.source;
+	return `${origin} @ ${template.sha?.slice(0, 7)} (${pinned ? `pinned, ${state}` : state})`;
 }

package/dist/index.d.ts

@@ -35,6 +35,100 @@ export type ToolHints = {
     /** Calling twice with the same input has the same effect as calling once. */
     idempotent?: boolean;
 };
+/**
+ * What an app may set on the template's `search` tool.
+ *
+ * Declared here and again in the template's `src/search/index.ts`, on purpose:
+ * the template does not depend on this package, so there is no type to share.
+ * The two meet at the generated `waniwani.ts` and nowhere else, which makes this
+ * a mirror that has to be kept in step by hand. A field added on one side and
+ * not the other is silently dropped rather than reported.
+ */
+export type SearchOptions = {
+    /**
+     * Whether the template registers the tool at all.
+     *
+     * `false` is the only way an app can decline it, because it cannot unregister
+     * what the template has already registered. Worth using: a deployment with no
+     * corpus behind it, or one holding another market's documents, is better off
+     * without the tool than with one answering confidently out of the wrong file.
+     */
+    enabled?: boolean;
+    /** Passages to ask for, 1-20. Unset leaves the SDK's default of 5. */
+    topK?: number;
+    /**
+     * Similarity floor, 0-1, under which a passage is dropped rather than ranked
+     * last. Unset leaves the SDK's default of 0.3.
+     */
+    minScore?: number;
+    /**
+     * Exact-match filter on chunk metadata: a passage must carry all of these
+     * pairs to come back. With the corpus tagged at ingest time, this is a gate in
+     * code rather than a line of prompt.
+     */
+    metadata?: Record<string, string>;
+    /** Give up on a slow search and answer as though nothing matched. */
+    timeoutMs?: number;
+    /** Name the source document on each passage. */
+    includeSources?: boolean;
+    /**
+     * Framing prepended to the answer text. Retrieved passages are third-party
+     * text on its way into a prompt; this is where an app says they are reference
+     * material rather than instructions.
+     */
+    preamble?: string;
+    /**
+     * Status text the host shows while the call is in flight, and once it has
+     * returned. Configurable because the defaults are English and this string is
+     * one of the few a user actually reads.
+     */
+    invoking?: string;
+    invoked?: string;
+};
+/** The event categories the tracking backend recognises. */
+export type ToolType = "pricing" | "product_info" | "availability" | "support" | "other";
+/**
+ * Tracking options, forwarded whole to the SDK's `withWaniwani()`.
+ *
+ * A mirror of that function's options for the same reason as `SearchOptions`
+ * above, narrowed to what an app declares rather than constructs: the SDK also
+ * accepts a `client` instance and an `onError` callback, and neither belongs in a
+ * config file.
+ *
+ * `flushAfterToolCall` is the one that matters on serverless. An invocation
+ * frozen between tool calls takes any unsent event batch with it, and this is
+ * the only way an app can ask for the flush.
+ */
+export type TrackingOptions = {
+    /** One category for every tool, or a function mapping tool name to category. */
+    toolType?: ToolType | ((toolName: string) => ToolType | undefined);
+    /** Merged into every tracked event. */
+    metadata?: Record<string, unknown>;
+    /** Flush the tracking transport after each tool call. */
+    flushAfterToolCall?: boolean;
+    /**
+     * Put widget tracking config in each tool response's `_meta.waniwani`, so a
+     * widget in the browser can send its own events.
+     *
+     * @default true
+     */
+    injectWidgetToken?: boolean;
+    /**
+     * Field names to strip from location `_meta` before events are sent. Pass
+     * `["latitude", "longitude"]` to drop coordinates and keep the rest.
+     *
+     * @default []
+     */
+    stripLocationFields?: readonly string[];
+    /**
+     * Replace flow state fields marked with `redacted()` before they are tracked.
+     * Wire it to an env var to keep real values in development and redact in
+     * production.
+     *
+     * @default false
+     */
+    applyFieldRedactions?: boolean;
+};
 export type AppConfig = {
     /** MCP server name, e.g. `oney-split-payment`. */
     name: string;
@@ -47,6 +141,14 @@ export type AppConfig = {
      * call. Tone, guardrails, what this app is for.
      */
     instructions?: string;
+    /**
+     * Tune, or decline, the `search` tool the template ships. Reaches the
+     * template through the generated `waniwani.ts`; a template that ships no such
+     * tool ignores it.
+     */
+    search?: SearchOptions;
+    /** Tracking behaviour for every tool call this app serves. */
+    tracking?: TrackingOptions;
 };
 export declare function defineApp(config: AppConfig): AppConfig;
 /**

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA2CH,MAAM,UAAU,SAAS,CAAC,MAAiB;IAC1C,OAAO,MAAM,CAAC;AACf,CAAC;AAwBD,MAAM,UAAU,UAAU,CACzB,GAAyB;IAEzB,OAAO,GAAG,CAAC;AACZ,CAAC;AAuCD,MAAM,UAAU,YAAY,CAAkB,GAAwB;IACrE,OAAO,GAAG,CAAC;AACZ,CAAC;AA4CD,MAAM,UAAU,cAAc,CAAC,GAAuB;IACrD,OAAO,GAAG,CAAC;AACZ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoJH,MAAM,UAAU,SAAS,CAAC,MAAiB;IAC1C,OAAO,MAAM,CAAC;AACf,CAAC;AAwBD,MAAM,UAAU,UAAU,CACzB,GAAyB;IAEzB,OAAO,GAAG,CAAC;AACZ,CAAC;AAuCD,MAAM,UAAU,YAAY,CAAkB,GAAwB;IACrE,OAAO,GAAG,CAAC;AACZ,CAAC;AA4CD,MAAM,UAAU,cAAc,CAAC,GAAuB;IACrD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waniwani/kit",
-  "version": "0.1.4",
+  "version": "0.1.6-beta.0",
   "description": "Build an MCP app as a folder: tools, widgets and flows, with one CLI and one shared server runtime.",
   "type": "module",
   "bin": {
@@ -25,6 +25,7 @@
   "//files": "`src` ships alongside `dist` on purpose: `waniwani eject` vendors the runtime as readable TypeScript, and it reads it out of the installed package.",
   "//dependencies": "tsx, typescript and the @types packages are here rather than in devDependencies because the underlying framework shells out to tsc and tsx by bare name and resolves types from the app repo tree, while declaring none of them. An app repo owns no build config, so this package is the only thing that can put them there. nodemon is the fourth of that set and arrives on its own, as a peer of it.",
   "//express": "express and cors back the api/ convention: the runtime mounts each endpoint with a JSON body parser and CORS, and an app's handlers are typed against express. Both are already skybridge's own dependencies at these ranges, so declaring them here adds no second copy — it stops an app from depending on a transitive hoist.",
+  "//skybridge": "skybridge and @skybridge/devtools are exact, and the two versions match each other. codegen.mjs forces both on every generated app by reading them back out of this file, so a range here would mean the kit was verified against whatever it resolved while apps were pinned to something else. Bumping them is scripts/bump-deps.mjs, and scripts/template-contract.mjs is what proves the bump.",
   "files": [
     "dist",
     "src",
@@ -48,18 +49,18 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
-    "@waniwani/sdk": "^0.19.5",
+    "@waniwani/sdk": "0.19.9-beta.0",
     "cors": "^2.8.6",
     "dotenv": "^17.4.1",
     "express": "^5.2.1",
-    "skybridge": "^1.3.5",
+    "skybridge": "1.4.0",
     "tailwindcss": "^4.3.3",
     "tsx": "^4.20.6",
     "typescript": "^6.0.2",
     "vite": "^8.1.5"
   },
   "devDependencies": {
-    "@skybridge/devtools": "^1.2.7"
+    "@skybridge/devtools": "1.4.0"
   },
   "peerDependencies": {
     "react": ">=19",

package/src/index.ts

@@ -42,6 +42,103 @@ export type ToolHints = {
 
 // ---------------------------------------------------------------- app config
 
+/**
+ * What an app may set on the template's `search` tool.
+ *
+ * Declared here and again in the template's `src/search/index.ts`, on purpose:
+ * the template does not depend on this package, so there is no type to share.
+ * The two meet at the generated `waniwani.ts` and nowhere else, which makes this
+ * a mirror that has to be kept in step by hand. A field added on one side and
+ * not the other is silently dropped rather than reported.
+ */
+export type SearchOptions = {
+	/**
+	 * Whether the template registers the tool at all.
+	 *
+	 * `false` is the only way an app can decline it, because it cannot unregister
+	 * what the template has already registered. Worth using: a deployment with no
+	 * corpus behind it, or one holding another market's documents, is better off
+	 * without the tool than with one answering confidently out of the wrong file.
+	 */
+	enabled?: boolean;
+	/** Passages to ask for, 1-20. Unset leaves the SDK's default of 5. */
+	topK?: number;
+	/**
+	 * Similarity floor, 0-1, under which a passage is dropped rather than ranked
+	 * last. Unset leaves the SDK's default of 0.3.
+	 */
+	minScore?: number;
+	/**
+	 * Exact-match filter on chunk metadata: a passage must carry all of these
+	 * pairs to come back. With the corpus tagged at ingest time, this is a gate in
+	 * code rather than a line of prompt.
+	 */
+	metadata?: Record<string, string>;
+	/** Give up on a slow search and answer as though nothing matched. */
+	timeoutMs?: number;
+	/** Name the source document on each passage. */
+	includeSources?: boolean;
+	/**
+	 * Framing prepended to the answer text. Retrieved passages are third-party
+	 * text on its way into a prompt; this is where an app says they are reference
+	 * material rather than instructions.
+	 */
+	preamble?: string;
+	/**
+	 * Status text the host shows while the call is in flight, and once it has
+	 * returned. Configurable because the defaults are English and this string is
+	 * one of the few a user actually reads.
+	 */
+	invoking?: string;
+	invoked?: string;
+};
+
+/** The event categories the tracking backend recognises. */
+export type ToolType = "pricing" | "product_info" | "availability" | "support" | "other";
+
+/**
+ * Tracking options, forwarded whole to the SDK's `withWaniwani()`.
+ *
+ * A mirror of that function's options for the same reason as `SearchOptions`
+ * above, narrowed to what an app declares rather than constructs: the SDK also
+ * accepts a `client` instance and an `onError` callback, and neither belongs in a
+ * config file.
+ *
+ * `flushAfterToolCall` is the one that matters on serverless. An invocation
+ * frozen between tool calls takes any unsent event batch with it, and this is
+ * the only way an app can ask for the flush.
+ */
+export type TrackingOptions = {
+	/** One category for every tool, or a function mapping tool name to category. */
+	toolType?: ToolType | ((toolName: string) => ToolType | undefined);
+	/** Merged into every tracked event. */
+	metadata?: Record<string, unknown>;
+	/** Flush the tracking transport after each tool call. */
+	flushAfterToolCall?: boolean;
+	/**
+	 * Put widget tracking config in each tool response's `_meta.waniwani`, so a
+	 * widget in the browser can send its own events.
+	 *
+	 * @default true
+	 */
+	injectWidgetToken?: boolean;
+	/**
+	 * Field names to strip from location `_meta` before events are sent. Pass
+	 * `["latitude", "longitude"]` to drop coordinates and keep the rest.
+	 *
+	 * @default []
+	 */
+	stripLocationFields?: readonly string[];
+	/**
+	 * Replace flow state fields marked with `redacted()` before they are tracked.
+	 * Wire it to an env var to keep real values in development and redact in
+	 * production.
+	 *
+	 * @default false
+	 */
+	applyFieldRedactions?: boolean;
+};
+
 export type AppConfig = {
 	/** MCP server name, e.g. `oney-split-payment`. */
 	name: string;
@@ -54,6 +151,14 @@ export type AppConfig = {
 	 * call. Tone, guardrails, what this app is for.
 	 */
 	instructions?: string;
+	/**
+	 * Tune, or decline, the `search` tool the template ships. Reaches the
+	 * template through the generated `waniwani.ts`; a template that ships no such
+	 * tool ignores it.
+	 */
+	search?: SearchOptions;
+	/** Tracking behaviour for every tool call this app serves. */
+	tracking?: TrackingOptions;
 };
 
 export function defineApp(config: AppConfig): AppConfig {