@rulvar/bridge-ai-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { LanguageModelV4 } from "@ai-sdk/provider";
+import { ModelCaps, ProviderAdapter, WireError } from "@rulvar/core";
+
+//#region src/bridge.d.ts
+interface BridgeAiSdkOptions {
+  /**
+  * Adapter id (the left segment of ModelRef). Defaults to the wrapped
+  * model's `provider` string; pass an explicit id to register several
+  * bridged models of the same provider side by side.
+  */
+  id?: string;
+  /**
+  * Provider family for provider-raw retention and projection (docs/04,
+  * section 2.3). Defaults to the wrapped model's `provider` string, so
+  * two bridged models of one provider share retained blocks.
+  */
+  provider?: string;
+  /** Per-model capability overrides merged over the conservative defaults. */
+  caps?: (model: string) => ModelCaps | Partial<ModelCaps>;
+}
+/**
+* Wraps a Vercel AI SDK LanguageModelV4 as a ProviderAdapter (docs/04,
+* section 7). The bridge MUST check specificationVersion at runtime and
+* fail with a typed ConfigError on mismatch. The published interface names
+* the version V4; the wire literal carried by @ai-sdk/provider ^4 is 'v4'.
+*/
+declare function bridgeAiSdk(model: LanguageModelV4, options?: BridgeAiSdkOptions): ProviderAdapter;
+/**
+* Projects a thrown value from the wrapped model into a typed WireError.
+* APICallError carries the provider's status and headers: 429 surfaces as
+* a retryable rate-limit with retryAfterMs; 5xx and status-less network
+* failures are retryable transport; other statuses are terminal transport
+* (docs/04, section 2.2).
+*/
+declare function aiSdkErrorToWire(error: unknown): WireError;
+//#endregion
+export { type BridgeAiSdkOptions, aiSdkErrorToWire, bridgeAiSdk };

package/dist/index.js

@@ -0,0 +1,651 @@
+import { APICallError } from "@ai-sdk/provider";
+import { ConfigError, createCanonicalIdMinter } from "@rulvar/core";
+//#region src/bridge.ts
+/**
+* @rulvar/bridge-ai-sdk (M9-T01): wraps any Vercel AI SDK LanguageModelV4
+* as a ProviderAdapter for the long tail of providers (Google, Bedrock,
+* Vertex) without coupling the core to the ai-sdk release cycle.
+*
+* Owning spec: docs/04-model-layer-spec.md, section "@rulvar/bridge-ai-sdk".
+* This is documented as the highest-churn package in the set: it tracks the
+* @ai-sdk/provider major line (^4, pinned in docs/13, section "Dependency
+* baseline pins") and checks specificationVersion at runtime so a transitive
+* provider-package major cannot mis-wire silently.
+*/
+/**
+* Conservative capability set for a model the bridge cannot introspect:
+* the LanguageModelV4 interface exposes no capability discovery, so the
+* defaults mirror the openaiCompatible factory posture (docs/04, section
+* 6) except structuredOutput, where responseFormat json IS the V4-native
+* mechanism every ai-sdk provider accepts. Callers SHOULD supply caps for
+* anything beyond this.
+*/
+const CONSERVATIVE_BRIDGE_CAPS = {
+	structuredOutput: "native",
+	supportsTemperature: true,
+	supportsParallelTools: false,
+	reasoningEfforts: [],
+	contextWindow: 8192,
+	maxOutputTokens: 4096
+};
+/**
+* Canonical effort to V4 reasoning effort. Canonical 'max' has no V4
+* equivalent and downmaps to 'xhigh' (the documented lossy downmap pattern
+* of docs/04, section 3.3); the downmap is recorded in providerMetadata.
+* Identity always keeps the requested canonical effort.
+*/
+const EFFORT_TO_V4 = {
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "xhigh",
+	max: "xhigh"
+};
+/**
+* Keys of the bridge's providerOptions namespace that would contradict a
+* canonical ChatRequest field. Canonical fields always win; a namespaced
+* option silently contradicting one is a typed ConfigError (docs/04,
+* section 1.8).
+*/
+const CANONICAL_CONFLICT_KEYS = [
+	"prompt",
+	"maxOutputTokens",
+	"stopSequences",
+	"responseFormat",
+	"tools",
+	"toolChoice",
+	"reasoning",
+	"abortSignal"
+];
+/** Transport knobs the bridge lifts from its namespace into V4 call options. */
+const LIFTED_OPTION_KEYS = [
+	"temperature",
+	"topP",
+	"topK",
+	"seed",
+	"presencePenalty",
+	"frequencyPenalty",
+	"headers"
+];
+/**
+* Bijective map between engine-minted CanonicalIds and the wrapped
+* provider's wire tool-call ids (docs/04, section 1.2). V4 accepts
+* arbitrary strings as toolCallId, so a canonical id minted outside this
+* provider is used verbatim as its own wire id.
+*/
+var BridgeIdMap = class {
+	toWire = /* @__PURE__ */ new Map();
+	toCanonical = /* @__PURE__ */ new Map();
+	mint;
+	constructor(mint) {
+		this.mint = mint;
+	}
+	canonicalFor(wireId) {
+		const existing = this.toCanonical.get(wireId);
+		if (existing !== void 0) return existing;
+		const canonical = this.mint();
+		this.toCanonical.set(wireId, canonical);
+		this.toWire.set(canonical, wireId);
+		return canonical;
+	}
+	wireFor(canonicalId) {
+		const existing = this.toWire.get(canonicalId);
+		if (existing !== void 0) return existing;
+		this.toWire.set(canonicalId, canonicalId);
+		this.toCanonical.set(canonicalId, canonicalId);
+		return canonicalId;
+	}
+};
+/**
+* Wraps a Vercel AI SDK LanguageModelV4 as a ProviderAdapter (docs/04,
+* section 7). The bridge MUST check specificationVersion at runtime and
+* fail with a typed ConfigError on mismatch. The published interface names
+* the version V4; the wire literal carried by @ai-sdk/provider ^4 is 'v4'.
+*/
+function bridgeAiSdk(model, options = {}) {
+	const version = model.specificationVersion;
+	if (version !== "v4") throw new ConfigError(`bridgeAiSdk requires a LanguageModelV4 (specificationVersion 'v4'); received ${JSON.stringify(version)}. A mismatched @ai-sdk/provider major cannot be bridged (docs/04, section 7).`, { data: { received: typeof version === "string" ? version : null } });
+	const id = options.id ?? model.provider;
+	if (id === void 0 || id === "") throw new ConfigError("bridgeAiSdk requires a non-empty adapter id (model.provider was empty)");
+	const family = options.provider ?? model.provider;
+	const ids = new BridgeIdMap(createCanonicalIdMinter());
+	return {
+		id,
+		provider: family,
+		caps(wireModel) {
+			const overrides = options.caps?.(wireModel);
+			return overrides === void 0 ? CONSERVATIVE_BRIDGE_CAPS : {
+				...CONSERVATIVE_BRIDGE_CAPS,
+				...overrides
+			};
+		},
+		async *stream(req, signal) {
+			if (req.model !== model.modelId) throw new ConfigError(`bridgeAiSdk adapter '${id}' wraps model '${model.modelId}' but was asked for '${req.model}'; register one bridgeAiSdk adapter per wrapped model`);
+			const built = buildCallOptions(req, {
+				adapterId: id,
+				family,
+				ids,
+				signal
+			});
+			let result;
+			try {
+				result = await model.doStream(built.callOptions);
+			} catch (thrown) {
+				if (signal?.aborted === true) return;
+				yield {
+					type: "error",
+					error: aiSdkErrorToWire(thrown)
+				};
+				return;
+			}
+			const mapper = new StreamMapper(id, ids, built.effortDownmapped);
+			try {
+				for await (const part of iterateStream(result.stream)) {
+					for (const event of mapper.map(part)) yield event;
+					if (mapper.terminal) return;
+				}
+			} catch (thrown) {
+				if (signal?.aborted === true) return;
+				yield {
+					type: "error",
+					error: aiSdkErrorToWire(thrown)
+				};
+				return;
+			}
+			if (!mapper.terminal) yield {
+				type: "error",
+				error: {
+					code: "agent",
+					message: `bridged model '${model.modelId}' ended its stream without a finish part`,
+					retryable: true,
+					data: { kind: "transport" }
+				}
+			};
+		}
+	};
+}
+async function* iterateStream(stream) {
+	const reader = stream.getReader();
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) return;
+			yield value;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+function buildCallOptions(req, context) {
+	const callOptions = { prompt: mapMessages(req.messages, context) };
+	if (req.maxOutputTokens !== void 0) callOptions.maxOutputTokens = req.maxOutputTokens;
+	if (req.stopSequences !== void 0) callOptions.stopSequences = req.stopSequences;
+	if (req.tools !== void 0 && req.tools.length > 0) callOptions.tools = req.tools.map((tool) => ({
+		type: "function",
+		name: tool.name,
+		description: tool.description,
+		inputSchema: tool.parameters
+	}));
+	if (req.toolChoice !== void 0) callOptions.toolChoice = mapToolChoice(req.toolChoice);
+	if (req.schema !== void 0) callOptions.responseFormat = {
+		type: "json",
+		schema: req.schema
+	};
+	let effortDownmapped = false;
+	if (req.effort !== void 0) {
+		callOptions.reasoning = EFFORT_TO_V4[req.effort];
+		effortDownmapped = req.effort === "max";
+	}
+	if (context.signal !== void 0) callOptions.abortSignal = context.signal;
+	applyNamespacedOptions(req, callOptions, context.adapterId);
+	return {
+		callOptions,
+		effortDownmapped
+	};
+}
+function applyNamespacedOptions(req, callOptions, adapterId) {
+	const ns = req.providerOptions?.[adapterId];
+	if (ns === void 0) return;
+	for (const key of CANONICAL_CONFLICT_KEYS) if (key in ns) throw new ConfigError(`providerOptions.${adapterId}.${key} contradicts a canonical ChatRequest field; canonical fields always win (docs/04, section 1.8)`);
+	for (const key of LIFTED_OPTION_KEYS) if (ns[key] !== void 0) callOptions[key] = ns[key];
+	if (ns.providerOptions !== void 0) callOptions.providerOptions = ns.providerOptions;
+}
+function mapToolChoice(choice) {
+	if (choice === "auto") return { type: "auto" };
+	if (choice === "none") return { type: "none" };
+	if (choice === "required") return { type: "required" };
+	return {
+		type: "tool",
+		toolName: choice.name
+	};
+}
+function mapMessages(messages, context) {
+	const prompt = [];
+	for (const message of messages) {
+		if (message.role === "system") {
+			const text = message.parts.map((part) => part.type === "text" ? part.text : "").join("");
+			prompt.push({
+				role: "system",
+				content: text
+			});
+			continue;
+		}
+		if (message.role === "user") {
+			const content = [];
+			for (const part of message.parts) if (part.type === "text") content.push({
+				type: "text",
+				text: part.text
+			});
+			else if (part.type === "image") content.push({
+				type: "file",
+				mediaType: part.mediaType,
+				data: toFileData(part.data)
+			});
+			prompt.push({
+				role: "user",
+				content
+			});
+			continue;
+		}
+		if (message.role === "assistant") {
+			const content = [];
+			for (const part of message.parts) if (part.type === "text") content.push({
+				type: "text",
+				text: part.text
+			});
+			else if (part.type === "tool-call") content.push({
+				type: "tool-call",
+				toolCallId: context.ids.wireFor(part.id),
+				toolName: part.name,
+				input: part.args
+			});
+			else if (part.type === "provider-raw" && part.provider === context.family) {
+				const reinserted = reinsertRetained(part.block);
+				if (reinserted !== void 0) content.push(reinserted);
+			}
+			prompt.push({
+				role: "assistant",
+				content
+			});
+			continue;
+		}
+		const content = [];
+		for (const part of message.parts) if (part.type === "tool-result") content.push({
+			type: "tool-result",
+			toolCallId: context.ids.wireFor(part.id),
+			toolName: part.name,
+			output: part.isError === true ? {
+				type: "error-text",
+				value: stringifyResult(part.result)
+			} : {
+				type: "json",
+				value: part.result
+			}
+		});
+		prompt.push({
+			role: "tool",
+			content
+		});
+	}
+	return prompt;
+}
+/**
+* Transforms a retained stream part (shipped through finish
+* providerMetadata retainedParts and lifted into a provider-raw part by
+* the runtime, docs/04, section 2.3) back into its V4 prompt-part shape.
+* Response-side providerMetadata becomes prompt-side providerOptions.
+*/
+function reinsertRetained(block) {
+	if (typeof block !== "object" || block === null) return;
+	const record = block;
+	const meta = record.providerMetadata;
+	const withMeta = meta === void 0 ? {} : { providerOptions: meta };
+	switch (record.type) {
+		case "reasoning": return {
+			type: "reasoning",
+			text: record.text,
+			...withMeta
+		};
+		case "custom": return {
+			type: "custom",
+			kind: record.kind,
+			...withMeta
+		};
+		case "file": return {
+			type: "file",
+			mediaType: record.mediaType,
+			data: record.data,
+			...withMeta
+		};
+		case "reasoning-file": return {
+			type: "reasoning-file",
+			mediaType: record.mediaType,
+			data: record.data,
+			...withMeta
+		};
+		case "tool-call": return {
+			type: "tool-call",
+			toolCallId: record.toolCallId,
+			toolName: record.toolName,
+			input: record.input,
+			providerExecuted: true,
+			...withMeta
+		};
+		case "tool-result": return {
+			type: "tool-result",
+			toolCallId: record.toolCallId,
+			toolName: record.toolName,
+			output: {
+				type: "json",
+				value: record.result
+			},
+			...withMeta
+		};
+		default: return;
+	}
+}
+function toFileData(data) {
+	if (typeof data === "string" && (/^https?:/i.test(data) || data.startsWith("data:"))) return {
+		type: "url",
+		url: new URL(data)
+	};
+	return {
+		type: "data",
+		data
+	};
+}
+function stringifyResult(result) {
+	return typeof result === "string" ? result : JSON.stringify(result) ?? "null";
+}
+/**
+* Maps the V4 stream-part vocabulary onto ChatEvents, assembling tool
+* arguments, normalizing usage under the Usage invariant, and collecting
+* the turn's retention payload (reasoning parts with their signatures,
+* custom blocks, generated files, provider-executed tool exchanges) for
+* finish providerMetadata retainedParts.
+*/
+var StreamMapper = class {
+	terminal = false;
+	adapterId;
+	ids;
+	effortDownmapped;
+	toolNames = /* @__PURE__ */ new Map();
+	startedToolWireIds = /* @__PURE__ */ new Set();
+	providerExecutedWireIds = /* @__PURE__ */ new Set();
+	reasoning = /* @__PURE__ */ new Map();
+	retained = [];
+	warnings = [];
+	response;
+	constructor(adapterId, ids, effortDownmapped) {
+		this.adapterId = adapterId;
+		this.ids = ids;
+		this.effortDownmapped = effortDownmapped;
+	}
+	map(part) {
+		switch (part.type) {
+			case "stream-start":
+				this.warnings = part.warnings;
+				return [];
+			case "response-metadata": {
+				const response = {};
+				if (part.id !== void 0) response.id = part.id;
+				if (part.modelId !== void 0) response.modelId = part.modelId;
+				if (part.timestamp !== void 0) response.timestamp = part.timestamp.toISOString();
+				if (Object.keys(response).length > 0) this.response = response;
+				return [];
+			}
+			case "text-start":
+			case "text-end": return [];
+			case "text-delta": return [{
+				type: "text-delta",
+				text: part.delta
+			}];
+			case "reasoning-start":
+				this.reasoning.set(part.id, {
+					text: "",
+					...part.providerMetadata === void 0 ? {} : { providerMetadata: { ...part.providerMetadata } }
+				});
+				return [];
+			case "reasoning-delta": {
+				const acc = this.reasoning.get(part.id) ?? { text: "" };
+				acc.text += part.delta;
+				this.mergeReasoningMeta(acc, part.providerMetadata);
+				this.reasoning.set(part.id, acc);
+				return [{
+					type: "reasoning-delta",
+					text: part.delta
+				}];
+			}
+			case "reasoning-end": {
+				const acc = this.reasoning.get(part.id);
+				if (acc !== void 0) {
+					this.mergeReasoningMeta(acc, part.providerMetadata);
+					this.retained.push({
+						type: "reasoning",
+						text: acc.text,
+						...acc.providerMetadata === void 0 ? {} : { providerMetadata: acc.providerMetadata }
+					});
+					this.reasoning.delete(part.id);
+				}
+				return [];
+			}
+			case "tool-input-start":
+				if (part.providerExecuted === true) {
+					this.providerExecutedWireIds.add(part.id);
+					return [];
+				}
+				this.toolNames.set(part.id, part.toolName);
+				this.startedToolWireIds.add(part.id);
+				return [{
+					type: "tool-call-start",
+					id: this.ids.canonicalFor(part.id),
+					name: part.toolName
+				}];
+			case "tool-input-delta":
+				if (this.providerExecutedWireIds.has(part.id)) return [];
+				return [{
+					type: "tool-call-delta",
+					id: this.ids.canonicalFor(part.id),
+					argsTextDelta: part.delta
+				}];
+			case "tool-input-end": return [];
+			case "tool-call": {
+				if (part.providerExecuted === true) {
+					this.providerExecutedWireIds.add(part.toolCallId);
+					const parsed = parseToolArgs(part.input);
+					this.retained.push({
+						type: "tool-call",
+						toolCallId: part.toolCallId,
+						toolName: part.toolName,
+						input: parsed.ok ? parsed.value : part.input,
+						providerExecuted: true,
+						...part.providerMetadata === void 0 ? {} : { providerMetadata: part.providerMetadata }
+					});
+					return [];
+				}
+				const events = [];
+				const canonical = this.ids.canonicalFor(part.toolCallId);
+				if (!this.startedToolWireIds.has(part.toolCallId)) events.push({
+					type: "tool-call-start",
+					id: canonical,
+					name: part.toolName
+				});
+				const parsed = parseToolArgs(part.input);
+				if (parsed.ok) events.push({
+					type: "tool-call-end",
+					id: canonical,
+					args: parsed.value
+				});
+				else {
+					this.terminal = true;
+					events.push({
+						type: "error",
+						error: {
+							code: "agent",
+							message: `bridged tool call '${part.toolName}' carried arguments that are not valid JSON`,
+							retryable: true,
+							data: { kind: "transport" }
+						}
+					});
+				}
+				return events;
+			}
+			case "tool-result":
+				this.retained.push({
+					type: "tool-result",
+					toolCallId: part.toolCallId,
+					toolName: part.toolName,
+					result: part.result,
+					...part.isError === void 0 ? {} : { isError: part.isError },
+					...part.providerMetadata === void 0 ? {} : { providerMetadata: part.providerMetadata }
+				});
+				return [];
+			case "tool-approval-request":
+				this.terminal = true;
+				return [{
+					type: "error",
+					error: {
+						code: "agent",
+						message: "the bridged provider requested approval for a provider-executed tool call; provider-executed tool approval flows are not supported through bridgeAiSdk",
+						retryable: false,
+						data: { kind: "terminal" }
+					}
+				}];
+			case "custom":
+			case "file":
+			case "reasoning-file":
+				this.retained.push(part);
+				return [];
+			case "source":
+			case "raw": return [];
+			case "finish":
+				this.terminal = true;
+				return this.mapFinish(part);
+			case "error":
+				this.terminal = true;
+				return [{
+					type: "error",
+					error: aiSdkErrorToWire(part.error)
+				}];
+			default: return [];
+		}
+	}
+	mergeReasoningMeta(acc, meta) {
+		if (meta === void 0) return;
+		acc.providerMetadata = {
+			...acc.providerMetadata,
+			...meta
+		};
+	}
+	mapFinish(part) {
+		if (part.finishReason.unified === "error") return [{
+			type: "error",
+			error: {
+				code: "agent",
+				message: part.finishReason.raw === void 0 ? "bridged provider reported an error finish" : `bridged provider reported an error finish (${part.finishReason.raw})`,
+				retryable: true,
+				data: { kind: "transport" }
+			}
+		}];
+		const finish = mapFinishReason(part.finishReason, this.adapterId);
+		const usage = mapUsage(part.usage);
+		const bag = {};
+		if (this.retained.length > 0) bag.retainedParts = this.retained;
+		if (this.warnings.length > 0) bag.warnings = this.warnings;
+		if (this.response !== void 0) bag.response = this.response;
+		if (part.providerMetadata !== void 0) bag.upstream = part.providerMetadata;
+		if (this.effortDownmapped) bag.effortDownmap = "max->xhigh";
+		if (part.finishReason.unified === "other" && part.finishReason.raw !== void 0) bag.finishRaw = part.finishReason.raw;
+		return [{
+			type: "finish",
+			finish,
+			usage,
+			...Object.keys(bag).length === 0 ? {} : { providerMetadata: { [this.adapterId]: bag } }
+		}];
+	}
+};
+function mapFinishReason(reason, adapterId) {
+	switch (reason.unified) {
+		case "tool-calls": return { reason: "tool-calls" };
+		case "length": return { reason: "max-tokens" };
+		case "content-filter": return {
+			reason: "refusal",
+			refusal: {
+				provider: adapterId,
+				stopDetails: { type: reason.raw ?? "content-filter" }
+			}
+		};
+		default: return { reason: "stop" };
+	}
+}
+/**
+* Normalizes V4 nested usage to the flat Usage under the Usage invariant:
+* inputTokens is the FULL prompt including cache reads and writes
+* (docs/04, section 1.6). When the provider's total disagrees with the
+* component sum, the larger value wins so the invariant holds by
+* construction.
+*/
+function mapUsage(usage) {
+	const cacheRead = usage.inputTokens.cacheRead ?? 0;
+	const cacheWrite = usage.inputTokens.cacheWrite ?? 0;
+	const derivedInput = (usage.inputTokens.noCache ?? 0) + cacheRead + cacheWrite;
+	const inputTokens = Math.max(usage.inputTokens.total ?? 0, derivedInput);
+	const derivedOutput = (usage.outputTokens.text ?? 0) + (usage.outputTokens.reasoning ?? 0);
+	return {
+		inputTokens,
+		outputTokens: Math.max(usage.outputTokens.total ?? 0, derivedOutput),
+		cacheReadTokens: cacheRead,
+		cacheWriteTokens: cacheWrite,
+		...usage.outputTokens.reasoning === void 0 ? {} : { reasoningTokens: usage.outputTokens.reasoning }
+	};
+}
+function parseToolArgs(input) {
+	if (input === "") return {
+		ok: true,
+		value: {}
+	};
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(input)
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+/**
+* Projects a thrown value from the wrapped model into a typed WireError.
+* APICallError carries the provider's status and headers: 429 surfaces as
+* a retryable rate-limit with retryAfterMs; 5xx and status-less network
+* failures are retryable transport; other statuses are terminal transport
+* (docs/04, section 2.2).
+*/
+function aiSdkErrorToWire(error) {
+	const record = error;
+	const status = typeof record.statusCode === "number" ? record.statusCode : typeof record.status === "number" ? record.status : void 0;
+	const message = typeof record.message === "string" ? record.message : String(error);
+	if (status === 429) {
+		const retryAfter = record.responseHeaders?.["retry-after"];
+		return {
+			code: "agent",
+			message,
+			retryable: true,
+			data: {
+				kind: "rate-limit",
+				...retryAfter === void 0 || Number.isNaN(Number(retryAfter)) ? {} : { retryAfterMs: Number(retryAfter) * 1e3 },
+				status: 429
+			}
+		};
+	}
+	return {
+		code: "agent",
+		message,
+		retryable: APICallError.isInstance(error) ? error.isRetryable : status === void 0 || status >= 500,
+		data: {
+			kind: "transport",
+			...status === void 0 ? {} : { status }
+		}
+	};
+}
+//#endregion
+export { aiSdkErrorToWire, bridgeAiSdk };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rulvar/bridge-ai-sdk",
+  "version": "1.0.0",
+  "description": "rulvar bridge adapter wrapping any Vercel AI SDK LanguageModelV4 as a ProviderAdapter.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "^4.0.0",
+    "@rulvar/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@ai-sdk/google": "^4.0.0",
+    "@types/node": "^22.20.0",
+    "tsdown": "^0.22.3",
+    "typescript": "~6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/o-stepper/rulvar.git",
+    "directory": "packages/bridge-ai-sdk"
+  },
+  "homepage": "https://rulvar.com",
+  "bugs": {
+    "url": "https://github.com/o-stepper/rulvar/issues"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "pack-check": "publint --pack pnpm && attw --pack . --profile esm-only"
+  }
+}