[BUG] tool-output-available TypeValidationError with Anthropic SDK — toUIMessageStream() path not covered by PR #1202

[Phantomn]

Describe the bug

PR #1202 fixed providerMetadata forwarding in convertFullStreamChunkToUIMessageStream (guardrail pipeline path), but there is a second, uncovered path that still causes TypeValidationError: unrecognized_keys ["providerMetadata"] on tool-output-available chunks when using @ai-sdk/anthropic.

The error is thrown in the console.voltagent.dev browser client when it parses the SSE stream via parseJsonEventStream({ schema: uiMessageChunkSchema }) — the browser bundle's schema does not include providerMetadata on tool-output-available.

Root cause chain

@ai-sdk/anthropic@3.0.78 (line 3832)
  → tool-call.providerMetadata = { anthropic: { caller: { type: "direct" } } }

ai@6.0.182 (line 3056)
  → tool-result.providerMetadata = (copied from tool-call)

ai@6.0.182 toUIMessageStream() (line 8121)
  → SSE: { type: "tool-output-available", ..., providerMetadata: { anthropic: { caller: ... } } }

console.voltagent.dev browser bundle
  → parseJsonEventStream + old uiMessageChunkSchema
  → TypeValidationError: unrecognized_keys ["providerMetadata"]

The key difference from PR #1202 (Google Vertex thinking models): Anthropic's caller metadata is injected by @ai-sdk/anthropic on every tool call, not just thinking models. The propagation happens entirely within the AI SDK's toUIMessageStream() method — VoltAgent's convertFullStreamChunkToUIMessageStream is never involved in this path.

Path analysis

Path 1 (fixed by PR #1202): guardrail pipeline
result.fullStream → convertFullStreamChunkToUIMessageStream → guardrailPipeline.createUIStream() → SSE

Path 2 (still broken): no guardrail / AI SDK direct
result.toUIMessageStream() → createUIMessageStream({ writer.merge(...) }) → SSE
↑ This is getGuardrailAwareUIStream when !guardrailPipeline (line ~32047 in 2.7.4)

Steps to reproduce

1. Use @ai-sdk/anthropic as the model provider (any version that sends caller in API response)
2. Call an agent with any tool
3. Observe TypeValidationError on tool-output-available in the VoltAgent console

Error

Type validation failed: Value: {"type":"tool-output-available","toolCallId":"...","output":{...},"providerMetadata":{"anthropic":{"caller":{"type":"direct"}}}}.
Error message: [{"code":"invalid_union","errors":[[...],["code":"unrecognized_keys","keys":["providerMetadata"]],...]}]

Packages

• @voltagent/core: 2.7.4 (also reproduced on 2.7.1, 2.7.2, 2.7.3)
• @ai-sdk/anthropic: 3.0.78
• ai: 6.0.182

Expected behavior

tool-output-available chunks with providerMetadata should not cause a validation error. Either:

1. The console client schema should be updated to accept providerMetadata on tool-output-available (correct fix), or
2. The server should strip providerMetadata from tool-output-available before sending SSE (workaround)

Workaround

Add a strip transform in toUIMessageStreamSanitized (VoltAgent core):

const stripProviderMetadataFromUIStream = (stream: ReadableStream) =>
  stream.pipeThrough(new TransformStream({
    transform(chunk, controller) {
      if (chunk?.type === "tool-output-available" && "providerMetadata" in chunk) {
        const { providerMetadata: _pm, ...rest } = chunk;
        controller.enqueue(rest);
      } else {
        controller.enqueue(chunk);
      }
    }
  }));

const toUIMessageStreamSanitized = (streamOptions) => {
  const resolvedStreamOptions = applyResponseMessageId(streamOptions);
  const baseStream = agent.subAgentManager.hasSubAgents()
    ? createMergedUIStream(resolvedStreamOptions)
    : getGuardrailAwareUIStream(resolvedStreamOptions);
  return attachFeedbackMetadata(stripProviderMetadataFromUIStream(baseStream));
};

This issue is related to #1195 and PR #1202 but affects Anthropic users independently of thinking models.

[Phantomn]

Update: ESM path not covered by initial workaround

After further investigation, the workaround in the original report had a critical gap.

Root cause of workaround failure

Projects using "type": "module" in package.json cause Node.js to load dist/index.mjs (ESM), not dist/index.js (CJS). The initial patch only added stripProviderMetadataFromUIStream to dist/index.js, so the fix never ran in ESM environments.

Additional issue with pipeThrough approach

The initial implementation used stream.pipeThrough(new TransformStream({...})). Since createMergedUIStream returns a createAsyncIterableReadable (VoltAgent's internal stream type), using pipeThrough may produce a plain ReadableStream that loses compatibility with downstream VoltAgent stream consumers. Switching to the same createAsyncIterableReadable pattern used by attachFeedbackMetadata is more robust.

Updated workaround

The fix must be applied to both dist/index.js and dist/index.mjs, using createAsyncIterableReadable instead of pipeThrough:

const stripProviderMetadataFromUIStream = /* @__PURE__ */ __name((stream) => {
  return createAsyncIterableReadable(async (controller) => {
    const reader = stream.getReader();
    try {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        if (value !== void 0) {
          if (value != null && (value.type === "tool-output-available" || value.type === "tool-output-error") && "providerMetadata" in value) {
            const { providerMetadata: _pm, ...rest } = value;
            controller.enqueue(rest);
          } else {
            controller.enqueue(value);
          }
        }
      }
      controller.close();
    } catch (error) {
      controller.error(error);
    } finally {
      reader.releaseLock();
    }
  });
}, "stripProviderMetadataFromUIStream");

Applied immediately before toUIMessageStreamSanitized in both files, replacing return attachFeedbackMetadata(baseStream) with return attachFeedbackMetadata(stripProviderMetadataFromUIStream(baseStream)).

Affected chunk types

• tool-output-available — primary failure case (reported in original issue)
• tool-output-error — same schema, same problem

Long-term fix

The proper fix remains updating uiMessageChunkSchema in the console bundle to allow providerMetadata as an optional field on tool-output-available and tool-output-error. The workaround is required for every VoltAgent patch upgrade until then.

[jingchang0623-crypto]

这个问题我也遇到过！在妙趣AI（miaoquai.com）的运营中，我们大量使用 Anthropic SDK 来做 AI 内容生成，providerMetadata 的处理确实是个坑。

我们的解法

我们用的 workaround 跟你的类似，但更轻量——直接在 SDK 调用层做拦截：

根本原因

Anthropic SDK 的 事件 schema 确实没有 字段，但 VoltAgent 的 stream 合并逻辑会把 SDK 内部元数据带出来。

建议

除了修复 ，建议在 里加一个 sanitize 中间件：

这样可以避免每次升级都要手动 patch 和 。

P.S. 如果你在找 Anthropic SDK 的踩坑实录，miaoquai.com/stories/ 里有不少实战案例 😉

---

妙趣AI | miaoquai.com - AI Agent 踩坑实录 · OpenClaw 教程 · 术语百科

[midhunxavier]

I'd like to pick this up and open a PR — is it OK to take it?

Building on @Phantomn's analysis: the leak survives on the sanitized UI-stream path (toUIMessageStreamSanitized in packages/core/src/agent/agent.ts), which only wraps the base stream with attachFeedbackMetadata. PR #1202's conversion lives on the fullStream/guardrail path and never runs here, so providerMetadata from @ai-sdk/anthropic passes straight through onto tool-output-available / tool-output-error chunks.

My plan is a small helper (stripProviderMetadataFromUIStream) using the existing createAsyncIterableReadable pattern, applied just before attachFeedbackMetadata, stripping providerMetadata from only those two chunk types. I'll deliberately leave the fullStream conversion untouched so providers that depend on forwarded metadata (#1195) aren't regressed, and add regression tests + a changeset.

Happy to adjust the approach if you'd prefer the schema-side fix on the console client instead.