@mohasinac/appkit 4.70.0 → 4.71.2

package/dist/_internal/server/features/assistant/tools/builtin/get-my-orders.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { orderRepository } from "../../../../../../features/orders/repository/orders.repository.js";
+import { defineAssistantTool } from "../define.js";
+/**
+ * `getMyOrders` — A3's first PII-bearing tool, and the one that makes this a
+ * CUSTOMER assistant rather than a catalogue search bot. "Where is my order"
+ * is the question customers actually ask.
+ *
+ * ## 🛑 Why this is an explicit literal and never a spread
+ *
+ * `OrderDocument` is the worked example in Part A's "masking by field list is
+ * not masking by document" section, and reading the schema confirms every
+ * word of it:
+ *
+ * - **`shippingAddress?: string`** is flat free text and is **deliberately
+ *   absent from `ORDER_PII_FIELDS`** — its own comment explains that
+ *   encrypting it now would give one field two formats across old and new
+ *   rows. So it is a full delivery address sitting in plaintext.
+ * - **`deliveryCity` / `deliveryState` / `deliveryPincode` / `deliveryCountry`
+ *   are unencrypted ON PURPOSE** — they "decide tax and serviceability and
+ *   must stay QUERYABLE". City + state + PIN re-identifies a household on its
+ *   own.
+ *
+ * A `{...order}` spread would publish all of that to a third-party model on
+ * the first order with a legacy address. Hence: one object literal, nine named
+ * fields, no spread anywhere in this file — which is also what
+ * `audit-assistant-egress` R3 checks mechanically.
+ *
+ * ## 🛑 Why there is no `revealOrders()` here
+ *
+ * `OrderRepository.mapDoc` is **not** overridden, so reads return exactly
+ * what Firestore holds — meaning any encrypted field arrives as `enc:v1:…`.
+ * That *looks broken*, and the tempting fix is `orderRepository.revealOrders()`,
+ * which decrypts **everything**. That accessor is legitimate for a seller
+ * looking at their own dashboard and catastrophic reached from a model-facing
+ * tool.
+ *
+ * The fields below are chosen so the question is answerable WITHOUT decrypting
+ * anything: status, dates, totals, item titles and a tracking number are not
+ * PII and are never encrypted. Nothing here can return ciphertext, so nothing
+ * here needs a decrypt.
+ *
+ * ## `piiClass: "handle-only"`
+ *
+ * No raw identifier leaves this tool. The order id is minted as a per-turn,
+ * single-use handle (`../handles.ts`), so the model can refer to "your order"
+ * and the renderer substitutes the real id — a raw Firestore order id in
+ * model context is a stable cross-conversation correlator, which is
+ * pseudonymised personal data under DPDP.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:none
+ */
+/** Rule #6: a tool must not fan out unbounded. Recent orders answer the question. */
+const MAX_ORDERS = 5;
+/** Enough to say what the order was, without pasting a whole basket into context. */
+const MAX_ITEM_TITLES = 4;
+const inputSchema = z.object({
+    /** Optional free-text status filter, matched case-insensitively. */
+    status: z.string().optional(),
+});
+function isoDay(v) {
+    if (!v)
+        return null;
+    // Firestore hands back a Timestamp, a Date, or (on some legacy rows) a string.
+    const d = typeof v === "string"
+        ? new Date(v)
+        : v instanceof Date
+            ? v
+            : typeof v.toDate === "function"
+                ? v.toDate()
+                : null;
+    if (!d || Number.isNaN(d.getTime()))
+        return null;
+    return d.toISOString().slice(0, 10);
+}
+export const getMyOrdersTool = defineAssistantTool({
+    name: "getMyOrders",
+    description: "Look up the signed-in customer's own recent orders: current status, " +
+        "payment status, what was ordered, the total, and a tracking number when " +
+        "one exists. Use this for 'where is my order', 'has it shipped', or " +
+        "'what did I buy'. Never returns anyone else's orders.",
+    inputSchema,
+    piiClass: "handle-only",
+    execute: async (input, ctx) => {
+        /*
+         * 🛑 Scoped to ctx.userId, which the ROUTE set from the verified session —
+         * never from a model-supplied argument. There is deliberately no
+         * `userId` field on inputSchema: a tool that accepts one is one
+         * hallucinated id away from being a cross-tenant read.
+         */
+        const orders = await orderRepository.findByUser(ctx.userId);
+        const wanted = input.status?.trim().toLowerCase();
+        const filtered = wanted
+            ? orders.filter((o) => String(o.status).toLowerCase() === wanted)
+            : orders;
+        const recent = [...filtered]
+            .sort((a, b) => (isoDay(b.orderDate) ?? "").localeCompare(isoDay(a.orderDate) ?? ""))
+            .slice(0, MAX_ORDERS);
+        return recent.map((order) => ({
+            // A handle, never the raw id — see the piiClass note above.
+            orderHandle: ctx.handles.mint("order", order.id),
+            status: String(order.status),
+            paymentStatus: String(order.paymentStatus),
+            placedOn: isoDay(order.orderDate),
+            itemTitles: (order.items ?? []).slice(0, MAX_ITEM_TITLES).map((i) => i.productTitle),
+            itemCount: order.items?.length ?? 0,
+            total: typeof order.totalPrice === "number" ? order.totalPrice : null,
+            currency: typeof order.currency === "string" ? order.currency : null,
+            trackingNumber: typeof order.trackingNumber === "string" ? order.trackingNumber : null,
+            deliveredOn: isoDay(order.deliveryDate),
+        }));
+    },
+});

package/dist/_internal/server/features/assistant/tools/builtin/get-toggle-state.d.ts

@@ -0,0 +1,8 @@
+export interface ToggleStateResult {
+    id: string;
+    label: string;
+    enabled: boolean;
+}
+export declare const getToggleStateTool: import("../define").AssistantToolDef<{
+    query: string;
+}, readonly ToggleStateResult[]>;

package/dist/_internal/server/features/assistant/tools/builtin/get-toggle-state.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { siteSettingsRepository } from "../../../../../../features/admin/repository/site-settings.repository.js";
+import { TOGGLE_CATALOG } from "../../../../../shared/features/site-settings/toggle-catalog.js";
+import { defineAssistantTool } from "../define.js";
+/**
+ * `getToggleState` — 2E-ii (overhaul brief). Read-only. Lets the assistant
+ * answer "is maintenance mode on" / "is COD payment on right now" with a
+ * real, current answer instead of a guess or a stale training-time fact.
+ *
+ * Wraps 1A-vi's `TOGGLE_CATALOG` — the same closed, curated set of
+ * site-wide boolean switches the admin dashboard's search/pin surface
+ * already reads. Every value here is public-safe by construction: a
+ * disabled payment method or a closed support desk is already observable
+ * by trying to use it, which is why `common-toggles.ts`'s own write
+ * endpoint has always treated the catalog as a closed, non-secret set.
+ *
+ * 🛑 Deliberately NO write-capable sibling tool. Letting the model itself
+ * flip a toggle is a real safety question, left out of scope on purpose —
+ * see the 2E-ii design note in the overhaul plan. A human confirms every
+ * mutation through the dashboard card's own confirmation-gated path
+ * (9-ii); this tool only ever reads.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:none
+ */
+const inputSchema = z.object({
+    /** A fuzzy name for the toggle, e.g. "maintenance", "cash on delivery". */
+    query: z.string().min(1).max(100),
+});
+function getBooleanAtDotPath(obj, path) {
+    let cursor = obj;
+    for (const key of path.split(".")) {
+        if (typeof cursor !== "object" || cursor === undefined)
+            return undefined;
+        cursor = cursor[key];
+    }
+    return typeof cursor === "boolean" ? cursor : undefined;
+}
+export const getToggleStateTool = defineAssistantTool({
+    name: "getToggleState",
+    description: "Look up whether a named site-wide feature or payment method is currently " +
+        "enabled or disabled — e.g. maintenance mode, a payment method, EMI, GST, " +
+        "chat, the customer assistant itself, or the announcement bar. Returns the " +
+        "CURRENT, live state. Use this instead of guessing when the user asks " +
+        "whether something is 'on' or 'off' right now.",
+    inputSchema,
+    piiClass: "none",
+    execute: async (input) => {
+        const q = input.query.trim().toLowerCase();
+        const matches = TOGGLE_CATALOG.filter((t) => t.label.toLowerCase().includes(q) ||
+            t.id.includes(q.replace(/\s+/g, "-")) ||
+            (t.keywords?.some((k) => k.toLowerCase().includes(q)) ?? false));
+        if (matches.length === 0)
+            return [];
+        const settings = await siteSettingsRepository.getSingleton();
+        return matches.slice(0, 5).map((t) => ({
+            id: t.id,
+            label: t.label,
+            enabled: getBooleanAtDotPath(settings, t.dotPath) !== false,
+        }));
+    },
+});

package/dist/_internal/server/features/assistant/tools/builtin/index.d.ts

@@ -0,0 +1,38 @@
+import { getMyOrdersTool } from "./get-my-orders";
+import { searchFaqsTool } from "./search-faqs";
+import { searchProductsTool } from "./search-products";
+import { getToggleStateTool } from "./get-toggle-state";
+/**
+ * The registered tool set.
+ *
+ * A2 (`piiClass: "none"`) — public, projected, no auth beyond the route's:
+ *   · searchFaqs       wraps listPublicFaqs, the /faqs page's own function
+ *   · searchProducts   wraps listPublicProducts, what GET /api/products serves
+ *   · getToggleState   (2E-ii) wraps TOGGLE_CATALOG — read-only, no write sibling
+ *
+ * A3 (`piiClass: "handle-only"`) — the customer's own data:
+ *   · getMyOrders      scoped to ctx.userId from the verified session, with
+ *                      the order id minted as a per-turn handle and every
+ *                      address field deliberately absent
+ *
+ * 🛑 The A2/A3 split is the single most important line in Part A: A2 shipped
+ * and was verified with ZERO PII surface, so none of the privacy machinery
+ * had to be right before anything worked. A3 adds exactly one tool on top of
+ * a proven engine instead of making the first version a PII migration.
+ */
+export declare const BUILTIN_ASSISTANT_TOOLS: readonly [import("../define").AssistantToolDef<{
+    query: string;
+}, readonly import("./search-faqs").SearchFaqsResult[]>, import("../define").AssistantToolDef<{
+    query: string;
+    category?: string | undefined;
+    brand?: string | undefined;
+}, readonly import("./search-products").SearchProductsResult[]>, import("../define").AssistantToolDef<{
+    query: string;
+}, readonly import("./get-toggle-state").ToggleStateResult[]>, import("../define").AssistantToolDef<{
+    status?: string | undefined;
+}, readonly import("./get-my-orders").MyOrderResult[]>];
+export { searchFaqsTool, searchProductsTool, getMyOrdersTool, getToggleStateTool };
+export type { SearchFaqsResult } from "./search-faqs";
+export type { SearchProductsResult } from "./search-products";
+export type { MyOrderResult } from "./get-my-orders";
+export type { ToggleStateResult } from "./get-toggle-state";

package/dist/_internal/server/features/assistant/tools/builtin/index.js

@@ -0,0 +1,29 @@
+import { getMyOrdersTool } from "./get-my-orders.js";
+import { searchFaqsTool } from "./search-faqs.js";
+import { searchProductsTool } from "./search-products.js";
+import { getToggleStateTool } from "./get-toggle-state.js";
+/**
+ * The registered tool set.
+ *
+ * A2 (`piiClass: "none"`) — public, projected, no auth beyond the route's:
+ *   · searchFaqs       wraps listPublicFaqs, the /faqs page's own function
+ *   · searchProducts   wraps listPublicProducts, what GET /api/products serves
+ *   · getToggleState   (2E-ii) wraps TOGGLE_CATALOG — read-only, no write sibling
+ *
+ * A3 (`piiClass: "handle-only"`) — the customer's own data:
+ *   · getMyOrders      scoped to ctx.userId from the verified session, with
+ *                      the order id minted as a per-turn handle and every
+ *                      address field deliberately absent
+ *
+ * 🛑 The A2/A3 split is the single most important line in Part A: A2 shipped
+ * and was verified with ZERO PII surface, so none of the privacy machinery
+ * had to be right before anything worked. A3 adds exactly one tool on top of
+ * a proven engine instead of making the first version a PII migration.
+ */
+export const BUILTIN_ASSISTANT_TOOLS = [
+    searchFaqsTool,
+    searchProductsTool,
+    getToggleStateTool,
+    getMyOrdersTool,
+];
+export { searchFaqsTool, searchProductsTool, getMyOrdersTool, getToggleStateTool };

package/dist/_internal/server/features/assistant/tools/builtin/search-faqs.d.ts

@@ -0,0 +1,8 @@
+export interface SearchFaqsResult {
+    question: string;
+    answerText: string;
+    slug: string;
+}
+export declare const searchFaqsTool: import("../define").AssistantToolDef<{
+    query: string;
+}, readonly SearchFaqsResult[]>;

package/dist/_internal/server/features/assistant/tools/builtin/search-faqs.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { listPublicFaqs } from "../../../../../../features/faq/actions/faq-actions.js";
+import { defineAssistantTool } from "../define.js";
+/**
+ * `searchFaqs` — the first of A2's two zero-PII tools.
+ *
+ * Wraps `listPublicFaqs`, the EXACT function the public `/faqs` page already
+ * calls, with no new endpoint and no new projection. `listPublicFaqs` has no
+ * free-text query parameter — it filters only by `category` — so free text
+ * search is done the SAME way the public page already does it:
+ * `FAQSearchableList.tsx` fetches `listPublicFaqs(undefined, 200)` once
+ * ("fetch all, bounded" — the collection is small) and substring-matches in
+ * memory. This tool copies that exact matching logic rather than inventing a
+ * second one.
+ *
+ * `piiClass: "none"` — every field returned here is already rendered,
+ * unauthenticated, on a public page.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:none
+ */
+const STRIP_HTML = /<[^>]+>/g;
+/** Matches `FAQSearchableList.tsx`'s "fetch all, bounded" cap — the FAQ
+ * collection is small (21 seeded, ~55+ target per the memory recording why
+ * this shape was chosen), so one bounded read beats a second search index. */
+const FAQ_FETCH_CAP = 200;
+const MAX_RESULTS = 5;
+const inputSchema = z.object({
+    query: z.string().min(1).max(200),
+});
+export const searchFaqsTool = defineAssistantTool({
+    name: "searchFaqs",
+    description: "Search the site's published FAQ entries by keyword. Returns the matching " +
+        "question, a plain-text answer, and a slug for linking to the full entry. " +
+        "Use this for policy, shipping, returns, and how-it-works questions before " +
+        "answering from general knowledge.",
+    inputSchema,
+    piiClass: "none",
+    execute: async (input) => {
+        const all = await listPublicFaqs(undefined, FAQ_FETCH_CAP);
+        const q = input.query.trim().toLowerCase();
+        const matches = all.filter((faq) => {
+            const answerText = faq.answer.text.replace(STRIP_HTML, "").toLowerCase();
+            return (faq.question.toLowerCase().includes(q) ||
+                answerText.includes(q) ||
+                (faq.tags?.some((tag) => tag.toLowerCase().includes(q)) ?? false));
+        });
+        /*
+         * Explicit allow-list literal, no spread of `faq` — `FAQDocument` also
+         * carries `stats`, `priority`/`order`, `isActive`, timestamps, and admin
+         * metadata that a model has no use for and that is wasted context either
+         * way. Three fields out, always.
+         */
+        return matches.slice(0, MAX_RESULTS).map((faq) => ({
+            question: faq.question,
+            answerText: faq.answer.text.replace(STRIP_HTML, ""),
+            slug: faq.seo.slug,
+        }));
+    },
+});

package/dist/_internal/server/features/assistant/tools/builtin/search-products.d.ts

@@ -0,0 +1,16 @@
+export interface SearchProductsResult {
+    title: string;
+    slug: string | null;
+    price: number | null;
+    currentBid: number | null;
+    currency: string | null;
+    listingType: string | null;
+    condition: string | null;
+    mainImage: string | null;
+    storeName: string | null;
+}
+export declare const searchProductsTool: import("../define").AssistantToolDef<{
+    query: string;
+    category?: string | undefined;
+    brand?: string | undefined;
+}, readonly SearchProductsResult[]>;

package/dist/_internal/server/features/assistant/tools/builtin/search-products.js

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { listPublicProducts } from "../../../products/list-public.js";
+import { defineAssistantTool } from "../define.js";
+/**
+ * `searchProducts` — the second of A2's two zero-PII tools.
+ *
+ * Wraps `listPublicProducts`, the EXACT function `GET /api/products` already
+ * calls and returns to any anonymous browser with no further field-stripping
+ * — confirmed by reading that route, not assumed. So the data this tool can
+ * see is already public by design; nothing here is a new projection.
+ *
+ * What IS new here, deliberately: this tool does not return the raw `Row`
+ * (`Record<string, JsonValue>`, an unbounded serialized product doc). It
+ * picks a small, named field set. Not a security boundary — `/api/products`
+ * already ships every one of these fields and more to a stranger — but a
+ * context-budget one: a model doesn't need `categorySlugs`, `seo*`,
+ * `customFields`, or any of the other ~40 fields a product document carries
+ * to answer "is this in stock" or "how much is it".
+ *
+ * `piiClass: "none"` — same reasoning as searchFaqs: every field here is
+ * already rendered on a public listing page to anyone, signed in or not.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:none
+ */
+const MAX_RESULTS = 10;
+const inputSchema = z.object({
+    query: z.string().min(1).max(200),
+    category: z.string().optional(),
+    brand: z.string().optional(),
+});
+function readString(row, key) {
+    const v = row[key];
+    return typeof v === "string" ? v : null;
+}
+function readNumber(row, key) {
+    const v = row[key];
+    return typeof v === "number" ? v : null;
+}
+export const searchProductsTool = defineAssistantTool({
+    name: "searchProducts",
+    description: "Search the public product catalogue by keyword, with optional category or " +
+        "brand filters. Returns title, price (or current bid for auctions), " +
+        "condition, listing type, and store name for each match. Use this to " +
+        "answer questions about availability, price, or what a store sells.",
+    inputSchema,
+    piiClass: "none",
+    execute: async (input) => {
+        const result = await listPublicProducts({
+            q: input.query,
+            category: input.category,
+            brand: input.brand,
+            page: 1,
+            pageSize: MAX_RESULTS,
+        });
+        /*
+         * `listPublicProducts` returns `null` on executor failure (verified —
+         * its own return type is `PublicProductListResult | null`). A model
+         * asking "is X in stock" must get "I could not find that", never a
+         * thrown error surfaced as a tool failure that reads like X doesn't
+         * exist for a different reason.
+         */
+        if (!result)
+            return [];
+        return result.items.map((row) => ({
+            title: readString(row, "title") ?? "",
+            slug: readString(row, "slug"),
+            price: readNumber(row, "price"),
+            currentBid: readNumber(row, "currentBid"),
+            currency: readString(row, "currency"),
+            listingType: readString(row, "listingType"),
+            condition: readString(row, "condition"),
+            mainImage: readString(row, "mainImage"),
+            storeName: readString(row, "storeName"),
+        }));
+    },
+});

package/dist/_internal/server/features/assistant/tools/define.d.ts

@@ -0,0 +1,85 @@
+import type { z } from "zod";
+import type { PiiClass } from "../../../../../contracts/ai";
+import type { HandleRegistry } from "../handles";
+/**
+ * A tool the assistant may call. One tool = one capability, one input
+ * schema, one output projection — never a raw repository or document.
+ *
+ * ## 🛑 The output projection is MANDATORY, and that is the whole point
+ *
+ * `execute` always returns `TOutput`; there is no variant that returns a
+ * repository document, and no `execute?: ...` that would let a tool exist
+ * with no real behaviour yet. "Return the document and let the model figure
+ * out what to show" is exactly the shape Part A's "masking by field list is
+ * not masking by document" section warns about — `OrderDocument` alone
+ * carries a flat, never-encrypted `shippingAddress` string nothing in
+ * `ORDER_PII_FIELDS` protects.
+ *
+ * TypeScript cannot prove `TOutput` is an allow-list literal with no spread
+ * of a source document — that is a review-time and audit-time property, the
+ * same way `audit-public-projection-parity` already polices it for public API
+ * projections elsewhere in this codebase. `scripts/audit-assistant-egress.mjs`
+ * is the audit for THIS tree; see its header for what it checks mechanically.
+ *
+ * ## `piiClass` is honest about the SHAPE of a tool's output, not a promise
+ *
+ * It tells `turn.ts`'s router which providers may see this tool's result at
+ * all (`routeModel` refuses a training-tier provider anything but `"none"`).
+ * A tool that can return PII must declare `"redacted"` or `"handle-only"` —
+ * never `"none"` — regardless of how rare a PII-bearing result actually is,
+ * because the router decides once, for the whole conversation, before any
+ * tool has run.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:none
+ */
+export interface AssistantToolContext {
+    /** Firestore uid of the authenticated end user this turn is answering. */
+    userId: string;
+    /** Resolved roles for `userId`, for the `roles` eligibility check below. */
+    roles: readonly string[];
+    /** This turn's handle minter — see `../handles.ts`. Tools that touch
+     * anything PII-adjacent mint a handle instead of returning the raw value. */
+    handles: HandleRegistry;
+}
+export interface AssistantToolDef<TInput = unknown, TOutput = unknown> {
+    /** Stable, model-facing name — becomes the function-calling tool name. */
+    name: string;
+    /** Model-facing description. This is prompt content; write it for the model. */
+    description: string;
+    /** Validates the model's raw tool-call arguments before `execute` sees them. */
+    inputSchema: z.ZodType<TInput>;
+    /** Firestore-style permission string, same vocabulary as `ActionDef.permission`. */
+    permission?: string;
+    /** If set, the tool is eligible only when the caller holds one of these roles. */
+    roles?: readonly string[];
+    /** See the module docstring. Decides which providers may run this turn. */
+    piiClass: PiiClass;
+    /** Runs the tool. The return value IS the projection — see the module docstring. */
+    execute: (input: TInput, ctx: AssistantToolContext) => Promise<TOutput>;
+    /** Set to the shadowed tool's name to explicitly replace it in a registry
+     * merge — same policy as `mergeFunctionRegistries`'s `options.overrides`. */
+    overrides?: string;
+}
+/**
+ * Identity helper — exists only to drive type inference on `TInput`/`TOutput`
+ * at the call site, the same idiom as `defineFunction()` in
+ * `appkit/src/_internal/server/functions/define.ts`.
+ */
+export declare function defineAssistantTool<TInput, TOutput>(def: AssistantToolDef<TInput, TOutput>): AssistantToolDef<TInput, TOutput>;
+/**
+ * The type a HETEROGENEOUS collection of tools is stored as — a registry, a
+ * merge result, a turn context's `tools` field. `AssistantToolDef<TInput,
+ * TOutput>`'s `execute` is contravariant in `TInput`, so an array of tools
+ * with genuinely different input shapes (`{query: string}` vs `{query,
+ * category, brand}`, …) cannot unify under one concrete `AssistantToolDef<X,
+ * Y>` — TypeScript correctly rejects it, the same way it would reject mixing
+ * a `(s: string) => void` and a `(n: number) => void` in one array typed as
+ * either. `any` here is the standard, deliberate escape for exactly this
+ * shape (the same one tRPC routers and the Vercel AI SDK's tool registries
+ * use) — every call site still gets full inference at its OWN definition via
+ * `defineAssistantTool<TInput, TOutput>`; only the collection type erases it.
+ */
+export type AnyAssistantToolDef = AssistantToolDef<any, any>;

package/dist/_internal/server/features/assistant/tools/define.js

@@ -0,0 +1,8 @@
+/**
+ * Identity helper — exists only to drive type inference on `TInput`/`TOutput`
+ * at the call site, the same idiom as `defineFunction()` in
+ * `appkit/src/_internal/server/functions/define.ts`.
+ */
+export function defineAssistantTool(def) {
+    return def;
+}

package/dist/_internal/server/features/assistant/tools/json-schema.d.ts

@@ -0,0 +1,34 @@
+import type { z } from "zod";
+import type { JsonObject } from "../../../../../schemas/types";
+/**
+ * A minimal, self-contained Zod -> JSON Schema converter for assistant tool
+ * input schemas.
+ *
+ * ## 🛑 Not `zod.toJSONSchema()` — appkit pins zod `^3.24`, which has no such export
+ *
+ * This engine was originally built against zod 4's native `toJSONSchema()`
+ * (the consumer app depends on zod `^4.3.6`), but appkit is a separate
+ * package pinned to zod `^3.24` across 148 files — bumping that major
+ * version to accommodate one relocated feature is a cross-cutting dependency
+ * change this move did not ask for, and is out of scope here. This module
+ * covers exactly the shapes the built-in tools' input schemas use (string,
+ * optional, enum, number, boolean, array, object) via zod 3's `_def`
+ * introspection — the same technique the `zod-to-json-schema` package uses,
+ * inlined rather than added as a dependency because the surface needed is
+ * this small.
+ *
+ * 🛑 This is a HINT for the model, not a validator. The real gate stays
+ * `tool.inputSchema.safeParse()` in `turn.ts` — an unmodelled shape here
+ * degrades to an unconstrained JSON Schema node rather than throwing,
+ * because a wrong hint only costs the model a clarifying round, while a
+ * throw here would take the whole turn down for a tool nobody has used yet.
+ *
+ * Extend this, not the tool definitions, if a future tool's input schema
+ * needs a shape not listed above.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:none
+ */
+export declare function zodInputToJsonSchema(schema: z.ZodTypeAny): JsonObject;

package/dist/_internal/server/features/assistant/tools/json-schema.js

@@ -0,0 +1,79 @@
+/**
+ * A minimal, self-contained Zod -> JSON Schema converter for assistant tool
+ * input schemas.
+ *
+ * ## 🛑 Not `zod.toJSONSchema()` — appkit pins zod `^3.24`, which has no such export
+ *
+ * This engine was originally built against zod 4's native `toJSONSchema()`
+ * (the consumer app depends on zod `^4.3.6`), but appkit is a separate
+ * package pinned to zod `^3.24` across 148 files — bumping that major
+ * version to accommodate one relocated feature is a cross-cutting dependency
+ * change this move did not ask for, and is out of scope here. This module
+ * covers exactly the shapes the built-in tools' input schemas use (string,
+ * optional, enum, number, boolean, array, object) via zod 3's `_def`
+ * introspection — the same technique the `zod-to-json-schema` package uses,
+ * inlined rather than added as a dependency because the surface needed is
+ * this small.
+ *
+ * 🛑 This is a HINT for the model, not a validator. The real gate stays
+ * `tool.inputSchema.safeParse()` in `turn.ts` — an unmodelled shape here
+ * degrades to an unconstrained JSON Schema node rather than throwing,
+ * because a wrong hint only costs the model a clarifying round, while a
+ * throw here would take the whole turn down for a tool nobody has used yet.
+ *
+ * Extend this, not the tool definitions, if a future tool's input schema
+ * needs a shape not listed above.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:none
+ */
+export function zodInputToJsonSchema(schema) {
+    return convert(schema);
+}
+function typeNameOf(schema) {
+    return schema._def.typeName;
+}
+function isOptional(schema) {
+    const name = typeNameOf(schema);
+    return name === "ZodOptional" || name === "ZodDefault" || name === "ZodNullable";
+}
+function convert(schema) {
+    const typeName = typeNameOf(schema);
+    const def = schema._def;
+    switch (typeName) {
+        case "ZodObject": {
+            const shape = schema.shape;
+            const properties = {};
+            const required = [];
+            for (const [key, value] of Object.entries(shape)) {
+                properties[key] = convert(value);
+                if (!isOptional(value))
+                    required.push(key);
+            }
+            return {
+                type: "object",
+                properties,
+                ...(required.length ? { required } : {}),
+                additionalProperties: false,
+            };
+        }
+        case "ZodOptional":
+        case "ZodNullable":
+        case "ZodDefault":
+            return convert(def.innerType);
+        case "ZodString":
+            return { type: "string" };
+        case "ZodNumber":
+            return { type: "number" };
+        case "ZodBoolean":
+            return { type: "boolean" };
+        case "ZodEnum":
+            return { type: "string", enum: def.values };
+        case "ZodArray":
+            return { type: "array", items: convert(def.type) };
+        default:
+            return {};
+    }
+}

package/dist/_internal/server/features/assistant/tools/manifest.d.ts

@@ -0,0 +1,22 @@
+import type { ToolSchema } from "../../../../../contracts/ai";
+import type { AnyAssistantToolDef } from "./define";
+/**
+ * Derive the model-facing `ToolSchema[]` from a set of tool definitions.
+ *
+ * This is the ONLY place a tool's JSON Schema is produced. The schema the
+ * model is told about *is* the one `turn.ts` validates the model's tool-call
+ * arguments against, because both read `tool.inputSchema` — there is no
+ * second hand-written copy to disagree with it (Root Cause #42/#61: two
+ * independent descriptions of one contract drift, and the drift is invisible
+ * until a model emits arguments the real validator rejects).
+ *
+ * 🛑 Derived via `zodInputToJsonSchema` (`./json-schema.ts`), NOT zod 4's
+ * native `toJSONSchema()` — appkit pins zod `^3.24`, which has no such
+ * export. See that module's header for why.
+ *
+ * @tag domain:assistant
+ * @tag layer:server
+ * @tag access:server
+ * @tag sideEffects:none
+ */
+export declare function buildToolManifest(tools: readonly AnyAssistantToolDef[]): readonly ToolSchema[];