@agen-ai/validation 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trevor Nichols
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# `@agen-ai/validation`
+
+`@agen-ai/validation` defines a small, validator-neutral issue format for reusable packages. It
+normalizes validation failures without making an ordinary public API expose a particular schema
+library. The optional Zod entrypoint adapts Zod 4 issues to the same stable shape.
+
+## Entrypoints
+
+- `@agen-ai/validation` exports plain issue types plus normalization functions. Its declarations do
+  not expose Zod.
+- `@agen-ai/validation/zod` exports the deliberate Zod 4 adapter and may expose Zod types.
+
+```ts
+import { normalizeValidationIssues } from "@agen-ai/validation";
+
+const issues = normalizeValidationIssues(
+  [{ code: "invalid_type", path: ["sessionId"], message: "Invalid input" }],
+  { sessionId: 42 },
+);
+```
+
+Consumers should treat `ValidationIssue.code`, `path`, and `message` as the portable error
+contract. Validator-native errors remain implementation details unless the consumer explicitly
+imports `/zod`.
+
+## Versioning and release
+
+The package follows semantic versioning. Breaking changes to ordinary types, normalized issue
+semantics, or exported entrypoints require a major release. Additive issue helpers and compatible
+normalization improvements may be minor releases; fixes that preserve the public contract are
+patch releases.
+
+The repository check builds and packs this package, inspects the tarball, and installs it into a
+temporary project outside the workspace. Run it from the public repository root:
+
+```sh
+pnpm check
+```
+
+That command never publishes. Registry publication, tags, and release credentials are separate
+release operations.

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+export type ValidationPathSegment = string | number;
+export interface ValidationIssue {
+    readonly code: string;
+    readonly path: readonly ValidationPathSegment[];
+    readonly message: string;
+}
+export interface ValidationIssueInput {
+    readonly code: string;
+    readonly path?: readonly PropertyKey[] | undefined;
+    readonly message: string;
+    readonly expected?: string | undefined;
+    readonly values?: readonly unknown[] | undefined;
+    readonly minimum?: number | bigint | undefined;
+    readonly maximum?: number | bigint | undefined;
+    readonly origin?: string | undefined;
+    readonly keys?: readonly unknown[] | undefined;
+    readonly format?: string | undefined;
+    readonly inclusive?: boolean | undefined;
+    readonly exact?: boolean | undefined;
+    readonly includes?: string | undefined;
+    readonly prefix?: string | undefined;
+    readonly suffix?: string | undefined;
+    readonly position?: number | undefined;
+    readonly divisor?: number | bigint | undefined;
+    readonly note?: string | undefined;
+    readonly discriminator?: string | undefined;
+    readonly options?: readonly unknown[] | undefined;
+}
+export interface ValidationErrorInput {
+    readonly issues: readonly ValidationIssueInput[];
+}
+export type ValidationInvalidValueKind = 'enum' | 'literal';
+export interface ValidationNormalizationOptions {
+    readonly resolveInvalidValueKind?: (issue: ValidationIssueInput) => ValidationInvalidValueKind | undefined;
+}
+export declare function normalizeValidationIssues(issues: readonly ValidationIssueInput[], input: unknown, options?: ValidationNormalizationOptions): readonly ValidationIssue[];
+export declare function normalizeValidationError(error: ValidationErrorInput, input: unknown, options?: ValidationNormalizationOptions): readonly ValidationIssue[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,226 @@
+const DEFAULT_FORMAT_MESSAGES = {
+  base64: ["Invalid base64-encoded string", "Invalid base64"],
+  cidrv4: ["Invalid IPv4 range", "Invalid cidr"],
+  cidrv6: ["Invalid IPv6 range", "Invalid cidr"],
+  cuid: ["Invalid cuid", "Invalid cuid"],
+  date: ["Invalid ISO date", "Invalid date"],
+  datetime: ["Invalid ISO datetime", "Invalid datetime"],
+  duration: ["Invalid ISO duration", "Invalid duration"],
+  email: ["Invalid email address", "Invalid email"],
+  emoji: ["Invalid emoji", "Invalid emoji"],
+  ipv4: ["Invalid IPv4 address", "Invalid ip"],
+  ipv6: ["Invalid IPv6 address", "Invalid ip"],
+  jwt: ["Invalid JWT", "Invalid jwt"],
+  nanoid: ["Invalid nanoid", "Invalid nanoid"],
+  time: ["Invalid ISO time", "Invalid time"],
+  ulid: ["Invalid ULID", "Invalid ulid"],
+  url: ["Invalid URL", "Invalid url"],
+  uuid: ["Invalid UUID", "Invalid uuid"]
+};
+function pathSegments(path) {
+  return (path ?? []).map(
+    (segment) => typeof segment === "number" ? segment : String(segment)
+  );
+}
+function valueAtPath(input, path) {
+  let value = input;
+  for (const segment of path) {
+    if (typeof value === "string" && typeof segment === "number") {
+      value = value.split(",")[segment];
+      continue;
+    }
+    if (value === null || typeof value !== "object") return void 0;
+    value = value[segment];
+  }
+  return value;
+}
+function quotedValue(value) {
+  if (typeof value === "string") return `'${value}'`;
+  return String(value);
+}
+function serializedLiteral(value) {
+  return JSON.stringify(
+    value,
+    (_key, item) => typeof item === "bigint" ? item.toString() : item
+  ) ?? String(value);
+}
+function receivedType(value) {
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "number" && Number.isNaN(value)) return "nan";
+  if (Array.isArray(value)) return "array";
+  if (value instanceof Date) return "date";
+  if (value instanceof Map) return "map";
+  if (value instanceof Set) return "set";
+  if (value instanceof Promise) return "promise";
+  return typeof value;
+}
+function invalidTypeIssue(issue, path, input) {
+  if (issue.code !== "invalid_type" || typeof issue.expected !== "string" || !issue.message.startsWith("Invalid input: expected ")) {
+    return null;
+  }
+  const receivedValue = valueAtPath(input, path);
+  if (receivedValue === void 0) {
+    return { code: issue.code, path, message: "Required" };
+  }
+  const expected = issue.expected === "int" ? "integer" : issue.expected;
+  const received = issue.expected === "int" && typeof receivedValue === "number" && !Number.isInteger(receivedValue) ? "float" : receivedType(receivedValue);
+  return {
+    code: issue.code,
+    path,
+    message: `Expected ${expected}, received ${received}`
+  };
+}
+function nonFiniteNumberIssue(issue, path, input) {
+  const receivedValue = valueAtPath(input, path);
+  if (issue.code !== "invalid_type" || issue.expected !== "number" || issue.message !== "Invalid input: expected number, received number" || receivedValue !== Number.POSITIVE_INFINITY && receivedValue !== Number.NEGATIVE_INFINITY) {
+    return null;
+  }
+  return {
+    code: "not_finite",
+    path,
+    message: "Number must be finite"
+  };
+}
+function limitDescription(issue, boundary, direction) {
+  const exact = issue.exact === true;
+  const inclusive = issue.inclusive !== false;
+  if (issue.origin === "array") {
+    const comparison = exact ? "exactly" : direction === "minimum" ? inclusive ? "at least" : "more than" : inclusive ? "at most" : "less than";
+    return `Array must contain ${comparison} ${boundary} element(s)`;
+  }
+  if (issue.origin === "string") {
+    const comparison = exact ? "exactly" : direction === "minimum" ? inclusive ? "at least" : "over" : inclusive ? "at most" : "under";
+    return `String must contain ${comparison} ${boundary} character(s)`;
+  }
+  if (issue.origin === "number" || issue.origin === "int") {
+    const comparison = exact ? "exactly equal to" : direction === "minimum" ? inclusive ? "greater than or equal to" : "greater than" : inclusive ? "less than or equal to" : "less than";
+    return `Number must be ${comparison} ${boundary}`;
+  }
+  if (issue.origin === "bigint") {
+    const comparison = exact ? "exactly" : direction === "minimum" ? inclusive ? "greater than or equal to" : "greater than" : inclusive ? "less than or equal to" : "less than";
+    const label = direction === "minimum" ? "Number" : "BigInt";
+    return `${label} must be ${comparison} ${boundary}`;
+  }
+  if (issue.origin === "date") {
+    const comparison = exact ? "exactly" : direction === "minimum" ? inclusive ? "greater than or equal to" : "greater than" : inclusive ? "smaller than or equal to" : "smaller than";
+    return `Date must be ${comparison} ${new Date(Number(boundary))}`;
+  }
+  return "Invalid input";
+}
+function limitIssue(issue, path) {
+  const direction = issue.code === "too_small" ? "minimum" : issue.code === "too_big" ? "maximum" : null;
+  if (direction === null || !issue.message.startsWith("Too ")) return null;
+  const boundary = issue[direction];
+  if (typeof boundary !== "number" && typeof boundary !== "bigint") return null;
+  return {
+    code: issue.code,
+    path,
+    message: limitDescription(issue, boundary, direction)
+  };
+}
+function notMultipleOfIssue(issue, path) {
+  if (issue.code !== "not_multiple_of" || typeof issue.divisor !== "number" && typeof issue.divisor !== "bigint" || issue.message !== `Invalid number: must be a multiple of ${issue.divisor}`) {
+    return null;
+  }
+  return {
+    code: issue.code,
+    path,
+    message: `Number must be a multiple of ${issue.divisor}`
+  };
+}
+function invalidUnionDiscriminatorIssue(issue, path) {
+  if (issue.code !== "invalid_union" || issue.note !== "No matching discriminator" || typeof issue.discriminator !== "string" || !Array.isArray(issue.options)) {
+    return null;
+  }
+  return {
+    code: "invalid_union_discriminator",
+    path,
+    message: issue.message
+  };
+}
+function invalidFormatMessage(issue) {
+  if (issue.format === "regex" && issue.message.startsWith("Invalid string: must match pattern ")) {
+    return "Invalid";
+  }
+  if (issue.format === "includes" && issue.includes !== void 0 && issue.message === `Invalid string: must include "${issue.includes}"`) {
+    const position = typeof issue.position === "number" ? ` at one or more positions greater than or equal to ${issue.position}` : "";
+    return `Invalid input: must include "${issue.includes}"${position}`;
+  }
+  if (issue.format === "starts_with" && issue.prefix !== void 0 && issue.message === `Invalid string: must start with "${issue.prefix}"`) {
+    return `Invalid input: must start with "${issue.prefix}"`;
+  }
+  if (issue.format === "ends_with" && issue.suffix !== void 0 && issue.message === `Invalid string: must end with "${issue.suffix}"`) {
+    return `Invalid input: must end with "${issue.suffix}"`;
+  }
+  const defaultMessage = issue.format === void 0 ? void 0 : DEFAULT_FORMAT_MESSAGES[issue.format];
+  if (defaultMessage !== void 0 && issue.message === defaultMessage[0]) {
+    return defaultMessage[1];
+  }
+  return issue.message;
+}
+function normalizeIssue(issue, input, options) {
+  const path = pathSegments(issue.path);
+  const nonFiniteNumber = nonFiniteNumberIssue(issue, path, input);
+  if (nonFiniteNumber !== null) return nonFiniteNumber;
+  const invalidType = invalidTypeIssue(issue, path, input);
+  if (invalidType !== null) return invalidType;
+  if (issue.code === "invalid_value" && Array.isArray(issue.values)) {
+    const invalidValueKind = issue.values.length === 1 ? options.resolveInvalidValueKind?.(issue) ?? "literal" : "enum";
+    if (invalidValueKind === "literal") {
+      return {
+        code: "invalid_literal",
+        path,
+        message: `Invalid literal value, expected ${serializedLiteral(issue.values[0])}`
+      };
+    }
+    const receivedValue = valueAtPath(input, path);
+    if (receivedValue === void 0) {
+      return {
+        code: "invalid_type",
+        path,
+        message: "Required"
+      };
+    }
+    return {
+      code: "invalid_enum_value",
+      path,
+      message: `Invalid enum value. Expected ${issue.values.map(quotedValue).join(" | ")}, received ${quotedValue(receivedValue)}`
+    };
+  }
+  const limit = limitIssue(issue, path);
+  if (limit !== null) return limit;
+  const notMultipleOf = notMultipleOfIssue(issue, path);
+  if (notMultipleOf !== null) return notMultipleOf;
+  const invalidUnionDiscriminator = invalidUnionDiscriminatorIssue(issue, path);
+  if (invalidUnionDiscriminator !== null) return invalidUnionDiscriminator;
+  if (issue.code === "unrecognized_keys" && Array.isArray(issue.keys)) {
+    return {
+      code: issue.code,
+      path,
+      message: `Unrecognized key(s) in object: ${issue.keys.map(quotedValue).join(", ")}`
+    };
+  }
+  if (issue.code === "invalid_format") {
+    return {
+      code: "invalid_string",
+      path,
+      message: invalidFormatMessage(issue)
+    };
+  }
+  return {
+    code: issue.code,
+    path,
+    message: issue.message
+  };
+}
+function normalizeValidationIssues(issues, input, options = {}) {
+  return issues.map((issue) => normalizeIssue(issue, input, options));
+}
+function normalizeValidationError(error, input, options = {}) {
+  return normalizeValidationIssues(error.issues, input, options);
+}
+export {
+  normalizeValidationError,
+  normalizeValidationIssues
+};

package/dist/zod.d.ts

@@ -0,0 +1,6 @@
+import { type ValidationErrorInput, type ValidationInvalidValueKind, type ValidationIssue, type ValidationIssueInput } from './index.js';
+import type { ZodType } from 'zod/v4';
+export declare function resolveZodInvalidValueKind(schema: ZodType, path: readonly PropertyKey[]): ValidationInvalidValueKind | undefined;
+export declare function normalizeZodValidationIssues(schema: ZodType, issues: readonly ValidationIssueInput[], input: unknown): readonly ValidationIssue[];
+export declare function normalizeZodValidationError(schema: ZodType, error: ValidationErrorInput, input: unknown): readonly ValidationIssue[];
+//# sourceMappingURL=zod.d.ts.map

package/dist/zod.js

@@ -0,0 +1,146 @@
+import {
+  normalizeValidationIssues
+} from "./index.js";
+function schemaNode(value) {
+  return value !== null && typeof value === "object" && "_zod" in value ? value : null;
+}
+function schemaDefinition(schema) {
+  return schemaNode(schema)?._zod?.def ?? null;
+}
+function nestedSchema(definition, key) {
+  return schemaNode(definition[key]);
+}
+function collectInvalidValueKinds(schema, path, pathIndex, depth) {
+  if (depth > path.length * 4 + 32) return [];
+  const definition = schemaDefinition(schema);
+  const schemaType = definition?.type;
+  if (definition === null || typeof schemaType !== "string") return [];
+  if (schemaType === "optional" || schemaType === "nullable" || schemaType === "default" || schemaType === "prefault" || schemaType === "catch" || schemaType === "readonly" || schemaType === "nonoptional" || schemaType === "promise") {
+    const innerType = nestedSchema(definition, "innerType");
+    return innerType === null ? [] : collectInvalidValueKinds(
+      innerType,
+      path,
+      pathIndex,
+      depth + 1
+    );
+  }
+  if (schemaType === "pipe") {
+    return [
+      ...collectInvalidValueKinds(
+        nestedSchema(definition, "in"),
+        path,
+        pathIndex,
+        depth + 1
+      ),
+      ...collectInvalidValueKinds(
+        nestedSchema(definition, "out"),
+        path,
+        pathIndex,
+        depth + 1
+      )
+    ];
+  }
+  if (schemaType === "union") {
+    const options = Array.isArray(definition.options) ? definition.options : [];
+    return options.flatMap(
+      (option) => collectInvalidValueKinds(option, path, pathIndex, depth + 1)
+    );
+  }
+  if (schemaType === "intersection") {
+    return [
+      ...collectInvalidValueKinds(
+        nestedSchema(definition, "left"),
+        path,
+        pathIndex,
+        depth + 1
+      ),
+      ...collectInvalidValueKinds(
+        nestedSchema(definition, "right"),
+        path,
+        pathIndex,
+        depth + 1
+      )
+    ];
+  }
+  if (schemaType === "lazy" && typeof definition.getter === "function") {
+    return collectInvalidValueKinds(
+      definition.getter(),
+      path,
+      pathIndex,
+      depth + 1
+    );
+  }
+  if (pathIndex === path.length) {
+    if (schemaType === "enum") return ["enum"];
+    if (schemaType === "literal") return ["literal"];
+    return [];
+  }
+  const segment = path[pathIndex];
+  if (schemaType === "object") {
+    const rawShape = typeof definition.shape === "function" ? definition.shape() : definition.shape;
+    const shape = rawShape !== null && typeof rawShape === "object" ? rawShape : {};
+    const child = schemaNode(shape[segment]);
+    const fallback = child ?? nestedSchema(definition, "catchall");
+    return fallback === null ? [] : collectInvalidValueKinds(
+      fallback,
+      path,
+      pathIndex + 1,
+      depth + 1
+    );
+  }
+  if (schemaType === "array") {
+    const element = nestedSchema(definition, "element");
+    return element === null ? [] : collectInvalidValueKinds(
+      element,
+      path,
+      pathIndex + 1,
+      depth + 1
+    );
+  }
+  if (schemaType === "tuple" && typeof segment === "number") {
+    const items = Array.isArray(definition.items) ? definition.items : [];
+    const item = schemaNode(items[segment]) ?? nestedSchema(definition, "rest");
+    return item === null ? [] : collectInvalidValueKinds(
+      item,
+      path,
+      pathIndex + 1,
+      depth + 1
+    );
+  }
+  if (schemaType === "record" || schemaType === "map" || schemaType === "set") {
+    const valueType = nestedSchema(definition, "valueType") ?? nestedSchema(definition, "element");
+    return valueType === null ? [] : collectInvalidValueKinds(
+      valueType,
+      path,
+      pathIndex + 1,
+      depth + 1
+    );
+  }
+  return [];
+}
+function resolveZodInvalidValueKind(schema, path) {
+  const kinds = new Set(
+    collectInvalidValueKinds(schema, path, 0, 0)
+  );
+  return kinds.size === 1 ? kinds.values().next().value : void 0;
+}
+function zodNormalizationOptions(schema) {
+  return {
+    resolveInvalidValueKind: (issue) => resolveZodInvalidValueKind(schema, issue.path ?? [])
+  };
+}
+function normalizeZodValidationIssues(schema, issues, input) {
+  return normalizeValidationIssues(
+    issues,
+    input,
+    zodNormalizationOptions(schema)
+  );
+}
+function normalizeZodValidationError(schema, error, input) {
+  return normalizeZodValidationIssues(schema, error.issues, input);
+}
+export {
+  normalizeZodValidationError,
+  normalizeZodValidationIssues,
+  resolveZodInvalidValueKind
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@agen-ai/validation",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Validator-neutral issue contracts and optional Zod 4 normalization for reusable AgenAI packages.",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./zod": {
+      "types": "./dist/zod.d.ts",
+      "import": "./dist/zod.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trevor-nichols/agenai-agent-sdk.git",
+    "directory": "packages/validation"
+  },
+  "homepage": "https://github.com/trevor-nichols/agenai-agent-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/trevor-nichols/agenai-agent-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "pnpm run clean && pnpm run build:runtime && pnpm run build:types",
+    "build:runtime": "tsup",
+    "build:types": "tsc --project tsconfig.json --emitDeclarationOnly --outDir dist",
+    "dev": "pnpm run build:runtime -- --watch",
+    "dev:types": "tsc --project tsconfig.json --emitDeclarationOnly --outDir dist --watch",
+    "test": "node --import tsx --test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist *.tsbuildinfo"
+  }
+}