feat: add support for response-healing plugin (#361)

* feat: add support for response-healing plugin

Co-Authored-By: Robert Yeakel <robert.yeakel@openrouter.ai>

* docs: enhance JSDoc for response-healing plugin with clearer streaming limitation

Co-Authored-By: Robert Yeakel <robert.yeakel@openrouter.ai>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: robert-j-y

.changeset/add-response-healing-plugin.md

@@ -0,0 +1,21 @@
+---
+"@openrouter/ai-sdk-provider": minor
+---
+
+Add support for the Response Healing plugin
+
+The Response Healing plugin automatically validates and repairs malformed JSON responses from AI models. Enable it by adding `{ id: 'response-healing' }` to the plugins array when using structured outputs with `generateObject`.
+
+```typescript
+const model = openrouter('openai/gpt-4o', {
+  plugins: [{ id: 'response-healing' }],
+});
+
+const { object } = await generateObject({
+  model,
+  schema: z.object({ name: z.string(), age: z.number() }),
+  prompt: 'Generate a person.',
+});
+```
+
+Note: Response Healing only works with non-streaming requests.

README.md

@@ -307,6 +307,34 @@ for await (const partialComponent of result.partialObjectStream) {
 
 ## Use Cases
 
+### Response Healing for Structured Outputs
+
+The provider supports the [Response Healing plugin](https://openrouter.ai/docs/guides/features/plugins/response-healing), which automatically validates and repairs malformed JSON responses from AI models. This is particularly useful when using `generateObject` or structured outputs, as it can fix common issues like missing brackets, trailing commas, markdown wrappers, and mixed text.
+
+```typescript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { generateObject } from 'ai';
+import { z } from 'zod';
+
+const openrouter = createOpenRouter({ apiKey: 'your-api-key' });
+const model = openrouter('openai/gpt-4o', {
+  plugins: [{ id: 'response-healing' }],
+});
+
+const { object } = await generateObject({
+  model,
+  schema: z.object({
+    name: z.string(),
+    age: z.number(),
+  }),
+  prompt: 'Generate a person with name and age.',
+});
+
+console.log(object); // { name: "John", age: 30 }
+```
+
+Note that Response Healing only works with non-streaming requests. When the model returns imperfect JSON formatting, the plugin attempts to repair the response so you receive valid, parseable JSON.
+
 ### Debugging API Requests
 
 The provider supports a debug mode that echoes back the request body sent to the upstream provider. This is useful for troubleshooting and understanding how your requests are being processed. Note that debug mode only works with streaming requests.

src/chat/index.test.ts

@@ -773,6 +773,51 @@ describe('doGenerate', () => {
     });
   });
 
+  it('should pass response-healing plugin in request payload', async () => {
+    prepareJsonResponse({ content: '{"name": "John", "age": 30}' });
+
+    const modelWithPlugin = provider.chat('anthropic/claude-3.5-sonnet', {
+      plugins: [{ id: 'response-healing' }],
+    });
+
+    await modelWithPlugin.doGenerate({
+      prompt: TEST_PROMPT,
+      responseFormat: {
+        type: 'json',
+        schema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            age: { type: 'number' },
+          },
+          required: ['name', 'age'],
+        },
+        name: 'PersonResponse',
+      },
+    });
+
+    expect(await server.calls[0]!.requestBodyJson).toStrictEqual({
+      model: 'anthropic/claude-3.5-sonnet',
+      messages: [{ role: 'user', content: 'Hello' }],
+      plugins: [{ id: 'response-healing' }],
+      response_format: {
+        type: 'json_schema',
+        json_schema: {
+          schema: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              age: { type: 'number' },
+            },
+            required: ['name', 'age'],
+          },
+          strict: true,
+          name: 'PersonResponse',
+        },
+      },
+    });
+  });
+
   it('should pass images', async () => {
     prepareJsonResponse({
       content: '',

src/types/openrouter-api-types.ts

@@ -28,6 +28,13 @@ export type IdFileParser = 'file-parser';
  */
 export type IdModeration = 'moderation';
 
+/**
+ * Plugin identifier for response healing.
+ * Automatically validates and repairs malformed JSON responses.
+ * @see https://openrouter.ai/docs/guides/features/plugins/response-healing
+ */
+export type IdResponseHealing = 'response-healing';
+
 /**
  * Search engine options for web search.
  * Open enum - accepts known values or any string for forward compatibility.

src/types/openrouter-chat-settings.ts

@@ -4,6 +4,7 @@ import type {
   Engine,
   IdFileParser,
   IdModeration,
+  IdResponseHealing,
   IdWeb,
   PdfEngine,
   ProviderSort,
@@ -74,6 +75,18 @@ monitor and detect abuse. Learn more.
     | {
         id: IdModeration;
       }
+    | {
+        /**
+         * Response healing plugin - automatically validates and repairs malformed JSON responses.
+         *
+         * **Important:** This plugin only works with non-streaming requests (e.g., `generateObject`).
+         * It has no effect when used with streaming methods like `streamObject` or `streamText`.
+         * The plugin activates when using `response_format` with `json_schema` or `json_object`.
+         *
+         * @see https://openrouter.ai/docs/guides/features/plugins/response-healing
+         */
+        id: IdResponseHealing;
+      }
   >;
 
   /**