feat(ai): add generic metadata field to StreamOptions, closes #1384

Add metadata?: Record<string, unknown> to StreamOptions so providers
can extract fields they understand. Anthropic provider extracts user_id
for abuse tracking and rate limiting. Other providers ignore it.

Based on #1384 by @7Sageer, reworked to use a generic type instead of
Anthropic-specific typing on the base interface.

packages/ai/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added optional `metadata` field to `StreamOptions` for passing provider-specific metadata (e.g. Anthropic `user_id` for abuse tracking/rate limiting) ([#1384](https://github.com/badlogic/pi-mono/pull/1384) by [@7Sageer](https://github.com/7Sageer))
+
 ## [0.52.9] - 2026-02-08
 
 ### Changed

packages/ai/src/providers/anthropic.ts

@@ -594,6 +594,13 @@ function buildParams(
 		}
 	}
 
+	if (options?.metadata) {
+		const userId = options.metadata.user_id;
+		if (typeof userId === "string") {
+			params.metadata = { user_id: userId };
+		}
+	}
+
 	if (options?.toolChoice) {
 		if (typeof options.toolChoice === "string") {
 			params.tool_choice = { type: options.toolChoice };

packages/ai/src/providers/simple-options.ts

@@ -11,6 +11,7 @@ export function buildBaseOptions(model: Model<Api>, options?: SimpleStreamOption
 		headers: options?.headers,
 		onPayload: options?.onPayload,
 		maxRetryDelayMs: options?.maxRetryDelayMs,
+		metadata: options?.metadata,
 	};
 }
 

packages/ai/src/types.ts

@@ -87,6 +87,12 @@ export interface StreamOptions {
 	 * Default: 60000 (60 seconds). Set to 0 to disable the cap.
 	 */
 	maxRetryDelayMs?: number;
+	/**
+	 * Optional metadata to include in API requests.
+	 * Providers extract the fields they understand and ignore the rest.
+	 * For example, Anthropic uses `user_id` for abuse tracking and rate limiting.
+	 */
+	metadata?: Record<string, unknown>;
 }
 
 export type ProviderStreamOptions = StreamOptions & Record<string, unknown>;