@hiper2d/ai-agents 0.24.1 → 0.25.0

package/dist/index.d.ts

@@ -162,6 +162,17 @@ declare class ZodSchemaConverter {
      * Convert Zod schema to Mistral/DeepSeek JSON Schema format
      */
     static toMistralSchema(zodSchema: z.ZodSchema): any;
+    /**
+     * JSON Schema for Anthropic structured outputs (`output_config.format`). Anthropic takes
+     * standard JSON Schema with a few rules: every object carries `additionalProperties: false`,
+     * nullability is `anyOf: [inner, {type: "null"}]` (the OpenAPI `nullable: true` the Google
+     * path uses is an unknown keyword there, and a `["string", "null"]` type array is refused
+     * next to an enum), unions are `anyOf`, and value constraints (min/max, lengths) are not
+     * accepted — the converter never emits those. Optional keys stay out of `required`, which
+     * Anthropic allows.
+     */
+    static toAnthropicSchema(zodSchema: z.ZodSchema): any;
+    private static toStandardNullability;
     /**
      * Convert Zod schema to human-readable prompt description for Anthropic
      */
@@ -1424,8 +1435,14 @@ declare class ClaudeAgent extends AbstractAgent {
     private buildTokenUsage;
     private convertRole;
     /**
-     * New method using Zod with Anthropic's Claude API
-     * Since Anthropic doesn't support native JSON schemas, we generate prompt descriptions
+     * Schema-validated ask on Anthropic structured outputs: the Zod schema goes out as JSON
+     * Schema in `output_config.format`, so the API constrains the reply to that shape and the
+     * model cannot answer in another one. Until 0.25.0 the schema was only described in prose
+     * appended to the last message and the reply parsed as text; Sonnet 5.5 once answered a
+     * vote with a tool-call shaped `<invoke name="json">` block instead (2026-10-18). The
+     * field descriptions travel inside the schema, so nothing is appended to the prompt any
+     * more. The reply is still run through the shared lenient parser + Zod on our side: same
+     * error messages for the host's retry hints, and a guard for a null-formatted reply.
      */
     doAskWithZodSchema<T>(zodSchema: z.ZodSchema<T>, messages: AIMessage[]): Promise<[T, string, TokenUsage$1?, string?]>;
     /**

package/dist/index.js

@@ -426,6 +426,41 @@ var ZodSchemaConverter = class {
       additionalProperties: false
     });
   }
+  /**
+   * JSON Schema for Anthropic structured outputs (`output_config.format`). Anthropic takes
+   * standard JSON Schema with a few rules: every object carries `additionalProperties: false`,
+   * nullability is `anyOf: [inner, {type: "null"}]` (the OpenAPI `nullable: true` the Google
+   * path uses is an unknown keyword there, and a `["string", "null"]` type array is refused
+   * next to an enum), unions are `anyOf`, and value constraints (min/max, lengths) are not
+   * accepted — the converter never emits those. Optional keys stay out of `required`, which
+   * Anthropic allows.
+   */
+  static toAnthropicSchema(zodSchema) {
+    const schema = this.zodToJsonSchema(zodSchema, { strict: true, includeDescription: true, additionalProperties: false });
+    return this.toStandardNullability(schema);
+  }
+  static toStandardNullability(schema) {
+    if (Array.isArray(schema)) {
+      return schema.map((item) => this.toStandardNullability(item));
+    }
+    if (typeof schema !== "object" || schema === null) {
+      return schema;
+    }
+    const { nullable, oneOf, ...rest } = schema;
+    const result = {};
+    for (const [key, value] of Object.entries(rest)) {
+      result[key] = key === "enum" || key === "required" ? value : this.toStandardNullability(value);
+    }
+    if (oneOf) {
+      result.anyOf = this.toStandardNullability(oneOf);
+    }
+    if (nullable === true) {
+      const { description, anyOf, ...inner } = result;
+      const variants = anyOf ? [...anyOf, { type: "null" }] : [inner, { type: "null" }];
+      return { anyOf: variants, ...description !== void 0 ? { description } : {} };
+    }
+    return result;
+  }
   /**
    * Convert Zod schema to human-readable prompt description for Anthropic
    */
@@ -3051,26 +3086,22 @@ var ClaudeAgent = class extends AbstractAgent {
     throw new Error(this.errorMessages.unsupportedRole(role));
   }
   /**
-   * New method using Zod with Anthropic's Claude API
-   * Since Anthropic doesn't support native JSON schemas, we generate prompt descriptions
+   * Schema-validated ask on Anthropic structured outputs: the Zod schema goes out as JSON
+   * Schema in `output_config.format`, so the API constrains the reply to that shape and the
+   * model cannot answer in another one. Until 0.25.0 the schema was only described in prose
+   * appended to the last message and the reply parsed as text; Sonnet 5.5 once answered a
+   * vote with a tool-call shaped `<invoke name="json">` block instead (2026-10-18). The
+   * field descriptions travel inside the schema, so nothing is appended to the prompt any
+   * more. The reply is still run through the shared lenient parser + Zod on our side: same
+   * error messages for the host's retry hints, and a guard for a null-formatted reply.
    */
   async doAskWithZodSchema(zodSchema, messages) {
     const aiMessages = this.prepareMessages(messages);
     this.logAsking(messages);
     this.logMessages(messages);
     try {
-      const schemaDescription = ZodSchemaConverter.toPromptDescription(zodSchema);
-      const lastMessage = aiMessages[aiMessages.length - 1];
-      const fullPrompt = `${lastMessage.content}
-
-${schemaDescription}`;
-      const messagesWithSchema = [...aiMessages];
-      messagesWithSchema[messagesWithSchema.length - 1] = {
-        ...lastMessage,
-        content: fullPrompt
-      };
       const canUseThinking = this.enableThinking;
-      const anthropicMessages = canUseThinking ? this.convertToAnthropicMessagesWithThinking(messagesWithSchema) : this.convertToAnthropicMessages(messagesWithSchema);
+      const anthropicMessages = canUseThinking ? this.convertToAnthropicMessagesWithThinking(aiMessages) : this.convertToAnthropicMessages(aiMessages);
       this.applyCacheBreakpoint(anthropicMessages);
       const params = {
         ...this.defaultParams,
@@ -3094,6 +3125,10 @@ ${schemaDescription}`;
       } else {
         params.temperature = this.temperature;
       }
+      params.output_config = {
+        ...params.output_config ?? {},
+        format: { type: "json_schema", schema: ZodSchemaConverter.toAnthropicSchema(zodSchema) }
+      };
       let response;
       try {
         response = await this.client.messages.create(params);