@core-ai/core-ai 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -143,10 +143,19 @@ type ToolResultMessage = {
      */
     metadata?: Record<string, unknown>;
 };
-type ToolDefinition = {
+type ToolDefinition<TParameters extends z.ZodType = z.ZodType> = {
     name: string;
     description: string;
-    parameters: z.ZodType;
+    parameters: TParameters;
+    /**
+     * `true` opts this tool into provider-enforced schema adherence. The
+     * schema must then satisfy the strict-capable schema contract (closed
+     * objects, every key required — use `.nullable()` instead of
+     * `.optional()` — and the shared keyword subset). Omitted or `false`
+     * means non-strict on every provider. Check
+     * `model.capabilities.tools.strictSchemas` before opting in.
+     */
+    strict?: boolean;
 };
 type ToolSet = Record<string, ToolDefinition>;
 type ToolChoice = 'auto' | 'none' | 'required' | {
@@ -169,6 +178,12 @@ type ChatInputModality = 'text' | 'image' | 'file' | 'audio' | 'video';
  * from `generate` / `stream`, not those dedicated APIs.
  */
 type ChatOutputModality = 'text' | 'image' | 'audio' | 'video';
+type ToolSchemaStrictnessCapabilities = {
+    supported: false;
+} | {
+    supported: true;
+    maxStrictTools?: number;
+};
 type ModelCapabilities = {
     reasoning: {
         mode: 'unsupported' | 'optional' | 'always-on';
@@ -189,6 +204,9 @@ type ModelCapabilities = {
          */
         output: readonly ChatOutputModality[];
     };
+    tools: {
+        strictSchemas: ToolSchemaStrictnessCapabilities;
+    };
 };
 type ChatModel = {
     readonly provider: string;
@@ -433,6 +451,27 @@ type GeneratedImage = {
     revisedPrompt?: string;
 };
 
+/**
+ * A single violation of the strict-capable schema contract, reported against
+ * the JSON Schema derived from the tool's Zod `parameters`.
+ */
+type StrictToolSchemaViolation = {
+    toolName: string;
+    /** Dot path into the tool's JSON Schema, e.g. `properties.limit`. */
+    path: string;
+    /** What is wrong and how to fix it. */
+    message: string;
+};
+/**
+ * Checks the JSON Schema of a strict tool against the strict-capable schema
+ * contract: closed objects with every key required, the basic type set, and
+ * the keyword/format subset every strict-capable provider accepts.
+ *
+ * Pure and non-throwing — returns every violation found so callers can report
+ * them all at once.
+ */
+declare function getStrictToolSchemaViolations(toolName: string, schema: Record<string, unknown>): StrictToolSchemaViolation[];
+
 declare class CoreAIError extends Error {
     readonly cause?: unknown;
     readonly provider?: string;
@@ -441,6 +480,29 @@ declare class CoreAIError extends Error {
 declare class ValidationError extends CoreAIError {
     constructor(message: string, cause?: unknown, provider?: string);
 }
+type ToolSchemaStrictnessErrorReason = 'unsupported' | 'limit-exceeded' | 'invalid-schema';
+type ToolSchemaStrictnessErrorOptions = {
+    providerId: string;
+    modelId: string;
+    toolNames: readonly string[];
+} & ({
+    reason: 'unsupported';
+} | {
+    reason: 'limit-exceeded';
+    maxStrictTools: number;
+} | {
+    reason: 'invalid-schema';
+    violations: readonly StrictToolSchemaViolation[];
+});
+declare class ToolSchemaStrictnessError extends ValidationError {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly toolNames: readonly string[];
+    readonly reason: ToolSchemaStrictnessErrorReason;
+    readonly maxStrictTools?: number;
+    readonly violations?: readonly StrictToolSchemaViolation[];
+    constructor(options: ToolSchemaStrictnessErrorOptions);
+}
 type UnsupportedInputModalityErrorOptions = {
     modelId: string;
     providerId: string;
@@ -574,16 +636,42 @@ declare function parseRetryAfterSeconds(headers: Headers | Record<string, string
 /** Reads `Retry-After` from common SDK error shapes that expose `headers`. */
 declare function getRetryAfterSecondsFromError(error: unknown): number | undefined;
 
-declare function defineTool(options: ToolDefinition): ToolDefinition;
+declare function defineTool<TParameters extends ToolDefinition['parameters']>(options: ToolDefinition<TParameters>): ToolDefinition<TParameters>;
 
 /**
  * Convert a Zod schema to a JSON Schema object using Zod 4's native
  * `z.toJSONSchema()`.
  */
 declare function zodSchemaToJsonSchema(schema: z.ZodType): Record<string, unknown>;
+/**
+ * Normalizes the JSON Schema of a strict tool for providers whose strict mode
+ * requires closed objects (OpenAI-style APIs). The transform is semantics
+ * preserving with respect to the tool's Zod schema:
+ *
+ * - drops `$schema` (metadata, not a constraint),
+ * - sets `additionalProperties: false` on object nodes where absent, which
+ *   matches `z.object()` semantics (unknown keys are stripped at parse time),
+ * - drops Zod's implicit safe-integer bounds on integer nodes (see
+ *   {@link isImplicitSafeIntegerBound}),
+ * - rewrites `oneOf` to `anyOf`. Zod emits `oneOf` only for
+ *   `z.discriminatedUnion()`, whose branches are disjoint by construction, so
+ *   the two keywords accept the same values there — and strict-capable
+ *   providers accept `anyOf` only.
+ *
+ * It never widens or narrows what the user's Zod schema accepts; schemas that
+ * cannot be expressed in the strict subset are rejected by the contract
+ * validator instead of being rewritten.
+ */
+declare function normalizeStrictJsonSchema(schema: Record<string, unknown>): Record<string, unknown>;
 
 declare function stripModelDateSuffix(modelId: string): string;
 
+declare const UNSUPPORTED_TOOL_SCHEMA_STRICTNESS: Readonly<{
+    readonly supported: false;
+}>;
+declare const SUPPORTED_TOOL_SCHEMA_STRICTNESS: Readonly<{
+    readonly supported: true;
+}>;
 declare function clampReasoningEffort(effort: ReasoningEffort, supportedEfforts: readonly ReasoningEffort[]): ReasoningEffort;
 /** Text in, text out — the default chat modality profile. */
 declare const TEXT_ONLY_MODALITIES: {
@@ -616,6 +704,23 @@ type ValidateInputModalitiesOptions = {
  */
 declare function validateInputModalities({ messages, capabilities, modelId, providerId, }: ValidateInputModalitiesOptions): void;
 
+type ValidateToolSchemaStrictnessOptions = {
+    tools: ToolSet;
+    capabilities: ModelCapabilities;
+    providerId: string;
+    modelId: string;
+};
+/**
+ * Validates the strict tools of a request before it reaches the provider.
+ *
+ * Strictness is per-tool opt-in: only tools with `strict: true` are checked.
+ * Throws {@link ToolSchemaStrictnessError} when the model is known not to
+ * support strict schemas (`unsupported`), when more tools opt in than the
+ * model allows (`limit-exceeded`), or when a strict tool's schema falls
+ * outside the strict-capable schema contract (`invalid-schema`).
+ */
+declare function validateToolSchemaStrictness({ tools, capabilities, providerId, modelId, }: ValidateToolSchemaStrictnessOptions): void;
+
 declare const UNKNOWN_MODEL: unique symbol;
 type ModelCapabilitiesRegistry<TCapabilities extends ModelCapabilities = ModelCapabilities> = Record<string, TCapabilities> & {
     [UNKNOWN_MODEL]?: TCapabilities;
@@ -692,4 +797,4 @@ type GenerateImageParams = ImageGenerateOptions & {
 };
 declare function generateImage(params: GenerateImageParams): Promise<ImageGenerateResult>;
 
-export { AbortedError, type AssistantContentPart, type AssistantMessage, type AssistantTextPart, type AudioPart, type BaseGenerateOptions, type ChatInputModality, type ChatInputTokenDetails, type ChatModel, type ChatModelMiddleware, type ChatOutputModality, type ChatOutputTokenDetails, type ChatStream, type ChatUsage, ContextLengthExceededError, type ContextLengthExceededErrorOptions, CoreAIError, type CreateChatStreamOptions, type EmbedOptions, type EmbedProviderOptions, type EmbedResult, type EmbeddingModel, type EmbeddingModelMiddleware, type EmbeddingUsage, type FilePart, type FinishReason, type GenerateObjectOptions, type GenerateObjectResult, type GenerateOptions, type GenerateProviderOptions, type GenerateResult, type GeneratedImage, type ImageGenerateOptions, type ImageGenerateResult, type ImageModel, type ImageModelMiddleware, type ImagePart, type ImageProviderOptions, MULTIMODAL_INPUT_MODALITIES, type Message, type ModelCapabilities, type ModelCapabilitiesRegistry, ModelOverloadedError, type ModelOverloadedErrorOptions, type ObjectStream, type ObjectStreamEvent, ProviderError, type ProviderErrorOptions, ProviderQuotaExceededError, type ProviderQuotaExceededErrorOptions, RateLimitError, type RateLimitErrorOptions, type ReasoningConfig, type ReasoningEffort, type ReasoningPart, RetryableProviderError, ServiceUnavailableError, type ServiceUnavailableErrorOptions, StreamAbortedError, type StreamEvent, type StreamObjectOptions, StructuredOutputError, StructuredOutputNoObjectGeneratedError, StructuredOutputParseError, StructuredOutputValidationError, type SystemMessage, TEXT_ONLY_MODALITIES, type TextPart, type ToolCall, type ToolCallPart, type ToolChoice, type ToolDefinition, type ToolResultMessage, type ToolSet, UNKNOWN_MODEL, UnsupportedInputModalityError, type UnsupportedInputModalityErrorOptions, type UserContentPart, type UserMessage, type ValidateInputModalitiesOptions, ValidationError, asObject, asRecord, assistantMessage, clampReasoningEffort, createChatStream, createObjectStream, defineTool, embed, generate, generateImage, generateObject, getErrorMessage, getHttpStatusCode, getProviderMetadata, getRegisteredModelCapabilities, getRetryAfterSecondsFromError, getString, isAbortErrorByName, isRateLimitStatus, isTransientUnavailableStatus, parseRetryAfterSeconds, resultToMessage, safeParseJsonObject, stream, streamObject, stripModelDateSuffix, supportsInputModality, supportsOutputModality, validateInputModalities, wrapChatModel, wrapEmbeddingModel, wrapImageModel, zodSchemaToJsonSchema };
+export { AbortedError, type AssistantContentPart, type AssistantMessage, type AssistantTextPart, type AudioPart, type BaseGenerateOptions, type ChatInputModality, type ChatInputTokenDetails, type ChatModel, type ChatModelMiddleware, type ChatOutputModality, type ChatOutputTokenDetails, type ChatStream, type ChatUsage, ContextLengthExceededError, type ContextLengthExceededErrorOptions, CoreAIError, type CreateChatStreamOptions, type EmbedOptions, type EmbedProviderOptions, type EmbedResult, type EmbeddingModel, type EmbeddingModelMiddleware, type EmbeddingUsage, type FilePart, type FinishReason, type GenerateObjectOptions, type GenerateObjectResult, type GenerateOptions, type GenerateProviderOptions, type GenerateResult, type GeneratedImage, type ImageGenerateOptions, type ImageGenerateResult, type ImageModel, type ImageModelMiddleware, type ImagePart, type ImageProviderOptions, MULTIMODAL_INPUT_MODALITIES, type Message, type ModelCapabilities, type ModelCapabilitiesRegistry, ModelOverloadedError, type ModelOverloadedErrorOptions, type ObjectStream, type ObjectStreamEvent, ProviderError, type ProviderErrorOptions, ProviderQuotaExceededError, type ProviderQuotaExceededErrorOptions, RateLimitError, type RateLimitErrorOptions, type ReasoningConfig, type ReasoningEffort, type ReasoningPart, RetryableProviderError, SUPPORTED_TOOL_SCHEMA_STRICTNESS, ServiceUnavailableError, type ServiceUnavailableErrorOptions, StreamAbortedError, type StreamEvent, type StreamObjectOptions, type StrictToolSchemaViolation, StructuredOutputError, StructuredOutputNoObjectGeneratedError, StructuredOutputParseError, StructuredOutputValidationError, type SystemMessage, TEXT_ONLY_MODALITIES, type TextPart, type ToolCall, type ToolCallPart, type ToolChoice, type ToolDefinition, type ToolResultMessage, type ToolSchemaStrictnessCapabilities, ToolSchemaStrictnessError, type ToolSchemaStrictnessErrorOptions, type ToolSchemaStrictnessErrorReason, type ToolSet, UNKNOWN_MODEL, UNSUPPORTED_TOOL_SCHEMA_STRICTNESS, UnsupportedInputModalityError, type UnsupportedInputModalityErrorOptions, type UserContentPart, type UserMessage, type ValidateInputModalitiesOptions, type ValidateToolSchemaStrictnessOptions, ValidationError, asObject, asRecord, assistantMessage, clampReasoningEffort, createChatStream, createObjectStream, defineTool, embed, generate, generateImage, generateObject, getErrorMessage, getHttpStatusCode, getProviderMetadata, getRegisteredModelCapabilities, getRetryAfterSecondsFromError, getStrictToolSchemaViolations, getString, isAbortErrorByName, isRateLimitStatus, isTransientUnavailableStatus, normalizeStrictJsonSchema, parseRetryAfterSeconds, resultToMessage, safeParseJsonObject, stream, streamObject, stripModelDateSuffix, supportsInputModality, supportsOutputModality, validateInputModalities, validateToolSchemaStrictness, wrapChatModel, wrapEmbeddingModel, wrapImageModel, zodSchemaToJsonSchema };

package/dist/index.js

@@ -15,6 +15,49 @@ var ValidationError = class extends CoreAIError {
     this.name = "ValidationError";
   }
 };
+var ToolSchemaStrictnessError = class extends ValidationError {
+  providerId;
+  modelId;
+  toolNames;
+  reason;
+  maxStrictTools;
+  violations;
+  constructor(options) {
+    super(
+      getToolSchemaStrictnessErrorMessage(options),
+      void 0,
+      options.providerId
+    );
+    this.name = "ToolSchemaStrictnessError";
+    this.providerId = options.providerId;
+    this.modelId = options.modelId;
+    this.toolNames = options.toolNames;
+    this.reason = options.reason;
+    if (options.reason === "limit-exceeded") {
+      this.maxStrictTools = options.maxStrictTools;
+    }
+    if (options.reason === "invalid-schema") {
+      this.violations = options.violations;
+    }
+  }
+};
+function getToolSchemaStrictnessErrorMessage(options) {
+  const tools = options.toolNames.length === 0 ? "(none)" : options.toolNames.map((name) => `"${name}"`).join(", ");
+  switch (options.reason) {
+    case "limit-exceeded": {
+      const toolWord = options.maxStrictTools === 1 ? "tool" : "tools";
+      return `${options.providerId} model "${options.modelId}" supports at most ${options.maxStrictTools} strict ${toolWord}, but received ${options.toolNames.length}: ${tools}`;
+    }
+    case "invalid-schema": {
+      const violations = options.violations.map(
+        (violation) => `tool "${violation.toolName}"${violation.path === "" ? "" : ` at ${violation.path}`}: ${violation.message}`
+      ).join("; ");
+      return `${options.providerId} model "${options.modelId}" received strict tools whose schemas are outside the strict-capable schema contract: ${violations}`;
+    }
+    case "unsupported":
+      return `${options.providerId} model "${options.modelId}" does not support per-tool strict schemas. Requested by: ${tools}`;
+  }
+}
 var UnsupportedInputModalityError = class extends ValidationError {
   requestedModalities;
   supportedModalities;
@@ -256,6 +299,348 @@ function zodSchemaToJsonSchema(schema) {
     io: "input"
   });
 }
+var MAX_SAFE_INTEGER_BOUND = 9007199254740991;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isObjectSchemaNode(node) {
+  return node.type === "object" || isPlainObject(node.properties);
+}
+function isImplicitSafeIntegerBound(node, key) {
+  if (node.type !== "integer") {
+    return false;
+  }
+  return key === "minimum" ? node.minimum === -MAX_SAFE_INTEGER_BOUND : node.maximum === MAX_SAFE_INTEGER_BOUND;
+}
+var NESTED_MAP_KEYWORDS = ["properties"];
+var NESTED_LIST_KEYWORDS = ["anyOf", "oneOf", "allOf"];
+var NESTED_SINGLE_KEYWORDS = ["items"];
+var DEFINITION_KEYWORDS = ["$defs", "definitions"];
+function getChildSchemaNodeEntries(node) {
+  const entries = getNamedChildEntries(node, NESTED_MAP_KEYWORDS);
+  for (const keyword of NESTED_SINGLE_KEYWORDS) {
+    if (node[keyword] !== void 0) {
+      entries.push({ segment: keyword, child: node[keyword] });
+    }
+  }
+  for (const keyword of NESTED_LIST_KEYWORDS) {
+    const value = node[keyword];
+    if (Array.isArray(value)) {
+      value.forEach((child, index) => {
+        entries.push({ segment: `${keyword}.${index}`, child });
+      });
+    }
+  }
+  return entries;
+}
+function getSchemaDefinitionEntries(node) {
+  return getNamedChildEntries(node, DEFINITION_KEYWORDS);
+}
+function getNamedChildEntries(node, keywords) {
+  const entries = [];
+  for (const keyword of keywords) {
+    const value = node[keyword];
+    if (isPlainObject(value)) {
+      for (const [key, child] of Object.entries(value)) {
+        entries.push({ segment: `${keyword}.${key}`, child });
+      }
+    }
+  }
+  return entries;
+}
+function mapChildSchemaNodes(node, map) {
+  const result = { ...node };
+  for (const keyword of [...NESTED_MAP_KEYWORDS, ...DEFINITION_KEYWORDS]) {
+    const value = result[keyword];
+    if (isPlainObject(value)) {
+      result[keyword] = Object.fromEntries(
+        Object.entries(value).map(([key, child]) => [key, map(child)])
+      );
+    }
+  }
+  for (const keyword of NESTED_SINGLE_KEYWORDS) {
+    if (result[keyword] !== void 0) {
+      result[keyword] = map(result[keyword]);
+    }
+  }
+  for (const keyword of NESTED_LIST_KEYWORDS) {
+    const value = result[keyword];
+    if (Array.isArray(value)) {
+      result[keyword] = value.map((child) => map(child));
+    }
+  }
+  return result;
+}
+function normalizeStrictJsonSchema(schema) {
+  return normalizeObjectNode(schema);
+}
+function normalizeNode(node) {
+  return isPlainObject(node) ? normalizeObjectNode(node) : node;
+}
+function normalizeObjectNode(node) {
+  const stripped = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "$schema") {
+      continue;
+    }
+    if ((key === "minimum" || key === "maximum") && isImplicitSafeIntegerBound(node, key)) {
+      continue;
+    }
+    stripped[key] = value;
+  }
+  const result = mapChildSchemaNodes(stripped, normalizeNode);
+  if (Array.isArray(result.oneOf) && result.anyOf === void 0) {
+    result.anyOf = result.oneOf;
+    delete result.oneOf;
+  }
+  if (isObjectSchemaNode(result) && result.additionalProperties === void 0) {
+    result.additionalProperties = false;
+  }
+  return result;
+}
+
+// src/strict-tool-schema-contract.ts
+var MAX_SCHEMA_DEPTH = 64;
+var ALLOWED_KEYWORDS = /* @__PURE__ */ new Set([
+  "$schema",
+  "$ref",
+  "$defs",
+  "definitions",
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "enum",
+  "const",
+  "anyOf",
+  "oneOf",
+  "format",
+  "pattern",
+  "title",
+  "description",
+  "default",
+  "examples",
+  "minimum",
+  "maximum"
+]);
+var ALLOWED_TYPES = /* @__PURE__ */ new Set([
+  "object",
+  "array",
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "null"
+]);
+var ALLOWED_STRING_FORMATS = /* @__PURE__ */ new Set([
+  "date-time",
+  "time",
+  "date",
+  "duration",
+  "email",
+  "hostname",
+  "ipv4",
+  "ipv6",
+  "uuid"
+]);
+var BOUND_HINTS = {
+  minimum: "remove numeric bounds (.min()/.gt()/.gte()) \u2014 numeric range constraints are outside the strict-capable subset; validate ranges after parsing instead",
+  maximum: "remove numeric bounds (.max()/.lt()/.lte()) \u2014 numeric range constraints are outside the strict-capable subset; validate ranges after parsing instead"
+};
+var KEYWORD_HINTS = {
+  ...BOUND_HINTS,
+  minLength: "remove .min()/.length() \u2014 string length constraints are outside the strict-capable subset; validate lengths after parsing instead",
+  maxLength: "remove .max()/.length() \u2014 string length constraints are outside the strict-capable subset; validate lengths after parsing instead",
+  exclusiveMinimum: "remove .gt() \u2014 numeric range constraints are outside the strict-capable subset; validate ranges after parsing instead",
+  exclusiveMaximum: "remove .lt() \u2014 numeric range constraints are outside the strict-capable subset; validate ranges after parsing instead",
+  multipleOf: "remove .multipleOf()/.step() \u2014 numeric constraints are outside the strict-capable subset; validate after parsing instead",
+  minItems: "remove .min()/.nonempty() on arrays \u2014 array length constraints are outside the strict-capable subset; validate after parsing instead",
+  maxItems: "remove .max() on arrays \u2014 array length constraints are outside the strict-capable subset; validate after parsing instead",
+  uniqueItems: "array uniqueness constraints are outside the strict-capable subset; validate after parsing instead",
+  prefixItems: "tuples (z.tuple) are not strict-capable; use a uniform z.array() or an object instead",
+  allOf: "intersections (z.intersection()/.and(), serialized as allOf) are not strict-capable; flatten the members into a single z.object() instead",
+  not: "negated schemas (not) are not strict-capable",
+  patternProperties: "pattern properties are not strict-capable; declare explicit keys with z.object()",
+  propertyNames: "property-name constraints are not strict-capable; declare explicit keys with z.object()"
+};
+function getStrictToolSchemaViolations(toolName, schema) {
+  const violations = [];
+  const refEdges = /* @__PURE__ */ new Map();
+  if (schema.type !== "object") {
+    violations.push({
+      toolName,
+      path: "type",
+      message: "tool parameters must be an object at the root; wrap the schema in z.object()"
+    });
+  }
+  walkNode(schema, "", "root", 0, toolName, violations, refEdges);
+  for (const { segment, child } of getSchemaDefinitionEntries(schema)) {
+    walkNode(child, segment, segment, 0, toolName, violations, refEdges);
+  }
+  for (const region of findCyclicRegions(refEdges)) {
+    violations.push({
+      toolName,
+      path: region === "root" ? "" : region,
+      message: "recursive schemas (z.lazy or self-referencing types) are not strict-capable"
+    });
+  }
+  return violations;
+}
+function walkNode(node, path, region, depth, toolName, violations, refEdges) {
+  if (!isPlainObject(node)) {
+    return;
+  }
+  if (depth > MAX_SCHEMA_DEPTH) {
+    violations.push({
+      toolName,
+      path,
+      message: `schema nesting exceeds the supported depth of ${MAX_SCHEMA_DEPTH}`
+    });
+    return;
+  }
+  for (const key of Object.keys(node)) {
+    if (ALLOWED_KEYWORDS.has(key)) {
+      continue;
+    }
+    const hint = KEYWORD_HINTS[key];
+    violations.push({
+      toolName,
+      path: joinPath(path, key),
+      message: hint ?? `keyword "${key}" is outside the strict-capable subset; remove it and validate after parsing instead`
+    });
+  }
+  validateBounds(node, path, toolName, violations);
+  validateType(node, path, toolName, violations);
+  validateFormat(node, path, toolName, violations);
+  validateObjectShape(node, path, toolName, violations);
+  validateRef(node, path, region, toolName, violations, refEdges);
+  for (const { segment, child } of getChildSchemaNodeEntries(node)) {
+    walkNode(
+      child,
+      joinPath(path, segment),
+      region,
+      depth + 1,
+      toolName,
+      violations,
+      refEdges
+    );
+  }
+}
+function validateBounds(node, path, toolName, violations) {
+  for (const key of ["minimum", "maximum"]) {
+    if (key in node && !isImplicitSafeIntegerBound(node, key)) {
+      violations.push({
+        toolName,
+        path: joinPath(path, key),
+        message: BOUND_HINTS[key]
+      });
+    }
+  }
+}
+function validateType(node, path, toolName, violations) {
+  if (!("type" in node)) {
+    return;
+  }
+  const types = Array.isArray(node.type) ? node.type : [node.type];
+  for (const type of types) {
+    if (typeof type !== "string" || !ALLOWED_TYPES.has(type)) {
+      violations.push({
+        toolName,
+        path: joinPath(path, "type"),
+        message: `type "${String(type)}" is outside the strict-capable subset (object, array, string, number, integer, boolean, null)`
+      });
+    }
+  }
+}
+function validateFormat(node, path, toolName, violations) {
+  if (typeof node.format !== "string") {
+    return;
+  }
+  if (!ALLOWED_STRING_FORMATS.has(node.format)) {
+    violations.push({
+      toolName,
+      path: joinPath(path, "format"),
+      message: `format "${node.format}" is outside the strict-capable subset (${[...ALLOWED_STRING_FORMATS].join(", ")}); remove the format refinement (for URLs, use z.string() instead of z.url()) and validate after parsing instead`
+    });
+  }
+}
+function validateObjectShape(node, path, toolName, violations) {
+  if (!isObjectSchemaNode(node)) {
+    return;
+  }
+  const properties = isPlainObject(node.properties) ? node.properties : {};
+  const required = new Set(
+    Array.isArray(node.required) ? node.required.filter((key) => typeof key === "string") : []
+  );
+  for (const key of Object.keys(properties)) {
+    if (!required.has(key)) {
+      violations.push({
+        toolName,
+        path: joinPath(path, `properties.${key}`),
+        message: `"${key}" is optional; strict schemas require every key \u2014 use .nullable() instead of .optional() (note that .default() also makes a key optional)`
+      });
+    }
+  }
+  if ("additionalProperties" in node && node.additionalProperties !== false) {
+    violations.push({
+      toolName,
+      path: joinPath(path, "additionalProperties"),
+      message: "open objects are not strict-capable; use z.object() with explicit keys instead of z.record(), .catchall(), .passthrough(), or z.looseObject()"
+    });
+  }
+}
+function validateRef(node, path, region, toolName, violations, refEdges) {
+  if (typeof node.$ref !== "string") {
+    return;
+  }
+  if (node.$ref === "#") {
+    addRefEdge(refEdges, region, "root");
+    return;
+  }
+  const match = /^#\/(\$defs|definitions)\/([^/]+)$/.exec(node.$ref);
+  if (!match) {
+    violations.push({
+      toolName,
+      path: joinPath(path, "$ref"),
+      message: `only local references into $defs are strict-capable; found "${node.$ref}"`
+    });
+    return;
+  }
+  addRefEdge(refEdges, region, `${match[1]}.${match[2]}`);
+}
+function addRefEdge(refEdges, from, to) {
+  const edges = refEdges.get(from) ?? /* @__PURE__ */ new Set();
+  edges.add(to);
+  refEdges.set(from, edges);
+}
+function findCyclicRegions(refEdges) {
+  const cyclic = /* @__PURE__ */ new Set();
+  const visiting = /* @__PURE__ */ new Set();
+  const done = /* @__PURE__ */ new Set();
+  function visit(region) {
+    if (done.has(region)) {
+      return;
+    }
+    if (visiting.has(region)) {
+      cyclic.add(region);
+      return;
+    }
+    visiting.add(region);
+    for (const target of refEdges.get(region) ?? []) {
+      visit(target);
+    }
+    visiting.delete(region);
+    done.add(region);
+  }
+  for (const region of refEdges.keys()) {
+    visit(region);
+  }
+  return [...cyclic];
+}
+function joinPath(path, segment) {
+  return path === "" ? segment : `${path}.${segment}`;
+}
 
 // src/model-id.ts
 var MODEL_DATE_SUFFIX_PATTERN = /[-@](?:\d{8}|\d{4}-\d{2}-\d{2})$/;
@@ -271,6 +656,12 @@ var EFFORT_RANK = {
   high: 3,
   max: 4
 };
+var UNSUPPORTED_TOOL_SCHEMA_STRICTNESS = Object.freeze({
+  supported: false
+});
+var SUPPORTED_TOOL_SCHEMA_STRICTNESS = Object.freeze({
+  supported: true
+});
 function clampReasoningEffort(effort, supportedEfforts) {
   if (supportedEfforts.includes(effort)) {
     return effort;
@@ -349,6 +740,63 @@ function collectRequestedInputModalities(messages) {
   return [...requested];
 }
 
+// src/validate-tool-schema-strictness.ts
+var contractViolationCache = /* @__PURE__ */ new WeakMap();
+function getContractViolations(tool) {
+  let cached = contractViolationCache.get(tool.parameters);
+  if (cached === void 0) {
+    cached = getStrictToolSchemaViolations(
+      tool.name,
+      zodSchemaToJsonSchema(tool.parameters)
+    ).map(({ path, message }) => ({ path, message }));
+    contractViolationCache.set(tool.parameters, cached);
+  }
+  return cached.map((violation) => ({ toolName: tool.name, ...violation }));
+}
+function validateToolSchemaStrictness({
+  tools,
+  capabilities,
+  providerId,
+  modelId
+}) {
+  const strictTools = Object.values(tools).filter(
+    (tool) => tool.strict === true
+  );
+  if (strictTools.length === 0) {
+    return;
+  }
+  const strictToolNames = strictTools.map((tool) => tool.name);
+  const strictCapabilities = capabilities.tools.strictSchemas;
+  if (!strictCapabilities.supported) {
+    throw new ToolSchemaStrictnessError({
+      providerId,
+      modelId,
+      toolNames: strictToolNames,
+      reason: "unsupported"
+    });
+  }
+  const maxStrictTools = strictCapabilities.maxStrictTools;
+  if (maxStrictTools !== void 0 && strictTools.length > maxStrictTools) {
+    throw new ToolSchemaStrictnessError({
+      providerId,
+      modelId,
+      toolNames: strictToolNames,
+      reason: "limit-exceeded",
+      maxStrictTools
+    });
+  }
+  const violations = strictTools.flatMap(getContractViolations);
+  if (violations.length > 0) {
+    throw new ToolSchemaStrictnessError({
+      providerId,
+      modelId,
+      toolNames: [...new Set(violations.map((v) => v.toolName))],
+      reason: "invalid-schema",
+      violations
+    });
+  }
+}
+
 // src/model-capabilities-registry.ts
 var UNKNOWN_MODEL = /* @__PURE__ */ Symbol("unknown-model");
 function getRegisteredModelCapabilities(registry, modelId) {
@@ -1000,6 +1448,7 @@ export {
   ProviderQuotaExceededError,
   RateLimitError,
   RetryableProviderError,
+  SUPPORTED_TOOL_SCHEMA_STRICTNESS,
   ServiceUnavailableError,
   StreamAbortedError,
   StructuredOutputError,
@@ -1007,7 +1456,9 @@ export {
   StructuredOutputParseError,
   StructuredOutputValidationError,
   TEXT_ONLY_MODALITIES,
+  ToolSchemaStrictnessError,
   UNKNOWN_MODEL,
+  UNSUPPORTED_TOOL_SCHEMA_STRICTNESS,
   UnsupportedInputModalityError,
   ValidationError,
   asObject,
@@ -1026,10 +1477,12 @@ export {
   getProviderMetadata,
   getRegisteredModelCapabilities,
   getRetryAfterSecondsFromError,
+  getStrictToolSchemaViolations,
   getString,
   isAbortErrorByName,
   isRateLimitStatus,
   isTransientUnavailableStatus,
+  normalizeStrictJsonSchema,
   parseRetryAfterSeconds,
   resultToMessage,
   safeParseJsonObject,
@@ -1039,6 +1492,7 @@ export {
   supportsInputModality,
   supportsOutputModality,
   validateInputModalities,
+  validateToolSchemaStrictness,
   wrapChatModel,
   wrapEmbeddingModel,
   wrapImageModel,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@core-ai/core-ai",
-    "version": "0.24.0",
+    "version": "0.25.0",
     "description": "Type-safe LLM abstraction layer over native provider SDKs",
     "license": "MIT",
     "author": "Omnifact (https://omnifact.ai)",