glirastes 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-25
+
+### Changed
+
+- **Upgraded Zod from v3 to v4** (`zod@^4`). The public schema-authoring API
+  is unchanged for consumers, but Zod 4 is now installed transitively — apps
+  that import `zod` directly alongside glirastes will resolve to Zod 4.
+  - Rewrote the internal Zod-introspection code that depended on Zod 3's
+    private representation (`_def.typeName`, `def.shape()`, `_def.checks`).
+    Most critically, `zodToCompactDescription()` (the `Returns: …` suffix
+    generator for AI tool descriptions) silently degraded to `"unknown"`
+    under Zod 4 — it now reads Zod 4's `_zod.def` correctly.
+  - Centralized all Zod-internals access for the test-suite generators
+    (`runEdgeCaseTest`, `runSchemaConsistencyTest`) into a single
+    `zod-introspect` module with full unit coverage, so a future Zod upgrade
+    fails loudly instead of generating empty test suites.
+  - `z.record(z.unknown())` updated to the Zod 4 two-argument form
+    `z.record(z.string(), z.unknown())`.
+
+### Added
+
+- Regression tests pinning `zodToCompactDescription` output and the Zod
+  introspection helpers, closing the silent-failure gap the upgrade exposed.
+
+## [0.3.2] - 2026-04-29
+
+### Changed
+
+- Documentation pass that makes the **CLI codegen step explicit as a
+  required part of the Next.js setup** for any non-trivial app. The
+  earlier framing implied codegen was only "for scaling up" — in
+  practice the manual `endpointToolsToRegistry([…])` import list breaks
+  down past a handful of tools, and codegen is the canonical wiring.
+  - README quickstart Step 4 now points readers at the codegen workflow
+    immediately after the demo manual-import example.
+  - The "Scaling up" section is renamed to **"Scaling up — required
+    codegen workflow for Next.js"** and explicitly states NestJS users
+    skip it (runtime DI scan handles aggregation).
+  - The `integrating-glirastes-nextjs` and `maintaining-glirastes-tools`
+    skills mirror the same framing so coding agents pick the codegen
+    path by default for non-trivial apps.
+- Forward-looking note in README and skills: a `buildToolRegistry`
+  helper based on `import.meta.glob` / `require.context` is planned
+  for **0.4.0** and will let Next.js consumers skip the codegen step.
+
+No code changes — patch-level docs release.
+
 ## [0.3.1] - 2026-04-28
 
 ### Added
@@ -140,6 +187,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   these libraries on install. `react-markdown` is loaded via `React.lazy`
   with a plain-text fallback when the peer dep is not installed.
 
-[Unreleased]: https://github.com/chainmatics/glirastes/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/chainmatics/glirastes/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/chainmatics/glirastes/compare/v0.3.2...v0.4.0
 [0.2.1]: https://github.com/chainmatics/glirastes/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/chainmatics/glirastes/releases/tag/v0.2.0

package/README.md

@@ -14,7 +14,7 @@
   <a href="#core-concepts"><strong>Concepts</strong></a> ·
   <a href="#examples"><strong>Examples</strong></a> ·
   <a href="#advanced"><strong>Advanced</strong></a> ·
-  <a href="#scaling-up--codegen-workflow"><strong>Scaling up</strong></a> ·
+  <a href="#scaling-up--required-codegen-workflow-for-nextjs"><strong>Scaling up</strong></a> ·
   <a href="#cli"><strong>CLI</strong></a> ·
   <a href="#agent-skills"><strong>Skills</strong></a>
 </p>
@@ -246,6 +246,10 @@ const registry = endpointToolsToRegistry(scan.tools);
 
 Done. AI chat is live, streaming, and your `list_tasks` tool is callable. Add more tools the same way — pick the style that matches your stack. See [NestJS with decorators](#nestjs-with-decorators) below for DTOs, `@AiParam`, and multi-controller scanning.
 
+> **One more step for Next.js once you have more than a handful of tools.** The manual `endpointToolsToRegistry([listTasks, …])` import list above stops scaling around 5–10 tools. Today's required pattern: write each tool in a co-located `*.ai-tool.ts` file and run the CLI codegen as a `predev` / `prebuild` hook to aggregate them into a generated registry your chat route imports. See [Scaling up — required codegen workflow for Next.js](#scaling-up--required-codegen-workflow-for-nextjs) below for the full setup. **NestJS users skip this entirely** — the runtime decorator scan handles aggregation automatically.
+>
+> *Coming in 0.4.0:* a `buildToolRegistry` helper backed by `import.meta.glob` / `require.context` that drops the codegen step for Next.js too. Track at [chainmatics/glirastes#issues](https://github.com/chainmatics/glirastes/issues).
+
 ### Setup notes
 
 #### tsconfig — modern is best, legacy still works
@@ -772,9 +776,13 @@ The voice button streams audio to your backend, which proxies it to a speech-to-
 
 <br/>
 
-## Scaling up — codegen workflow
+## Scaling up — required codegen workflow for Next.js
 
-Hand-importing 50 tool definitions into your chat route doesn't scale. The CLI generates a registry from co-located `*.ai-tool.ts` files so you can stay co-located while still wiring everything centrally.
+Hand-importing every tool definition into your chat route doesn't scale past a handful. **In Glirastes 0.3.x the canonical pattern for Next.js consumers is to run the CLI codegen as a build hook** — it generates a registry from co-located `*.ai-tool.ts` files. The chat route imports the generated registry instead of maintaining a manual import list.
+
+> NestJS users **skip this section entirely.** `AiChatModule.forRoot()` discovers `@AiTool`-decorated controllers at runtime via the NestJS `DiscoveryService` — no codegen step is ever needed.
+>
+> **Coming in 0.4.0:** a `buildToolRegistry` helper based on `import.meta.glob` / `require.context` will let Next.js consumers skip the codegen step too. Until then the steps below are required for any non-trivial Next.js app.
 
 ### 1. Bootstrap a tool from an existing route
 

package/dist/cjs/server/adapters/nestjs/module/ai-tools.service.d.ts

@@ -14,14 +14,14 @@ export declare class AiToolsService {
     buildAiTools(context: ToolContext, options?: ToolToAiToolOptions): Promise<Record<string, {
         _toolId: string;
         description: string;
-        parameters: import("zod").ZodType<any, import("zod").ZodTypeDef, any>;
+        parameters: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
         needsApproval: ((input: unknown) => Promise<boolean>) | undefined;
         execute: (input: unknown) => Promise<unknown>;
     }>>;
     buildAiToolsForIntent(intent: string, context: ToolContext, options?: ToolToAiToolOptions): Promise<Record<string, {
         _toolId: string;
         description: string;
-        parameters: import("zod").ZodType<any, import("zod").ZodTypeDef, any>;
+        parameters: import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
         needsApproval: ((input: unknown) => Promise<boolean>) | undefined;
         execute: (input: unknown) => Promise<unknown>;
     }>>;

package/dist/cjs/server/core/index.d.ts

@@ -117,7 +117,7 @@ export interface ToolToAiToolOptions {
 export declare function toolToAiTool(tool: Tool, context: ToolContext, toolName?: string, options?: ToolToAiToolOptions): {
     _toolId: string;
     description: string;
-    parameters: z.ZodType<any, z.ZodTypeDef, any>;
+    parameters: z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
     needsApproval: ((input: unknown) => Promise<boolean>) | undefined;
     execute: (input: unknown) => Promise<unknown>;
 };

package/dist/cjs/server/core/zod-compact.d.ts

@@ -9,7 +9,7 @@ import { z } from 'zod';
  * zodToCompactDescription(z.object({
  *   tasks: z.array(z.object({ id: z.string(), title: z.string() })),
  *   total: z.number(),
- * }))
+ * }), 5)
  * // → '{ tasks: Array<{ id: string, title: string }>, total: number }'
  *
  * @param schema - Any Zod schema

package/dist/cjs/server/core/zod-compact.js

@@ -11,7 +11,7 @@ exports.zodToCompactDescription = zodToCompactDescription;
  * zodToCompactDescription(z.object({
  *   tasks: z.array(z.object({ id: z.string(), title: z.string() })),
  *   total: z.number(),
- * }))
+ * }), 5)
  * // → '{ tasks: Array<{ id: string, title: string }>, total: number }'
  *
  * @param schema - Any Zod schema
@@ -20,45 +20,49 @@ exports.zodToCompactDescription = zodToCompactDescription;
 function zodToCompactDescription(schema, maxDepth = 3) {
     return describeSchema(schema, 0, maxDepth);
 }
+/** Read Zod v4's internal schema definition (`schema._zod.def`). */
+function getDef(schema) {
+    return schema?._zod?.def;
+}
 function describeSchema(schema, depth, maxDepth) {
     if (depth >= maxDepth)
         return '...';
-    const def = schema._def;
-    const typeName = def?.typeName;
-    switch (typeName) {
-        case 'ZodString':
+    const def = getDef(schema);
+    const type = def?.type;
+    switch (type) {
+        case 'string':
             return 'string';
-        case 'ZodNumber':
+        case 'number':
+        case 'bigint':
             return 'number';
-        case 'ZodBoolean':
+        case 'boolean':
             return 'boolean';
-        case 'ZodDate':
+        case 'date':
             return 'string'; // Dates serialize as strings in JSON
-        case 'ZodLiteral':
-            return JSON.stringify(def.value);
-        case 'ZodNull':
+        case 'literal':
+            // Zod v4 literals hold an array of allowed values.
+            return def.values
+                .map((v) => JSON.stringify(v))
+                .join(' | ');
+        case 'null':
             return 'null';
-        case 'ZodUndefined':
-            return 'undefined';
-        case 'ZodAny':
+        case 'undefined':
+        case 'void':
+            return type;
+        case 'any':
             return 'any';
-        case 'ZodUnknown':
+        case 'unknown':
             return 'unknown';
-        case 'ZodVoid':
-            return 'void';
-        case 'ZodEnum':
-            return def.values
-                .map((v) => `"${v}"`)
-                .join(' | ');
-        case 'ZodNativeEnum':
-            return Object.values(def.values)
-                .filter((v) => typeof v === 'string')
-                .map((v) => `"${v}"`)
-                .join(' | ');
-        case 'ZodArray':
-            return `Array<${describeSchema(def.type, depth + 1, maxDepth)}>`;
-        case 'ZodObject': {
-            const shape = def.shape();
+        case 'enum': {
+            // Zod v4 stores enum members in an `entries` record (covers both string
+            // enums and native enums). Emit the string values only.
+            const values = Object.values(def.entries).filter((v) => typeof v === 'string');
+            return values.map((v) => `"${v}"`).join(' | ');
+        }
+        case 'array':
+            return `Array<${describeSchema(def.element, depth + 1, maxDepth)}>`;
+        case 'object': {
+            const shape = def.shape;
             const entries = Object.entries(shape);
             if (entries.length === 0)
                 return '{}';
@@ -71,59 +75,78 @@ function describeSchema(schema, depth, maxDepth) {
             });
             return `{ ${fields.join(', ')} }`;
         }
-        case 'ZodRecord':
+        case 'record':
             return `Record<string, ${describeSchema(def.valueType, depth + 1, maxDepth)}>`;
-        case 'ZodUnion':
-        case 'ZodDiscriminatedUnion': {
+        case 'union': {
+            // Covers both unions and discriminated unions in Zod v4.
             const options = def.options;
             return options
                 .map((o) => describeSchema(o, depth + 1, maxDepth))
                 .join(' | ');
         }
-        case 'ZodTuple': {
+        case 'tuple': {
             const items = def.items;
             return `[${items.map((i) => describeSchema(i, depth + 1, maxDepth)).join(', ')}]`;
         }
-        case 'ZodNullable':
+        case 'nullable':
             return `${describeSchema(def.innerType, depth, maxDepth)} | null`;
-        case 'ZodOptional':
-        case 'ZodDefault':
+        case 'optional':
+        case 'default':
+        case 'prefault':
+        case 'catch':
+        case 'readonly':
+        case 'nonoptional':
             return describeSchema(def.innerType, depth, maxDepth);
-        case 'ZodEffects':
-            return describeSchema(def.schema, depth, maxDepth);
+        case 'pipe':
+            // Transforms / refinements become pipes in Zod v4; describe the input
+            // side, matching the pre-v4 behaviour of describing the base schema.
+            return describeSchema(def.in, depth, maxDepth);
+        case 'lazy':
+            return describeSchema(def.getter(), depth, maxDepth);
         default:
             return 'unknown';
     }
 }
-/** Unwrap ZodOptional / ZodNullable / ZodDefault / ZodEffects to the inner schema. */
+/** Unwrap optional / nullable / default / pipe wrappers to the inner schema. */
 function unwrap(schema) {
-    const def = schema._def;
-    const typeName = def?.typeName;
-    if (typeName === 'ZodOptional' ||
-        typeName === 'ZodNullable' ||
-        typeName === 'ZodDefault') {
+    const def = getDef(schema);
+    const type = def?.type;
+    if (type === 'optional' ||
+        type === 'nullable' ||
+        type === 'default' ||
+        type === 'prefault' ||
+        type === 'catch' ||
+        type === 'readonly' ||
+        type === 'nonoptional') {
         return unwrap(def.innerType);
     }
-    if (typeName === 'ZodEffects') {
-        return unwrap(def.schema);
+    if (type === 'pipe') {
+        return unwrap(def.in);
     }
     return schema;
 }
 function isOptional(schema) {
-    const def = schema._def;
-    const typeName = def?.typeName;
-    if (typeName === 'ZodOptional' || typeName === 'ZodDefault')
+    const def = getDef(schema);
+    const type = def?.type;
+    if (type === 'optional' || type === 'default' || type === 'prefault') {
         return true;
-    if (typeName === 'ZodNullable')
+    }
+    if (type === 'nullable' || type === 'readonly' || type === 'catch') {
         return isOptional(def.innerType);
+    }
     return false;
 }
 function isNullable(schema) {
-    const def = schema._def;
-    const typeName = def?.typeName;
-    if (typeName === 'ZodNullable')
+    const def = getDef(schema);
+    const type = def?.type;
+    if (type === 'nullable')
         return true;
-    if (typeName === 'ZodOptional' || typeName === 'ZodDefault')
+    if (type === 'optional' ||
+        type === 'default' ||
+        type === 'prefault' ||
+        type === 'readonly' ||
+        type === 'catch') {
         return isNullable(def.innerType);
+    }
     return false;
 }

package/dist/cjs/server/testing/edge-cases.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runEdgeCaseTest = runEdgeCaseTest;
 const vitest_1 = require("vitest");
+const zod_introspect_js_1 = require("./zod-introspect.js");
 /**
  * Auto-generates edge case tests from tool Zod schemas + custom cases.
  *
@@ -23,7 +24,7 @@ function runEdgeCaseTest(toolRegistry, options) {
     (0, vitest_1.describe)('AI Tool Edge Cases', () => {
         for (const [toolName, toolDef] of toolsWithSchemas) {
             const schema = toolDef.inputSchema;
-            const shape = getObjectShape(schema);
+            const shape = (0, zod_introspect_js_1.getObjectShape)(schema);
             const hasShapeTests = shape && hasTestableFields(shape);
             const custom = customCases[toolName];
             const hasCustom = custom && custom.length > 0;
@@ -89,59 +90,26 @@ function runEdgeCaseTest(toolRegistry, options) {
  */
 function hasTestableFields(shape) {
     for (const [, fieldSchema] of Object.entries(shape)) {
-        const optional = isOptional(fieldSchema);
-        if (!optional)
-            return true; // Required field → generates "rejects missing" test
-        const inner = unwrap(fieldSchema);
-        const typeName = inner._def.typeName;
-        if (typeName === 'ZodEnum' && inner._def.values)
+        if (!(0, zod_introspect_js_1.isOptional)(fieldSchema))
+            return true; // Required field → "rejects missing" test
+        const inner = (0, zod_introspect_js_1.unwrap)(fieldSchema);
+        const type = (0, zod_introspect_js_1.getBaseType)(inner);
+        if (type === 'enum' && (0, zod_introspect_js_1.getEnumValues)(inner).length > 0)
+            return true;
+        if (type === 'array' && (0, zod_introspect_js_1.getArrayMax)(inner) !== null)
+            return true;
+        if (type === 'string' && (0, zod_introspect_js_1.isUuidString)(inner))
             return true;
-        if (typeName === 'ZodArray') {
-            const checks = inner._def.checks ?? [];
-            if (checks.some((c) => c.kind === 'max'))
-                return true;
-        }
-        if (typeName === 'ZodString') {
-            const checks = inner._def.checks ?? [];
-            if (checks.some((c) => c.kind === 'uuid'))
-                return true;
-        }
     }
     return false;
 }
-function getObjectShape(schema) {
-    const def = schema._def;
-    if (def.typeName === 'ZodObject' && typeof def.shape === 'function') {
-        return def.shape();
-    }
-    // Unwrap ZodEffects (e.g. .refine(), .transform())
-    if (def.typeName === 'ZodEffects' && def.innerType) {
-        return getObjectShape(def.innerType);
-    }
-    return null;
-}
-function isOptional(schema) {
-    const name = schema._def.typeName;
-    return name === 'ZodOptional' || name === 'ZodNullable' || name === 'ZodDefault';
-}
-function unwrap(schema) {
-    const name = schema._def.typeName;
-    if ((name === 'ZodOptional' || name === 'ZodNullable' || name === 'ZodDefault') &&
-        schema._def.innerType) {
-        return unwrap(schema._def.innerType);
-    }
-    if (name === 'ZodEffects' && schema._def.innerType) {
-        return unwrap(schema._def.innerType);
-    }
-    return schema;
-}
 function generateShapeTests(shape, parentSchema) {
     // Build a valid base object with placeholder values
     const baseInput = buildMinimalValidInput(shape);
     for (const [fieldName, fieldSchema] of Object.entries(shape)) {
-        const optional = isOptional(fieldSchema);
-        const inner = unwrap(fieldSchema);
-        const typeName = inner._def.typeName;
+        const optional = (0, zod_introspect_js_1.isOptional)(fieldSchema);
+        const inner = (0, zod_introspect_js_1.unwrap)(fieldSchema);
+        const type = (0, zod_introspect_js_1.getBaseType)(inner);
         // Required field: test missing
         if (!optional) {
             (0, vitest_1.it)(`rejects missing ${fieldName} (required)`, () => {
@@ -152,9 +120,9 @@ function generateShapeTests(shape, parentSchema) {
             });
         }
         // Enum: test each valid value + invalid
-        if (typeName === 'ZodEnum' && inner._def.values) {
-            const values = inner._def.values;
-            for (const val of values) {
+        const enumValues = type === 'enum' ? (0, zod_introspect_js_1.getEnumValues)(inner) : [];
+        if (enumValues.length > 0) {
+            for (const val of enumValues) {
                 (0, vitest_1.it)(`accepts valid ${fieldName} enum: ${val}`, () => {
                     const result = parentSchema.safeParse({ ...baseInput, [fieldName]: val });
                     (0, vitest_1.expect)(result.success).toBe(true);
@@ -166,11 +134,9 @@ function generateShapeTests(shape, parentSchema) {
             });
         }
         // Array with max: test at limit and over limit
-        if (typeName === 'ZodArray') {
-            const checks = inner._def.checks ?? [];
-            const maxCheck = checks.find((c) => c.kind === 'max');
-            if (maxCheck && typeof maxCheck.value === 'number') {
-                const max = maxCheck.value;
+        if (type === 'array') {
+            const max = (0, zod_introspect_js_1.getArrayMax)(inner);
+            if (max !== null) {
                 const arrayFillValue = getArrayElementPlaceholder(inner);
                 (0, vitest_1.it)(`accepts ${fieldName} at max(${max})`, () => {
                     const result = parentSchema.safeParse({
@@ -189,31 +155,24 @@ function generateShapeTests(shape, parentSchema) {
             }
         }
         // String with UUID check
-        if (typeName === 'ZodString') {
-            const checks = inner._def.checks ?? [];
-            const hasUuid = checks.some((c) => c.kind === 'uuid');
-            if (hasUuid) {
-                (0, vitest_1.it)(`rejects invalid ${fieldName} UUID: "not-a-uuid"`, () => {
-                    const result = parentSchema.safeParse({ ...baseInput, [fieldName]: 'not-a-uuid' });
-                    (0, vitest_1.expect)(result.success).toBe(false);
-                });
-            }
+        if (type === 'string' && (0, zod_introspect_js_1.isUuidString)(inner)) {
+            (0, vitest_1.it)(`rejects invalid ${fieldName} UUID: "not-a-uuid"`, () => {
+                const result = parentSchema.safeParse({ ...baseInput, [fieldName]: 'not-a-uuid' });
+                (0, vitest_1.expect)(result.success).toBe(false);
+            });
         }
     }
 }
 function getArrayElementPlaceholder(arraySchema) {
-    const elementSchema = arraySchema._def.type;
+    const elementSchema = (0, zod_introspect_js_1.getArrayElement)(arraySchema);
     if (elementSchema) {
-        const elInner = unwrap(elementSchema);
-        const elType = elInner._def.typeName;
-        if (elType === 'ZodString') {
-            const elChecks = elInner._def.checks ?? [];
-            if (elChecks.some((c) => c.kind === 'uuid')) {
-                return '00000000-0000-0000-0000-000000000000';
-            }
-            return 'test-id';
+        const elType = (0, zod_introspect_js_1.getBaseType)(elementSchema);
+        if (elType === 'string') {
+            return (0, zod_introspect_js_1.isUuidString)(elementSchema)
+                ? '00000000-0000-0000-0000-000000000000'
+                : 'test-id';
         }
-        if (elType === 'ZodNumber')
+        if (elType === 'number')
             return 1;
     }
     return 'test-id';
@@ -221,44 +180,36 @@ function getArrayElementPlaceholder(arraySchema) {
 function buildMinimalValidInput(shape) {
     const input = {};
     for (const [name, schema] of Object.entries(shape)) {
-        if (isOptional(schema))
+        if ((0, zod_introspect_js_1.isOptional)(schema))
             continue;
-        const inner = unwrap(schema);
-        const typeName = inner._def.typeName;
-        if (typeName === 'ZodString') {
-            const checks = inner._def.checks ?? [];
-            if (checks.some((c) => c.kind === 'uuid')) {
-                input[name] = '00000000-0000-0000-0000-000000000000';
-            }
-            else {
-                input[name] = 'test-value';
-            }
+        const inner = (0, zod_introspect_js_1.unwrap)(schema);
+        const type = (0, zod_introspect_js_1.getBaseType)(inner);
+        if (type === 'string') {
+            input[name] = (0, zod_introspect_js_1.isUuidString)(inner)
+                ? '00000000-0000-0000-0000-000000000000'
+                : 'test-value';
         }
-        else if (typeName === 'ZodNumber') {
+        else if (type === 'number') {
             input[name] = 1;
         }
-        else if (typeName === 'ZodBoolean') {
+        else if (type === 'boolean') {
             input[name] = false;
         }
-        else if (typeName === 'ZodEnum' && inner._def.values) {
-            input[name] = inner._def.values[0];
+        else if (type === 'enum') {
+            const values = (0, zod_introspect_js_1.getEnumValues)(inner);
+            input[name] = values.length > 0 ? values[0] : 'test';
         }
-        else if (typeName === 'ZodArray') {
+        else if (type === 'array') {
             // Introspect array element type to generate valid placeholders
-            const elementSchema = inner._def.type;
+            const elementSchema = (0, zod_introspect_js_1.getArrayElement)(inner);
             if (elementSchema) {
-                const elInner = unwrap(elementSchema);
-                const elType = elInner._def.typeName;
-                if (elType === 'ZodString') {
-                    const elChecks = elInner._def.checks ?? [];
-                    if (elChecks.some((c) => c.kind === 'uuid')) {
-                        input[name] = ['00000000-0000-0000-0000-000000000000'];
-                    }
-                    else {
-                        input[name] = ['test-id'];
-                    }
+                const elType = (0, zod_introspect_js_1.getBaseType)(elementSchema);
+                if (elType === 'string') {
+                    input[name] = (0, zod_introspect_js_1.isUuidString)(elementSchema)
+                        ? ['00000000-0000-0000-0000-000000000000']
+                        : ['test-id'];
                 }
-                else if (elType === 'ZodNumber') {
+                else if (elType === 'number') {
                     input[name] = [1];
                 }
                 else {

package/dist/cjs/server/testing/schema-consistency.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runSchemaConsistencyTest = runSchemaConsistencyTest;
 const vitest_1 = require("vitest");
+const zod_introspect_js_1 = require("./zod-introspect.js");
 /**
  * Verifies that tool output field types match the input field types
  * of downstream tools in declared workflow chains.
@@ -21,36 +22,14 @@ function runSchemaConsistencyTest(toolRegistry, options) {
                 // Target tool must have inputSchema with the target field
                 const toSchema = toTool.inputSchema;
                 (0, vitest_1.expect)(toSchema, `Target tool "${chain.to}" has no inputSchema`).toBeDefined();
-                const toShape = getShape(toSchema);
+                const toShape = (0, zod_introspect_js_1.getObjectShape)(toSchema);
                 (0, vitest_1.expect)(toShape, `Target tool "${chain.to}" inputSchema is not an object`).not.toBeNull();
-                const targetField = resolveField(toShape, chain.targetField);
+                const targetField = toShape[chain.targetField] ?? null;
                 (0, vitest_1.expect)(targetField, `Target field "${chain.targetField}" not found in ${chain.to} inputSchema`).not.toBeNull();
                 // Verify type compatibility
-                const targetType = getBaseTypeName(targetField);
-                (0, vitest_1.expect)(['ZodString', 'ZodNumber', 'ZodArray', 'ZodEnum', 'ZodBoolean'].includes(targetType), `Target field "${chain.targetField}" in ${chain.to} has unrecognized type: ${targetType}`).toBe(true);
+                const targetType = (0, zod_introspect_js_1.getBaseType)(targetField);
+                (0, vitest_1.expect)(['string', 'number', 'array', 'enum', 'boolean'].includes(targetType ?? ''), `Target field "${chain.targetField}" in ${chain.to} has unrecognized type: ${targetType}`).toBe(true);
             });
         }
     });
 }
-function getShape(schema) {
-    const def = schema._def;
-    if (def.typeName === 'ZodObject' && typeof def.shape === 'function') {
-        return def.shape();
-    }
-    if ((def.typeName === 'ZodEffects' || def.typeName === 'ZodOptional') && def.innerType) {
-        return getShape(def.innerType);
-    }
-    return null;
-}
-function resolveField(shape, path) {
-    if (shape[path])
-        return shape[path];
-    return null;
-}
-function getBaseTypeName(schema) {
-    const def = schema._def;
-    if (def.typeName === 'ZodOptional' || def.typeName === 'ZodNullable' || def.typeName === 'ZodDefault') {
-        return def.innerType ? getBaseTypeName(def.innerType) : def.typeName;
-    }
-    return def.typeName;
-}

package/dist/cjs/server/testing/zod-introspect.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Zod schema introspection helpers (Zod v4).
+ *
+ * Centralizes all access to Zod's internal `_zod.def` representation so the
+ * test-suite generators (`edge-cases.ts`, `schema-consistency.ts`) don't each
+ * reach into internals independently. If a future Zod version changes its
+ * internal shape, only this file — covered by `zod-introspect.test.ts` — needs
+ * updating, and the unit tests will catch a silent regression (introspection
+ * returning nothing) instead of letting it ship as a green-but-empty suite.
+ */
+/** The normalized Zod v4 type tag (e.g. 'object', 'string', 'array', 'enum'). */
+export declare function getSchemaType(schema: unknown): string | undefined;
+/**
+ * True if the field is optional, nullable, or has a default — i.e. an input
+ * is not strictly required to provide a concrete value. Matches the historical
+ * behaviour of the edge-case generator, which skips the "rejects missing"
+ * boundary test for any of these.
+ */
+export declare function isOptional(schema: unknown): boolean;
+/** Strip optional/nullable/default/pipe wrappers to the base schema. */
+export declare function unwrap<T = unknown>(schema: T): T;
+/** The base Zod type tag after unwrapping (e.g. an optional string → 'string'). */
+export declare function getBaseType(schema: unknown): string | undefined;
+/**
+ * The field map of an object schema, unwrapping optional/default/pipe wrappers.
+ * Returns null for non-object schemas.
+ */
+export declare function getObjectShape(schema: unknown): Record<string, unknown> | null;
+/** The string members of an enum schema (after unwrapping). */
+export declare function getEnumValues(schema: unknown): string[];
+/** The element schema of an array (after unwrapping), or null. */
+export declare function getArrayElement(schema: unknown): unknown | null;
+/** The `.max(n)` length constraint on an array schema, or null. */
+export declare function getArrayMax(schema: unknown): number | null;
+/** True if a string schema carries the given format check (e.g. 'uuid'). */
+export declare function hasStringFormat(schema: unknown, format: string): boolean;
+/** True if a string schema is a UUID. */
+export declare function isUuidString(schema: unknown): boolean;