@ag-ui/core 0.1.1-canary.beta.0 → 1.0.0

package/dist/index.js

@@ -1,6 +1,774 @@
-const require_events = require('./events-CMtdFXWl.js');
+const require_version = require('./version-BIes0ykB.js');
 
-//#region src/types.ts
+//#region src/generated/serialization.ts
+const shapes = {
+	TextMessageStartEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId",
+			"role",
+			"name"
+		],
+		fields: {}
+	},
+	TextMessageContentEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	TextMessageEndEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	TextMessageChunkEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId",
+			"messageId",
+			"role",
+			"delta",
+			"name"
+		],
+		fields: {}
+	},
+	ToolCallStartEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId",
+			"parentMessageId"
+		],
+		fields: {}
+	},
+	ToolCallArgsEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	ToolCallEndEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	ToolCallChunkEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId",
+			"toolCallId",
+			"toolCallName",
+			"parentMessageId",
+			"delta"
+		],
+		fields: {}
+	},
+	TextPart: {
+		optional: ["id", "metadata"],
+		fields: {}
+	},
+	DataSource: {
+		optional: [],
+		fields: {}
+	},
+	UrlSource: {
+		optional: ["mimeType"],
+		fields: {}
+	},
+	FileSource: {
+		optional: ["provider", "mimeType"],
+		fields: {}
+	},
+	PartSource: {
+		discriminator: "type",
+		variants: {
+			data: "DataSource",
+			url: "UrlSource",
+			file: "FileSource"
+		}
+	},
+	ImagePart: {
+		optional: ["id", "metadata"],
+		fields: { source: "PartSource" }
+	},
+	AudioPart: {
+		optional: ["id", "metadata"],
+		fields: { source: "PartSource" }
+	},
+	VideoPart: {
+		optional: ["id", "metadata"],
+		fields: { source: "PartSource" }
+	},
+	DocumentPart: {
+		optional: ["id", "metadata"],
+		fields: { source: "PartSource" }
+	},
+	ContentPart: {
+		discriminator: "type",
+		variants: {
+			text: "TextPart",
+			image: "ImagePart",
+			audio: "AudioPart",
+			video: "VideoPart",
+			document: "DocumentPart"
+		}
+	},
+	ToolCallResultEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId",
+			"role"
+		],
+		fields: { content: { array: "ContentPart" } }
+	},
+	StateSnapshotEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	AddOperation: {
+		optional: [],
+		fields: {}
+	},
+	RemoveOperation: {
+		optional: [],
+		fields: {}
+	},
+	ReplaceOperation: {
+		optional: [],
+		fields: {}
+	},
+	MoveOperation: {
+		optional: [],
+		fields: {}
+	},
+	CopyOperation: {
+		optional: [],
+		fields: {}
+	},
+	TestOperation: {
+		optional: [],
+		fields: {}
+	},
+	JsonPatchOperation: {
+		discriminator: "op",
+		variants: {
+			add: "AddOperation",
+			remove: "RemoveOperation",
+			replace: "ReplaceOperation",
+			move: "MoveOperation",
+			copy: "CopyOperation",
+			test: "TestOperation"
+		}
+	},
+	StateDeltaEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: { delta: { array: "JsonPatchOperation" } }
+	},
+	DeveloperMessage: {
+		optional: [
+			"subagentRunId",
+			"name",
+			"encryptedValue",
+			"metadata"
+		],
+		fields: {}
+	},
+	SystemMessage: {
+		optional: [
+			"subagentRunId",
+			"name",
+			"encryptedValue",
+			"metadata"
+		],
+		fields: {}
+	},
+	FunctionCall: {
+		optional: [],
+		fields: {}
+	},
+	ToolCall: {
+		optional: ["encryptedValue", "metadata"],
+		fields: { function: "FunctionCall" }
+	},
+	AssistantMessage: {
+		optional: [
+			"subagentRunId",
+			"name",
+			"encryptedValue",
+			"metadata",
+			"content",
+			"toolCalls"
+		],
+		fields: { toolCalls: { array: "ToolCall" } }
+	},
+	UserMessage: {
+		optional: [
+			"subagentRunId",
+			"name",
+			"encryptedValue",
+			"metadata"
+		],
+		fields: { content: { array: "ContentPart" } }
+	},
+	ToolMessage: {
+		optional: [
+			"subagentRunId",
+			"error",
+			"encryptedValue",
+			"metadata"
+		],
+		fields: { content: { array: "ContentPart" } }
+	},
+	ActivityMessage: {
+		optional: ["subagentRunId", "metadata"],
+		fields: {}
+	},
+	ReasoningMessage: {
+		optional: [
+			"subagentRunId",
+			"encryptedValue",
+			"metadata"
+		],
+		fields: {}
+	},
+	Message: {
+		discriminator: "role",
+		variants: {
+			developer: "DeveloperMessage",
+			system: "SystemMessage",
+			assistant: "AssistantMessage",
+			user: "UserMessage",
+			tool: "ToolMessage",
+			activity: "ActivityMessage",
+			reasoning: "ReasoningMessage"
+		}
+	},
+	MessagesSnapshotEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata"
+		],
+		fields: { messages: { array: "Message" } }
+	},
+	ActivitySnapshotEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId",
+			"replace"
+		],
+		fields: {}
+	},
+	ActivityDeltaEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: { patch: { array: "JsonPatchOperation" } }
+	},
+	RawEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId",
+			"source"
+		],
+		fields: {}
+	},
+	CustomEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	Tool: {
+		optional: ["parameters", "metadata"],
+		fields: {}
+	},
+	Context: {
+		optional: [],
+		fields: {}
+	},
+	ResumeEntry: {
+		optional: ["payload", "metadata"],
+		fields: {}
+	},
+	RunAgentInput: {
+		optional: [
+			"protocolVersion",
+			"parentRunId",
+			"state",
+			"tools",
+			"context",
+			"forwardedProps",
+			"resume"
+		],
+		fields: {
+			messages: { array: "Message" },
+			tools: { array: "Tool" },
+			context: { array: "Context" },
+			resume: { array: "ResumeEntry" }
+		}
+	},
+	RunStartedEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"protocolVersion",
+			"parentRunId",
+			"input"
+		],
+		fields: { input: "RunAgentInput" }
+	},
+	RunFinishedSuccessOutcome: {
+		optional: ["pendingToolCallIds"],
+		fields: {}
+	},
+	Interrupt: {
+		optional: [
+			"subagentRunId",
+			"message",
+			"toolCallId",
+			"responseSchema",
+			"expiresAt",
+			"metadata"
+		],
+		fields: {}
+	},
+	RunFinishedInterruptOutcome: {
+		optional: [],
+		fields: { interrupts: { array: "Interrupt" } }
+	},
+	RunFinishedCancelledOutcome: {
+		optional: [],
+		fields: {}
+	},
+	RunFinishedOutcome: {
+		discriminator: "type",
+		variants: {
+			success: "RunFinishedSuccessOutcome",
+			interrupt: "RunFinishedInterruptOutcome",
+			cancelled: "RunFinishedCancelledOutcome"
+		}
+	},
+	TokenUsage: {
+		optional: [
+			"provider",
+			"model",
+			"inputTokens",
+			"outputTokens",
+			"totalTokens",
+			"reasoningTokens",
+			"cachedInputTokens",
+			"cacheWriteInputTokens"
+		],
+		fields: {}
+	},
+	RunFinishedEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"result",
+			"outcome",
+			"usage"
+		],
+		fields: {
+			outcome: "RunFinishedOutcome",
+			usage: { array: "TokenUsage" }
+		}
+	},
+	RunErrorEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"code",
+			"usage"
+		],
+		fields: { usage: { array: "TokenUsage" } }
+	},
+	StepStartedEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	StepFinishedEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	ReasoningStartEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	ReasoningMessageStartEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	ReasoningMessageContentEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	ReasoningMessageEndEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	ReasoningMessageChunkEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId",
+			"messageId",
+			"delta"
+		],
+		fields: {}
+	},
+	ReasoningEndEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	ReasoningEncryptedValueEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"subagentRunId"
+		],
+		fields: {}
+	},
+	SubagentStartedEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"description",
+			"parentSubagentRunId",
+			"parentToolCallId",
+			"parentMessageId"
+		],
+		fields: {}
+	},
+	SubagentFinishedSuccessOutcome: {
+		optional: [],
+		fields: {}
+	},
+	SubagentFinishedSuspendedOutcome: {
+		optional: ["interruptIds"],
+		fields: {}
+	},
+	SubagentFinishedOutcome: {
+		discriminator: "type",
+		variants: {
+			success: "SubagentFinishedSuccessOutcome",
+			suspended: "SubagentFinishedSuspendedOutcome"
+		}
+	},
+	SubagentFinishedEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"result",
+			"outcome"
+		],
+		fields: { outcome: "SubagentFinishedOutcome" }
+	},
+	SubagentErrorEvent: {
+		optional: [
+			"timestamp",
+			"rawEvent",
+			"metadata",
+			"code"
+		],
+		fields: {}
+	},
+	Event: {
+		discriminator: "type",
+		variants: {
+			TEXT_MESSAGE_START: "TextMessageStartEvent",
+			TEXT_MESSAGE_CONTENT: "TextMessageContentEvent",
+			TEXT_MESSAGE_END: "TextMessageEndEvent",
+			TEXT_MESSAGE_CHUNK: "TextMessageChunkEvent",
+			TOOL_CALL_START: "ToolCallStartEvent",
+			TOOL_CALL_ARGS: "ToolCallArgsEvent",
+			TOOL_CALL_END: "ToolCallEndEvent",
+			TOOL_CALL_CHUNK: "ToolCallChunkEvent",
+			TOOL_CALL_RESULT: "ToolCallResultEvent",
+			STATE_SNAPSHOT: "StateSnapshotEvent",
+			STATE_DELTA: "StateDeltaEvent",
+			MESSAGES_SNAPSHOT: "MessagesSnapshotEvent",
+			ACTIVITY_SNAPSHOT: "ActivitySnapshotEvent",
+			ACTIVITY_DELTA: "ActivityDeltaEvent",
+			RAW: "RawEvent",
+			CUSTOM: "CustomEvent",
+			RUN_STARTED: "RunStartedEvent",
+			RUN_FINISHED: "RunFinishedEvent",
+			RUN_ERROR: "RunErrorEvent",
+			STEP_STARTED: "StepStartedEvent",
+			STEP_FINISHED: "StepFinishedEvent",
+			REASONING_START: "ReasoningStartEvent",
+			REASONING_MESSAGE_START: "ReasoningMessageStartEvent",
+			REASONING_MESSAGE_CONTENT: "ReasoningMessageContentEvent",
+			REASONING_MESSAGE_END: "ReasoningMessageEndEvent",
+			REASONING_MESSAGE_CHUNK: "ReasoningMessageChunkEvent",
+			REASONING_END: "ReasoningEndEvent",
+			REASONING_ENCRYPTED_VALUE: "ReasoningEncryptedValueEvent",
+			SUBAGENT_STARTED: "SubagentStartedEvent",
+			SUBAGENT_FINISHED: "SubagentFinishedEvent",
+			SUBAGENT_ERROR: "SubagentErrorEvent"
+		}
+	},
+	SubagentInfo: {
+		optional: ["description"],
+		fields: {}
+	},
+	IdentityCapabilities: {
+		optional: [
+			"name",
+			"type",
+			"description",
+			"version",
+			"provider",
+			"documentationUrl",
+			"metadata"
+		],
+		fields: {}
+	},
+	TransportCapabilities: {
+		optional: [
+			"streaming",
+			"websocket",
+			"httpBinary",
+			"pushNotifications",
+			"resumable"
+		],
+		fields: {}
+	},
+	ToolsCapabilities: {
+		optional: [
+			"supported",
+			"items",
+			"parallelCalls",
+			"clientProvided"
+		],
+		fields: { items: { array: "Tool" } }
+	},
+	OutputCapabilities: {
+		optional: ["structuredOutput", "supportedMimeTypes"],
+		fields: {}
+	},
+	StateCapabilities: {
+		optional: [
+			"snapshots",
+			"deltas",
+			"memory",
+			"persistentState"
+		],
+		fields: {}
+	},
+	MultiAgentCapabilities: {
+		optional: [
+			"supported",
+			"delegation",
+			"handoffs",
+			"subagents"
+		],
+		fields: { subagents: { array: "SubagentInfo" } }
+	},
+	ReasoningCapabilities: {
+		optional: [
+			"supported",
+			"streaming",
+			"encrypted"
+		],
+		fields: {}
+	},
+	MultimodalInputCapabilities: {
+		optional: [
+			"image",
+			"audio",
+			"video",
+			"pdf",
+			"file"
+		],
+		fields: {}
+	},
+	MultimodalOutputCapabilities: {
+		optional: ["image", "audio"],
+		fields: {}
+	},
+	MultimodalCapabilities: {
+		optional: ["input", "output"],
+		fields: {
+			input: "MultimodalInputCapabilities",
+			output: "MultimodalOutputCapabilities"
+		}
+	},
+	ExecutionCapabilities: {
+		optional: [
+			"codeExecution",
+			"sandboxed",
+			"maxIterations",
+			"maxExecutionTime"
+		],
+		fields: {}
+	},
+	HumanInTheLoopCapabilities: {
+		optional: [
+			"supported",
+			"approvals",
+			"interventions",
+			"feedback",
+			"interrupts",
+			"approveWithEdits"
+		],
+		fields: {}
+	},
+	AgentCapabilities: {
+		optional: [
+			"identity",
+			"transport",
+			"tools",
+			"output",
+			"state",
+			"multiAgent",
+			"reasoning",
+			"multimodal",
+			"execution",
+			"humanInTheLoop",
+			"custom"
+		],
+		fields: {
+			identity: "IdentityCapabilities",
+			transport: "TransportCapabilities",
+			tools: "ToolsCapabilities",
+			output: "OutputCapabilities",
+			state: "StateCapabilities",
+			multiAgent: "MultiAgentCapabilities",
+			reasoning: "ReasoningCapabilities",
+			multimodal: "MultimodalCapabilities",
+			execution: "ExecutionCapabilities",
+			humanInTheLoop: "HumanInTheLoopCapabilities"
+		}
+	}
+};
+function omit(value, shape) {
+	if (typeof shape === "string") return omit(value, shapes[shape]);
+	if ("array" in shape) {
+		if (!Array.isArray(value)) return value;
+		const result = value.map((item) => omit(item, shape.array));
+		return result.every((item, index) => item === value[index]) ? value : result;
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+	const object = value;
+	if ("discriminator" in shape) {
+		const tag = object[shape.discriminator];
+		return typeof tag === "string" && Object.prototype.hasOwnProperty.call(shape.variants, tag) ? omit(value, shape.variants[tag]) : value;
+	}
+	let result = object;
+	for (const key of shape.optional) if (Object.prototype.hasOwnProperty.call(object, key) && object[key] === null) {
+		if (result === object) result = { ...object };
+		delete result[key];
+	}
+	for (const [key, child] of Object.entries(shape.fields)) {
+		if (!Object.prototype.hasOwnProperty.call(result, key)) continue;
+		const next = omit(result[key], child);
+		if (next !== result[key]) {
+			if (result === object) result = { ...object };
+			result[key] = next;
+		}
+	}
+	return result;
+}
+/**
+* Omits whole optional null fields before transmission. Does not validate,
+* mutate the input, or traverse arbitrary application JSON or unknown fields.
+* Required null payloads and null values inside opaque data remain intact.
+*/
+function omitOptionalNulls(value, root) {
+	return omit(value, root);
+}
+
+//#endregion
+//#region src/compat.ts
 var AGUIError = class extends Error {
 	constructor(message) {
 		super(message);
@@ -12,8 +780,275 @@ var AGUIConnectNotImplementedError = class extends AGUIError {
 	}
 };
 
+//#endregion
+//#region src/metadata.ts
+/**
+* The key reserved for AG-UI's own use inside a metadata object. Every other
+* key is user space.
+*
+* Reservation is by convention: nothing rejects a write to this key at runtime,
+* because metadata is open by key and validating its shape would contradict
+* that.
+*/
+const AGUI_METADATA_KEY = "ag-ui";
+/**
+* Extra information attached to an event or a message.
+*
+* Open by key — any JSON value is allowed under a key, including `null`.
+*
+* Deliberately `z.any()` rather than a recursive JSON-value schema, which review
+* has suggested more than once. Two reasons. Every dynamic payload in the
+* protocol uses the permissive form — `state`, `rawEvent`, `CustomEvent.value`,
+* `ActivityMessage.content`, and the pre-existing `Tool.metadata` and
+* `Interrupt.metadata` — so tightening this one field would make it the sole
+* outlier while fixing nothing elsewhere. And a recursive validation would walk
+* every value on every event, on the streaming hot path, to catch a mistake
+* (a function, a bigint) that already fails loudly at encode time.
+*
+* The schema itself now lives in the generated source (MetadataSchema in
+* src/generated/schemas.ts); this comment survives as the recorded reasoning.
+*/
+/**
+* How metadata is declared on events and messages: the object is absent or an
+* object, never `null`. The validator pinning that invariant is
+* `OptionalMetadataSchema`, which lives in src/schemas.ts along with every
+* other runtime validator this package ships.
+*/
+/**
+* Folds `incoming` metadata into `existing`, key by key, with the last write
+* winning.
+*
+* A message is assembled from a sequence of events, and the interesting values
+* — token usage and finish reason among them — are only known at the end. So
+* metadata accumulates as the sequence arrives rather than being fixed at the
+* start.
+*
+* A key's value is replaced outright. This never recurses, so an array or
+* object under any key — including {@link AGUI_METADATA_KEY} — is replaced
+* wholesale rather than blended with what was there before.
+*
+* Returns a new object rather than mutating either argument. An absent
+* `incoming` returns `existing` untouched; an empty `incoming` changes nothing.
+*/
+function mergeMetadata(existing, incoming) {
+	if (incoming === void 0) return existing;
+	if (existing === void 0) return { ...incoming };
+	return {
+		...existing,
+		...incoming
+	};
+}
+
+//#endregion
+//#region src/token-usage.ts
+/** The AG-UI names of the six token counts, in the order an entry lists them. */
+const COUNT_KEYS = [
+	"inputTokens",
+	"outputTokens",
+	"totalTokens",
+	"reasoningTokens",
+	"cachedInputTokens",
+	"cacheWriteInputTokens"
+];
+/**
+* The count keys already warned about, so the diagnostic below fires once per
+* process per key rather than once per event. A provider that hands over a
+* string count hands one over on every call, and a per-call warning would bury
+* the stream it is meant to annotate.
+*/
+const warnedCountKeys = /* @__PURE__ */ new Set();
+/** What the value WAS, said in a way that points at the provider's bug. */
+const describeRejected = (v) => {
+	if (v === null) return "null";
+	if (typeof v === "string") return `${JSON.stringify(v)} (a string)`;
+	if (typeof v === "number") return `${String(v)} (a non-finite number)`;
+	if (typeof v === "object") return `an object`;
+	return `${String(v)} (a ${typeof v})`;
+};
+/**
+* Accept a value only if it is a real, finite number.
+*
+* Shared by both vendor mappers so they guard identically. Providers do hand
+* over strings, `null`s and `NaN`s in their usage metadata, and a bad value must
+* not reach the wire: consumers validate every incoming event and throw on
+* failure, so one malformed count would fail an otherwise-successful run at its
+* final event — costing the user the answer, not just the token count.
+*
+* Dropping it is right; dropping it in silence is not. The usage this run
+* reports is then simply wrong, with nothing anywhere saying which count went
+* missing or why, so a present-but-unusable value is named once per key.
+*
+* `undefined` and `NaN` are exempt because they are not defects: they are how a
+* provider spells "did not report this count". `undefined` covers both shapes —
+* an absent key in LangChain's `usage_metadata`, an explicit `undefined` in
+* AI-SDK's `LanguageModelUsage` — and AI-SDK uses `NaN` for the same thing,
+* which is why its mapper's docstring says so. Warning on those would fire on
+* ordinary traffic and train the reader to ignore the message.
+*
+* `key` is the AG-UI count name the value was headed for, not the vendor's
+* spelling of it, so one message reads the same whichever mapper produced it.
+*/
+const num = (v, key) => {
+	if (typeof v === "number" && Number.isFinite(v)) return v;
+	if (!(v === void 0 || typeof v === "number" && Number.isNaN(v)) && !warnedCountKeys.has(key)) {
+		warnedCountKeys.add(key);
+		console.warn(`[ag-ui] usage.${key} was ${describeRejected(v)}, not a number — omitted from this run's usage. Reported once per key.`);
+	}
+};
+/**
+* Read a property from a value of unknown shape, yielding `undefined` for
+* anything that is not an object. Lets the mappers take `unknown` rather than
+* `any` — vendor payloads are untrusted, so every access should be narrowed
+* rather than assumed.
+*/
+const prop = (v, key) => typeof v === "object" && v !== null ? v[key] : void 0;
+/**
+* Build a {@link TokenUsage} from already-guarded counts, or `undefined` when no
+* count survived. Returning `undefined` rather than a labels-only entry keeps
+* "the provider reported no usage" distinct from "the provider reported usage",
+* so callers omit the field instead of emitting an entry that claims nothing.
+*/
+function buildEntry(counts, { provider, model }) {
+	if (!COUNT_KEYS.some((key) => counts[key] !== void 0)) return void 0;
+	const entry = {};
+	if (provider != null) entry.provider = provider;
+	if (model != null) entry.model = model;
+	for (const key of COUNT_KEYS) {
+		const value = counts[key];
+		if (value !== void 0) entry[key] = value;
+	}
+	return entry;
+}
+/**
+* Map a LangChain-family `usage_metadata` object into an AG-UI {@link TokenUsage}.
+*
+* LangChain and LangGraph both attach usage as `{ input_tokens, output_tokens,
+* total_tokens, input_token_details: { cache_read, cache_creation },
+* output_token_details: { reasoning } }`. LangChain's accounting is the
+* protocol's — `input_tokens` already includes the cache details and
+* `output_tokens` the reasoning detail — so every count passes through as is.
+* This maps only those numeric counts plus optional provider/model labels —
+* never prompt/completion content. A count the provider
+* did not return is simply absent from `usage_metadata` and reads as
+* `undefined` here; that is not a defect and draws no warning. Returns
+* `undefined` when no usable count is present, so callers can omit usage rather
+* than report zeros.
+*/
+function tokenUsageFromLangChainMetadata(usageMetadata, { provider, model }) {
+	if (!usageMetadata) return void 0;
+	const inputDetails = prop(usageMetadata, "input_token_details");
+	const outputDetails = prop(usageMetadata, "output_token_details");
+	return buildEntry({
+		inputTokens: num(prop(usageMetadata, "input_tokens"), "inputTokens"),
+		outputTokens: num(prop(usageMetadata, "output_tokens"), "outputTokens"),
+		totalTokens: num(prop(usageMetadata, "total_tokens"), "totalTokens"),
+		reasoningTokens: num(prop(outputDetails, "reasoning"), "reasoningTokens"),
+		cachedInputTokens: num(prop(inputDetails, "cache_read"), "cachedInputTokens"),
+		cacheWriteInputTokens: num(prop(inputDetails, "cache_creation"), "cacheWriteInputTokens")
+	}, {
+		provider,
+		model
+	});
+}
+/**
+* Map an AI-SDK `LanguageModelUsage` object into an AG-UI {@link TokenUsage}.
+*
+* AI-SDK's v5 keys already match — `inputTokens`, `outputTokens`,
+* `totalTokens`, `reasoningTokens`, `cachedInputTokens` — with the totals
+* inclusive the way the protocol counts them. v6 adds `inputTokenDetails:
+* { cacheReadTokens, cacheWriteTokens }` and `outputTokenDetails:
+* { reasoningTokens }`; the cache-write count exists only there, and the two
+* counts present in both forms are read from the top level first. AI-SDK
+* reports `NaN`/`undefined` for counts a provider didn't return, so only finite
+* numbers are copied. Returns `undefined` when no finite count is present (so
+* callers omit empty usage).
+*/
+function tokenUsageFromAiSdkUsage(usage, { provider, model }) {
+	if (!usage) return void 0;
+	const inputDetails = prop(usage, "inputTokenDetails");
+	const outputDetails = prop(usage, "outputTokenDetails");
+	return buildEntry({
+		inputTokens: num(prop(usage, "inputTokens"), "inputTokens"),
+		outputTokens: num(prop(usage, "outputTokens"), "outputTokens"),
+		totalTokens: num(prop(usage, "totalTokens"), "totalTokens"),
+		reasoningTokens: num(prop(usage, "reasoningTokens"), "reasoningTokens") ?? num(prop(outputDetails, "reasoningTokens"), "reasoningTokens"),
+		cachedInputTokens: num(prop(usage, "cachedInputTokens"), "cachedInputTokens") ?? num(prop(inputDetails, "cacheReadTokens"), "cachedInputTokens"),
+		cacheWriteInputTokens: num(prop(inputDetails, "cacheWriteTokens"), "cacheWriteInputTokens")
+	}, {
+		provider,
+		model
+	});
+}
+/**
+* Sum per-call {@link TokenUsage} entries into one entry per `(provider, model)`
+* pair. Order follows first appearance. A count field stays `undefined` when no
+* member of the group reported it, so "not reported" stays distinct from zero.
+*
+* Protocol-agnostic: works on any producer's `TokenUsage[]`, so integrations
+* share it rather than reimplementing aggregation.
+*/
+function aggregateTokenUsage(entries) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const key = `${entry.provider ?? ""} ${entry.model ?? ""}`;
+		let target = grouped.get(key);
+		if (!target) {
+			target = {
+				provider: entry.provider,
+				model: entry.model
+			};
+			grouped.set(key, target);
+		}
+		for (const field of COUNT_KEYS) {
+			const value = entry[field];
+			if (value == null) continue;
+			target[field] = (target[field] ?? 0) + value;
+		}
+	}
+	return [...grouped.values()];
+}
+
+//#endregion
+//#region src/content.ts
+/**
+* The text of string-or-parts content, for a consumer that can only hold a
+* string: the text parts concatenated in order, every other part dropped.
+*
+* This is the downgrade the specification permits for a peer that predates
+* content parts (/spec/1.0/basic/versioning): it removes and reshapes, and
+* it invents nothing — no placeholder stands in for a dropped image, because a
+* downgrade MUST NOT supply a value the producer never sent. Content that is
+* entirely media flattens to the empty string, which the same rule allows.
+*
+* Losing content is never meant to be silent. This helper only reshapes; a
+* caller that knows it is talking to an older peer warns as well, the way the
+* era shims in `@ag-ui/client` do.
+*/
+function contentToText(content) {
+	if (content === void 0) return "";
+	if (typeof content === "string") return content;
+	return content.filter((part) => part.type === "text").map((part) => part.text).join("");
+}
+/**
+* Whether string-or-parts content carries anything but text — the question a
+* caller asks before flattening, so it can warn about what the flattening
+* would drop.
+*/
+function contentHasMedia(content) {
+	return Array.isArray(content) && content.some((part) => part.type !== "text");
+}
+
 //#endregion
 exports.AGUIConnectNotImplementedError = AGUIConnectNotImplementedError;
 exports.AGUIError = AGUIError;
-exports.EventType = require_events.EventType;
+exports.AGUI_METADATA_KEY = AGUI_METADATA_KEY;
+exports.EventType = require_version.EventType;
+exports.PROTOCOL_VERSION = require_version.PROTOCOL_VERSION;
+exports.aggregateTokenUsage = aggregateTokenUsage;
+exports.contentHasMedia = contentHasMedia;
+exports.contentToText = contentToText;
+exports.mergeMetadata = mergeMetadata;
+exports.omitOptionalNulls = omitOptionalNulls;
+exports.tokenUsageFromAiSdkUsage = tokenUsageFromAiSdkUsage;
+exports.tokenUsageFromLangChainMetadata = tokenUsageFromLangChainMetadata;
 //# sourceMappingURL=index.js.map