feat: Expose OpenRouter extra parameters

[voxathon]

tl;dr: This adds a typed passthrough openrouter_extras to the AI chat completion service to allow for advanced use-cases involving ZDR (Zero Data Retention), OpenRouter's built-in web search plugin, and structured outputs. This also allows users to enable thinking for Anthropic's Claude or control the CoT budget for Google's Gemini.

Before this change, the OpenRouterProvider had cherry-picked parameters, which prevented users from utilizing OpenRouter-specific features such as:

• JSON mode / Structured Outputs (response_format)
• Provider routing preferences (provider.order, allow_fallbacks)
• Reasoning effort configuration (reasoning)

---

Main Changes

src/backend/src/services/ai/chat/providers/types.ts

• Added IOpenRouterExtras interface with autocomplete for common parameters and [key: string]: unknown escape hatch for forward compatibility

src/backend/src/services/ai/chat/providers/OpenRouterProvider/OpenRouterProvider.ts

• Spread openrouter_extras into upstream OpenAI SDK requests

src/backend/src/services/ai/AIInterfaceService.js

• Added openrouter_extras: { type: 'json' } to the puter-chat-completion interface definition

src/puter-js/src/modules/AI.js

• Added 'openrouter_extras' to PARAMS_TO_PASS array

src/backend/src/services/ai/chat/AIChatService.ts

• Improved 4xx error detection for OpenRouter responses to prevent unnecessary fallback attempts
• Extracts actual provider error messages from OpenRouter's nested metadata.raw structure

---

Usage

puter.ai.chat("What are the latest developments in AI? Respond in json", {
    model: "openrouter:minimax/minimax-m2.1",
    openrouter_extras: {
        plugins: [{
            "id": "web"
        }],
        response_format: {
            "type": "json_object"
        },
        provider: {
            order: ["Fireworks", "Chutes"],
            allow_fallbacks: false
        },
        reasoning: {
            effort: "high"
        }
    }
}).then(console.log)

Output:

{
  "logprobs": null,
  "finish_reason": "stop",
  "native_finish_reason": "stop",
  "index": 0,
  "message": {
    "role": "assistant",
    "content": "{\n\"latest_ai_developments\": [\n{\n\"company\": \"Google\",\n\"model_name\": \"Gemini 3 Pro\",\n\"release_date\": \"2025-11-18\",\n\"key_features\": [\"State-of-the-art reasoning capabilities\", \"...\"],\n\"availability\": [\"Gemini app\", \"AI Mode in Search\", \"...\"],\n\"source\": \"https://blog.google/...\"\n},\n{\n\"company\": \"Google\",\n\"announcement\": \"Deep Research Agent & Interactions API\",\n\"release_date\": \"2025-12-11\",\n\"key_features\": [\"Reimagined Deep Research agent\", \"Interactions API\", \"...\"],\n\"source\": \"https://techcrunch.com/...\"\n},\n{\n\"company\": \"OpenAI\",\n\"model_name\": \"GPT-5.2\",\n\"release_date\": \"2025-12-11\",\n\"key_features\": [\"Best model for everyday professional use\", \"...\"],\n\"source\": \"https://www.theverge.com/...\"\n}\n],\n\"market_context\": { \"...\": \"...\" },\n\"trend_analysis\": { \"...\": \"...\" },\n\"benchmark_highlights\": { \"...\": \"...\" }\n}",
    "refusal": null,
    "reasoning": "...",
    "reasoning_details": [
      {
        "format": null,
        "index": 0,
        "type": "reasoning.text",
        "text": "..."
      }
    ],
    "annotations": [
      {
        "type": "url_citation",
        "url_citation": {
          "url": "https://techcrunch.com/2025/12/11/google-launched-its-deepest-ai-research-agent-yet-on-the-same-day-openai-dropped-gpt-5-2/",
          "start_index": 0,
          "end_index": 0,
          "title": "Google launched its deepest AI research agent yet — on the same day OpenAI dropped GPT-5.2",
          "content": "..."
        }
      },
      {
        "type": "url_citation",
        "url_citation": {
          "url": "https://blog.google/intl/en-africa/company-news/outreach-and-initiatives/a-new-era-of-intelligence-with-gemini-3/",
          "start_index": 0,
          "end_index": 0,
          "title": "A new era of intelligence with Gemini 3",
          "content": "..."
        }
      },
      {
        "type": "url_citation",
        "url_citation": {
          "url": "https://developers.googleblog.com/new-gemini-api-updates-for-gemini-3/",
          "start_index": 0,
          "end_index": 0,
          "title": "New Gemini API updates for Gemini 3",
          "content": "..."
        }
      },
      {
        "type": "url_citation",
        "url_citation": {
          "url": "https://www.theverge.com/ai-artificial-intelligence/842529/openai-gpt-5-2-new-model-chatgpt",
          "start_index": 0,
          "end_index": 0,
          "title": "GPT-5.2 is OpenAI’s latest move in the agentic AI battle",
          "content": "..."
        }
      },
      {
        "type": "url_citation",
        "url_citation": {
          "url": "https://blog.google/technology/developers/interactions-api/",
          "start_index": 0,
          "end_index": 0,
          "title": "Interactions API: A unified foundation for models and agents",
          "content": "..."
        }
      }
    ]
  },
  "usage": {
    "prompt": 19182,
    "completion": 928,
    "input_cache_read": 3
  },
  "via_ai_chat_service": true
}

---

Notes

• The puter.js SDK will need to be rebuilt for client-side usage
• OpenRouter validates parameters server-side; invalid configurations will return 4xx errors, which are now properly surfaced instead of triggering fallback logic
• $0.08 was burned in the testing of this PR :)

This was done in an effort to address ( #2228 ).

[CLAassistant]

All committers have signed the CLA.

[ProgrammerIn-wonderland]

Not against this, but we cannot comply with ZDR policies as we do keep data about prompts and responses internally and for moderation purposes

[jelveh]

We could still allow ZDR as it relates to OpenRouter. i.e., the user is asking OpenRouter not to retain data. if that's the case, is this mergeable?

[ProgrammerIn-wonderland]

I don't think so, I think there's some inherent dangers with how openrouter_extras is destructured directly into the OpenAI SDK params. I'm concerned it could interfere with usage billing which would be quite significant. I do like the concept but I don't like how it's implemented. There probably needs to be strict validation of every option and a whitelist probably needs to be built

[ProgrammerIn-wonderland]

GitHub Mobile seems to be glitching out but check out line 98 in Openrouter provider in this PR

[voxathon]

There probably needs to be strict validation of every option and a whitelist probably needs to be built

That's fair enough.

---

it could interfere with usage billing which would be quite significant.

Oh, right. Whoops. Let me get on that.

[ProgrammerIn-wonderland]

Slightly unprofessional for me to comment on this but I am enjoying the whimsical commit names lol

[ProgrammerIn-wonderland]

Hey is there any issues in continuing this PR? If its stale I can try and work on it myself @voxathon