Middleware Telemetry Safety

Operator wants every call to enforce maxTokens<=2000 regardless of caller. They mutate the params arg in-place inside transformParams.

Middleware transformParams({params}) must return a new params object (immutable transform). Returning undefined or mutating in place leads to inconsistent provider state across concurrent calls. Use `return { ...params, maxTokens: Math.min(params.maxTokens ?? 2000, 2000) }`.

Cache middleware keys requests by JSON.stringify(messages); a small change in the system prompt does not invalidate cached responses.

Cache key must include every field the provider sees: model id, system, messages, tools (schemas), tool_choice, temperature, maxTokens, and any providerOptions that affect output (cache_control, response_format). Hash the post-transformParams payload, not the caller-supplied one.

wrapStream middleware buffers all stream parts to log them, then emits the buffered parts at the end. UI shows nothing until completion.

wrapStream must forward parts as they arrive — implement as an async iterable that yields each upstream part after side effects. Buffering destroys the streaming UX. If you must log, log on-the-fly into the side channel and pass through unchanged.