veryfront 0.1.501 → 0.1.503

package/src/src/skill/tools.ts

@@ -9,7 +9,7 @@
  * @module
  */
 
-import { z } from "zod";
+import { defineSchema } from "../schemas/index.js";
 import { tool } from "../tool/factory.js";
 import type { Tool } from "../tool/index.js";
 import { readTextFile } from "../platform/compat/fs.js";
@@ -30,6 +30,39 @@ import {
 /** Maximum allowed script execution timeout in milliseconds (5 minutes) */
 const MAX_SCRIPT_TIMEOUT_MS = 300_000;
 
+const getLoadSkillInputSchema = defineSchema((v) =>
+  v.object({
+    skillId: v.string().describe("The ID of the skill to load"),
+  })
+);
+
+const getLoadSkillReferenceInputSchema = defineSchema((v) =>
+  v.object({
+    skillId: v.string().describe("The ID of the skill"),
+    reference: v.string().describe(
+      "Relative path to the reference file (e.g. 'references/CLAUSES.md')",
+    ),
+  })
+);
+
+const getExecuteSkillScriptInputSchema = defineSchema((v) =>
+  v.object({
+    skillId: v.string().describe("The ID of the skill"),
+    script: v.string().describe("Relative path to the script (e.g. 'scripts/setup.sh')"),
+    args: v.array(v.string()).optional().describe("Arguments to pass to the script"),
+    env: v.record(v.string(), v.string()).optional().describe(
+      "Environment variables for the script",
+    ),
+    timeoutMs: v
+      .number()
+      .int()
+      .positive()
+      .max(MAX_SCRIPT_TIMEOUT_MS)
+      .optional()
+      .describe(`Optional execution timeout in milliseconds (max ${MAX_SCRIPT_TIMEOUT_MS})`),
+  })
+);
+
 /**
  * Read a file from a skill directory.
  * Uses skill.fsAdapter if available (VFS/cloud), otherwise falls back to compat readTextFile.
@@ -63,9 +96,7 @@ export function createLoadSkillTool(): Tool {
     id: "load-skill",
     description: "Load a skill's full instructions. Returns the skill's markdown instructions, " +
       "allowed tools policy, and lists of available reference files and scripts.",
-    inputSchema: z.object({
-      skillId: z.string().describe("The ID of the skill to load"),
-    }),
+    inputSchema: getLoadSkillInputSchema(),
     execute: async (input): Promise<SkillContent> => {
       const skill = skillRegistry.get(input.skillId);
       if (!skill) {
@@ -120,12 +151,7 @@ export function createLoadSkillReferenceTool(): Tool {
     id: "load-skill-reference",
     description: "Read a reference file from a skill. Only files in the skill's " +
       "references/ and assets/ directories are accessible.",
-    inputSchema: z.object({
-      skillId: z.string().describe("The ID of the skill"),
-      reference: z.string().describe(
-        "Relative path to the reference file (e.g. 'references/CLAUSES.md')",
-      ),
-    }),
+    inputSchema: getLoadSkillReferenceInputSchema(),
     execute: async (input): Promise<{ content: string; path: string }> => {
       const skill = skillRegistry.get(input.skillId);
       if (!skill) {
@@ -160,21 +186,7 @@ export function createExecuteSkillScriptTool(): Tool {
     id: "execute-skill-script",
     description:
       "Execute a script from a skill's scripts/ directory. Returns stdout, stderr, and exit code.",
-    inputSchema: z.object({
-      skillId: z.string().describe("The ID of the skill"),
-      script: z.string().describe("Relative path to the script (e.g. 'scripts/setup.sh')"),
-      args: z.array(z.string()).optional().describe("Arguments to pass to the script"),
-      env: z.record(z.string(), z.string()).optional().describe(
-        "Environment variables for the script",
-      ),
-      timeoutMs: z
-        .number()
-        .int()
-        .positive()
-        .max(MAX_SCRIPT_TIMEOUT_MS)
-        .optional()
-        .describe(`Optional execution timeout in milliseconds (max ${MAX_SCRIPT_TIMEOUT_MS})`),
-    }),
+    inputSchema: getExecuteSkillScriptInputSchema(),
     execute: async (input) => {
       const skill = skillRegistry.get(input.skillId);
       if (!skill) {

package/src/src/tool/factory.ts

@@ -1,6 +1,5 @@
 import type { Tool, ToolConfig, ToolExecutionContext } from "./types.js";
-import type { JsonSchema } from "./schema/json-schema.js";
-import type { z } from "zod";
+import type { JsonSchema, Schema } from "../extensions/schema/index.js";
 import { zodToJsonSchema } from "./schema/zod-json-schema.js";
 import { agentLogger } from "../utils/logger/logger.js";
 import { createError, getErrorMessage, toError } from "../errors/veryfront-error.js";
@@ -14,10 +13,26 @@ interface ZodLikeSchema {
   parse?: (input: unknown) => void;
 }
 
+interface ContractSchemaShape {
+  __zod?: unknown;
+  _output?: unknown;
+  parse: (input: unknown) => unknown;
+  safeParse?: (input: unknown) => unknown;
+}
+
 interface SchemaWithParse {
   parse: (input: unknown) => unknown;
 }
 
+function isContractSchema(value: unknown): value is ContractSchemaShape {
+  if (value === null || typeof value !== "object") return false;
+  if ("__zod" in value) return true;
+  return (
+    "_output" in value &&
+    typeof (value as { parse?: unknown }).parse === "function"
+  );
+}
+
 function hasValidZodTypeName(schema: unknown): schema is ZodLikeSchema {
   if (schema === null || typeof schema !== "object") return false;
   if (!("_def" in schema)) return false;
@@ -88,9 +103,12 @@ function convertSchemaToJson(
   logPrefix: string,
   permissive = false,
 ): JsonSchema {
-  if (hasValidZodTypeName(schema)) {
+  // Modern path: contract Schema<T> (defineSchema-produced) — route through
+  // the SchemaValidator contract via zodToJsonSchema (which detects both
+  // wrapped and raw zod shapes).
+  if (isContractSchema(schema) || hasValidZodTypeName(schema)) {
     const result = tryConvert(
-      () => zodToJsonSchema(schema as z.ZodTypeAny),
+      () => zodToJsonSchema(schema),
       toolId,
       logPrefix,
       permissive,
@@ -196,7 +214,7 @@ export function dynamicTool(config: DynamicToolConfig): Tool<unknown, unknown> {
     id,
     type: "dynamic" as const,
     description: config.description,
-    inputSchema: config.inputSchema as z.ZodSchema<unknown>,
+    inputSchema: config.inputSchema as Schema<unknown>,
     inputSchemaJson,
     execute: async (input: unknown, context?: ToolExecutionContext) => {
       if (hasSchemaParse(config.inputSchema)) {

package/src/src/tool/host-tools.ts

@@ -1,7 +1,6 @@
 import * as dntShim from "../../_dnt.shims.js";
-import { z } from "zod";
 import { dynamicTool, tool } from "./factory.js";
-import type { JsonSchema } from "./schema/json-schema.js";
+import type { JsonSchema, Schema } from "../extensions/schema/index.js";
 import type { Tool, ToolConfig, ToolExecutionContext, ToolSet } from "./types.js";
 
 type HostToolExecute = {
@@ -25,7 +24,7 @@ export type HostToolSet = Record<string, HostToolDefinition>;
 
 type RunnableHostToolDefinition = HostToolDefinition & {
   description: string;
-  inputSchema: z.ZodSchema<unknown>;
+  inputSchema: Schema<unknown>;
   execute: HostToolExecute;
 };
 
@@ -37,8 +36,19 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function isZodSchema(value: unknown): value is z.ZodSchema<unknown> {
-  if (!isRecord(value) || typeof value.parse !== "function") return false;
+/**
+ * Detect a contract `Schema<T>` (defineSchema-produced wrapper) or a raw
+ * zod schema. Both are accepted during the migration window so host tools
+ * can feed either into the framework without bespoke conversion.
+ */
+function isSchemaLike(value: unknown): value is Schema<unknown> {
+  if (!isRecord(value)) return false;
+  if (typeof value.parse !== "function") return false;
+  // Contract Schema<T> brand from the ext-zod adapter.
+  if ("__zod" in value) return true;
+  // defineSchema wrapper without a brand yet — match on the contract surface.
+  if ("_output" in value && typeof value.safeParse === "function") return true;
+  // Raw zod schema (legacy host paths still hand us bare zod instances).
   if (!isRecord(value._def)) return false;
   return typeof value._def.typeName === "string" || typeof value._def.type === "string";
 }
@@ -47,7 +57,7 @@ function isHostToolDefinition(value: unknown): value is RunnableHostToolDefiniti
   return (
     isRecord(value) &&
     typeof value.description === "string" &&
-    isZodSchema(value.inputSchema) &&
+    isSchemaLike(value.inputSchema) &&
     typeof value.execute === "function"
   );
 }

package/src/src/tool/index.ts

@@ -1,17 +1,19 @@
 /**
- * Define tools with Zod schemas for agents and MCP.
+ * Define tools with `defineSchema`-built input schemas for agents and MCP.
  *
  * @module tool
  *
  * @example Basic tool
  * ```ts
  * import { tool } from "veryfront/tool";
- * import { z } from "zod";
+ * import { defineSchema } from "veryfront/schemas";
+ *
+ * const getWeatherInputSchema = defineSchema((v) => v.object({ city: v.string() }));
  *
  * const weather = tool({
  *   id: "weather",
  *   description: "Get current weather for a city",
- *   inputSchema: z.object({ city: z.string() }),
+ *   inputSchema: getWeatherInputSchema(),
  *   execute: async ({ city }) => {
  *     const res = await fetch(`https://api.weather.com/${city}`);
  *     return res.json();
@@ -23,12 +25,14 @@
  * ```ts
  * import { tool } from "veryfront/tool";
  * import { agent } from "veryfront/agent";
- * import { z } from "zod";
+ * import { defineSchema } from "veryfront/schemas";
+ *
+ * const getWeatherInputSchema = defineSchema((v) => v.object({ city: v.string() }));
  *
  * const weather = tool({
  *   id: "weather",
  *   description: "Get current weather for a city",
- *   inputSchema: z.object({ city: z.string() }),
+ *   inputSchema: getWeatherInputSchema(),
  *   execute: async ({ city }) => {
  *     const res = await fetch(`https://api.weather.com/${city}`);
  *     return res.json();

package/src/src/tool/remote-source-tools.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { defineSchema } from "../schemas/index.js";
 import { dynamicTool } from "./factory.js";
 import type { RemoteToolSource, Tool, ToolDefinition, ToolExecutionContext } from "./types.js";
 
@@ -7,6 +7,14 @@ export interface RemoteToolMaterializationOptions {
   toolNameAliases?: Record<string, string>;
 }
 
+/**
+ * Permissive input schema used for remote tools whose JSON Schema is
+ * sourced from the remote and we only need a no-op contract `Schema<T>` to
+ * satisfy the runtime input-validation pass. Equivalent to
+ * `z.object({}).passthrough()`.
+ */
+const getRemoteToolPassthroughSchema = defineSchema((v) => v.object({}).passthrough());
+
 function toToolInputRecord(input: unknown): Record<string, unknown> {
   if (typeof input !== "object" || input === null || Array.isArray(input)) {
     return {};
@@ -29,7 +37,7 @@ export function createToolsFromRemoteDefinitions(
         dynamicTool({
           id: toolName,
           description: definition.description,
-          inputSchema: z.object({}).passthrough(),
+          inputSchema: getRemoteToolPassthroughSchema(),
           inputSchemaJson: definition.parameters,
           mcp: {
             title: definition.title,

package/src/src/tool/schema/json-schema.ts

@@ -1,15 +1,9 @@
-export type JsonSchema = {
-  type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
-  description?: string;
-  enum?: unknown[];
-  const?: unknown;
-  default?: unknown;
-  properties?: Record<string, JsonSchema>;
-  required?: string[];
-  items?: JsonSchema;
-  additionalProperties?: boolean | JsonSchema;
-  anyOf?: JsonSchema[];
-  prefixItems?: JsonSchema[];
-  minItems?: number;
-  maxItems?: number;
-};
+/**
+ * Back-compat re-export. The canonical `JsonSchema` type now lives in
+ * `src/extensions/schema/json-schema.ts` so the `SchemaValidator`
+ * contract can reference it without an upward import.
+ *
+ * @module tool/schema/json-schema
+ */
+
+export type { JsonSchema } from "../../extensions/schema/json-schema.js";

package/src/src/tool/schema/zod-json-schema.ts

@@ -1,221 +1,87 @@
-import type { z } from "zod";
-import type { JsonSchema } from "./json-schema.js";
-import { INVALID_ARGUMENT } from "../../errors/index.js";
-
-/** Zod internal _def shape — covers fields from both v3 and v4. */
-interface ZodDef {
-  typeName?: string; // v3
-  type?: string; // v4
-  value?: unknown; // v3 literal
-  values?: unknown; // v3 enum / v4 literal
-  entries?: Record<string, unknown>; // v4 enum
-  shape?: (() => Record<string, z.ZodTypeAny>) | Record<string, z.ZodTypeAny>;
-  element?: z.ZodTypeAny; // v4 array/record
-  items?: z.ZodTypeAny[]; // tuple
-  options?: z.ZodTypeAny[] | Map<string, z.ZodTypeAny>; // union
-  valueType?: z.ZodTypeAny; // record
-  innerType?: z.ZodTypeAny; // optional/nullable/default (v3)
-  schema?: z.ZodTypeAny; // effects/optional/nullable (v3/v4)
-  in?: z.ZodTypeAny; // pipe input (v4)
-  getter?: () => z.ZodTypeAny; // lazy
-  defaultValue?: (() => unknown) | unknown;
+/**
+ * Schema → JSON Schema conversion shim.
+ *
+ * Historically this module was the in-tree zod-to-JSON-Schema converter.
+ * After Phase B2 the conversion lives behind the `SchemaValidator`
+ * contract (`toJsonSchema` / `isOptional`) and the zod-aware logic moved
+ * to `extensions/ext-zod/src/json-schema.ts`. This file is kept as a
+ * back-compat surface so existing callers (`tool/registry.ts`,
+ * `tool/factory.ts`, `workflow/registry.ts`, `routing/api/openapi/...`,
+ * `mcp/server.ts`, `cli/mcp/server.ts`) continue to compile.
+ *
+ * Inputs may be either an opaque `Schema<T>` produced by `defineSchema`
+ * (the modern path) or a raw zod schema (legacy path during the migration
+ * window). Both shapes are routed through the `SchemaValidator` contract
+ * so no zod-specific logic remains in this file.
+ *
+ * @module tool/schema/zod-json-schema
+ */
+
+import type { JsonSchema, Schema } from "../../extensions/schema/index.js";
+import {
+  isOptionalSchema as schemaIsOptional,
+  schemaToJsonSchema,
+} from "../../schemas/json-schema.js";
+
+/** Detect contract `Schema<T>` (carries a `__zod` brand from the ext-zod adapter). */
+function isContractSchema(value: unknown): value is Schema<unknown> {
+  if (value === null || typeof value !== "object") return false;
+  if ("__zod" in value) return true;
+  // Fallback: defineSchema-produced wrappers expose `_output`, `parse`, and
+  // `safeParse`. Some test doubles may construct these directly.
+  return (
+    "_output" in value &&
+    typeof (value as { parse?: unknown }).parse === "function" &&
+    typeof (value as { safeParse?: unknown }).safeParse === "function"
+  );
 }
 
-const LITERAL_TYPE_MAP: Record<string, "string" | "number" | "boolean"> = {
-  string: "string",
-  number: "number",
-  boolean: "boolean",
-};
-
-function getLiteralType(value: unknown): "string" | "number" | "boolean" | undefined {
-  return LITERAL_TYPE_MAP[typeof value];
+/** Detect a raw zod schema: object with `_def` carrying `typeName` (v3) or `type` (v4). */
+function isRawZodSchema(value: unknown): value is { _def: { typeName?: string; type?: string } } {
+  if (value === null || typeof value !== "object") return false;
+  if (!("_def" in value)) return false;
+  const def = (value as { _def: unknown })._def as { typeName?: unknown; type?: unknown } | null;
+  if (!def || typeof def !== "object") return false;
+  return typeof def.typeName === "string" || typeof def.type === "string";
 }
 
-function getDef(schema: z.ZodTypeAny): ZodDef {
-  return schema._def as ZodDef;
+/**
+ * Adapter that wraps a raw zod schema in the contract's `Schema<unknown>`
+ * shape so the contract's `toJsonSchema` / `isOptional` can unwrap it via
+ * the `__zod` brand.
+ */
+function wrapRawZod(value: unknown): Schema<unknown> {
+  return { __zod: value } as unknown as Schema<unknown>;
 }
 
-/** Get the internal type tag from a zod schema (_def.typeName in v3, _def.type in v4). */
-function getTypeTag(schema: z.ZodTypeAny): string | undefined {
-  const def = getDef(schema);
-  return def.typeName ?? def.type;
-}
-
-export function zodToJsonSchema(schema: z.ZodTypeAny): JsonSchema {
-  // Guard against invalid schemas (can happen with different zod instances in npm bundle)
-  if (!schema || typeof schema !== "object" || !("_def" in schema)) {
-    throw INVALID_ARGUMENT.create({ detail: "Invalid Zod schema: missing _def property" });
+/**
+ * Convert a `Schema<T>` (or, transitionally, a raw zod schema) into a
+ * JSON Schema document.
+ *
+ * Throws if the input is neither a contract schema nor a raw zod schema —
+ * matches the pre-B2 behavior of the original `zodToJsonSchema` guard.
+ */
+export function zodToJsonSchema(schema: unknown): JsonSchema {
+  if (isContractSchema(schema)) {
+    return schemaToJsonSchema(schema);
   }
-
-  const { schema: unwrapped, nullable } = unwrapSchema(schema);
-  const json = convert(unwrapped);
-
-  return nullable ? { anyOf: [json, { type: "null" }] } : json;
-}
-
-export function isOptionalSchema(schema: z.ZodTypeAny): boolean {
-  return unwrapSchema(schema).optional;
-}
-
-function convert(schema: z.ZodTypeAny): JsonSchema {
-  const tag = getTypeTag(schema);
-  const def = getDef(schema);
-
-  switch (tag) {
-    case "ZodString":
-    case "string":
-      return { type: "string" };
-
-    case "ZodNumber":
-    case "number":
-      return { type: "number" };
-
-    case "ZodBoolean":
-    case "boolean":
-      return { type: "boolean" };
-
-    case "ZodBigInt":
-    case "bigint":
-      return { type: "integer" };
-
-    case "ZodLiteral":
-    case "literal": {
-      // v3: _def.value, v4: _def.values (array of accepted values)
-      const literal = def.value ?? (Array.isArray(def.values) ? def.values[0] : def.values);
-      return { const: literal, type: getLiteralType(literal) };
-    }
-
-    case "ZodEnum":
-    case "ZodNativeEnum":
-    case "enum": {
-      // v3: _def.values (array), v4: _def.entries (object {key: value})
-      const values = def.values ?? (def.entries ? Object.values(def.entries) : []);
-      if (Array.isArray(values)) {
-        return { type: "string", enum: values };
-      }
-      // Native enum: filter out reverse-mapped numeric keys
-      return {
-        enum: Object.values(values).filter((value) => typeof value !== "number"),
-      };
-    }
-
-    case "ZodObject":
-    case "object": {
-      const shape = typeof def.shape === "function" ? def.shape() : def.shape;
-      const properties: Record<string, JsonSchema> = {};
-      const required: string[] = [];
-
-      for (const [key, value] of Object.entries(shape ?? {})) {
-        const zodSchema = value as z.ZodTypeAny;
-        properties[key] = zodToJsonSchema(zodSchema);
-        if (!isOptionalSchema(zodSchema)) required.push(key);
-      }
-
-      const json: JsonSchema = { type: "object", properties };
-      if (required.length) json.required = required;
-
-      return json;
-    }
-
-    case "ZodArray":
-    case "array": {
-      // v3: _def.type (item schema), v4: _def.element (item schema)
-      const itemType = def.element ?? (def.type as unknown as z.ZodTypeAny | undefined);
-      if (!itemType || typeof itemType === "string") return { type: "array" };
-      return { type: "array", items: zodToJsonSchema(itemType) };
-    }
-
-    case "ZodTuple":
-    case "tuple": {
-      const items = def.items ?? [];
-      return {
-        type: "array",
-        prefixItems: items.map((item: z.ZodTypeAny) => zodToJsonSchema(item)),
-        minItems: items.length,
-        maxItems: items.length,
-      };
-    }
-
-    case "ZodUnion":
-    case "ZodDiscriminatedUnion":
-    case "union": {
-      const options = def.options ?? [];
-      const optionArray = options instanceof Map ? Array.from(options.values()) : options;
-      return { anyOf: optionArray.map((option: z.ZodTypeAny) => zodToJsonSchema(option)) };
-    }
-
-    case "ZodRecord":
-    case "record": {
-      const valueSchema = def.valueType ?? def.element;
-      if (!valueSchema) return { type: "object" };
-      return { type: "object", additionalProperties: zodToJsonSchema(valueSchema) };
-    }
-
-    case "ZodDefault":
-    case "default": {
-      const innerType = def.innerType ?? def.schema;
-      if (!innerType) return { type: "object" };
-      const inner = zodToJsonSchema(innerType);
-      const defaultValue = typeof def.defaultValue === "function"
-        ? def.defaultValue()
-        : def.defaultValue;
-
-      if (typeof inner === "object" && !("anyOf" in inner) && defaultValue !== undefined) {
-        inner.default = defaultValue;
-      }
-
-      return inner;
-    }
-
-    case "ZodLazy":
-    case "lazy":
-      return def.getter ? convert(def.getter()) : { type: "object" };
-
-    case "ZodEffects":
-    case "pipe": {
-      // v3: ZodEffects wraps schema in _def.schema
-      // v4: pipe wraps in _def.in (input schema)
-      const innerSchema = def.schema ?? def.in;
-      return innerSchema ? convert(innerSchema) : { type: "object" };
-    }
-
-    default:
-      return { type: "object" };
+  if (isRawZodSchema(schema)) {
+    return schemaToJsonSchema(wrapRawZod(schema));
   }
+  throw new Error("Invalid Zod schema: missing _def property");
 }
 
-function unwrapSchema(
-  schema: z.ZodTypeAny,
-): { schema: z.ZodTypeAny; nullable: boolean; optional: boolean } {
-  let current: z.ZodTypeAny = schema;
-  let nullable = false;
-  let optional = false;
-
-  while (true) {
-    const tag = getTypeTag(current);
-    const def = getDef(current);
-
-    switch (tag) {
-      case "ZodNullable":
-      case "nullable":
-        nullable = true;
-        current = (def.innerType ?? def.schema)!;
-        break;
-
-      case "ZodOptional":
-      case "optional":
-        optional = true;
-        current = (def.innerType ?? def.schema)!;
-        break;
-
-      case "ZodEffects":
-      case "pipe":
-        current = def.schema ?? def.in ?? current;
-        if (current === schema) return { schema: current, nullable, optional };
-        break;
-
-      default:
-        return { schema: current, nullable, optional };
-    }
+/**
+ * Returns `true` when the schema permits `undefined`. Accepts both
+ * contract `Schema<T>` and raw zod schemas for the same compatibility
+ * reasons as `zodToJsonSchema` above.
+ */
+export function isOptionalSchema(schema: unknown): boolean {
+  if (isContractSchema(schema)) {
+    return schemaIsOptional(schema);
+  }
+  if (isRawZodSchema(schema)) {
+    return schemaIsOptional(wrapRawZod(schema));
   }
+  return false;
 }