adonis-ai-kit 1.1.0 → 1.2.0

package/dist/src/models/language_model_factory.d.ts

@@ -0,0 +1,44 @@
+import type { LanguageModel } from 'ai';
+import type { AcpPermissionPolicy } from '../acp/types.js';
+import type { ConfirmationService } from '../guard/confirmation.js';
+import type { Logger } from '../logger.js';
+import { ProviderFactoryRegistry } from './provider_factories.js';
+import type { ResolvedModel } from './types.js';
+export interface LanguageModelFactoryOptions {
+    factories?: ProviderFactoryRegistry;
+    /** Per-request fetch timeout. Default: 180_000 */
+    timeoutMs?: number;
+    logger?: Logger;
+    acp?: {
+        permissionPolicy?: AcpPermissionPolicy;
+        confirmation?: ConfirmationService;
+        /** Pass the full server environment to agent processes. Default: false (allowlisted variables only). */
+        inheritEnv?: boolean;
+        /** Reuse one driver (and agent process) per command and cwd. Default: true. */
+        shareDriver?: boolean;
+    };
+}
+export declare class LanguageModelFactory {
+    private readonly factories;
+    private readonly timeoutMs;
+    private readonly logger?;
+    private readonly acp;
+    private readonly drivers;
+    /** Unshared drivers with a call in flight; tracked so `shutdown()` can stop them. Emptied as calls end. */
+    private readonly unsharedDrivers;
+    constructor(options?: LanguageModelFactoryOptions);
+    create(model: ResolvedModel): Promise<LanguageModel>;
+    /** Stops every ACP agent process started by this factory. */
+    shutdown(): Promise<void>;
+    private createAcp;
+    /**
+     * Wraps a per-call model so its driver is tracked only while a call is in flight (so shutdown()
+     * can stop it) and released when the last call ends (result, error, stream end or cancel). A model
+     * that is never called is not tracked, so it is collected together with its driver.
+     */
+    private releaseWhenCallEnds;
+    /** Re-exposes a stream, calling `done` exactly once when it ends, errors or is cancelled. */
+    private endWith;
+    private createTimeoutFetch;
+}
+//# sourceMappingURL=language_model_factory.d.ts.map

package/dist/src/models/language_model_factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language_model_factory.d.ts","sourceRoot":"","sources":["../../../src/models/language_model_factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAA;AAEvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAE1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,MAAM,WAAW,2BAA2B;IAC1C,SAAS,CAAC,EAAE,uBAAuB,CAAA;IACnC,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE;QACJ,gBAAgB,CAAC,EAAE,mBAAmB,CAAA;QACtC,YAAY,CAAC,EAAE,mBAAmB,CAAA;QAClC,wGAAwG;QACxG,UAAU,CAAC,EAAE,OAAO,CAAA;QACpB,+EAA+E;QAC/E,WAAW,CAAC,EAAE,OAAO,CAAA;KACtB,CAAA;CACF;AAqBD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoC;IACxD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IACvD,2GAA2G;IAC3G,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;gBAE3C,OAAO,GAAE,2BAAgC;IAO/C,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAuB1D,6DAA6D;IACvD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;YAOjB,SAAS;IAiCvB;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IA8C3B,6FAA6F;IAC7F,OAAO,CAAC,OAAO;IAiCf,OAAO,CAAC,kBAAkB;CAqB3B"}

package/dist/src/models/language_model_factory.js

@@ -0,0 +1,193 @@
+import { AcpDriver } from '../acp/provider.js';
+import { ProviderConfigError } from '../errors.js';
+import { ProviderFactoryRegistry } from './provider_factories.js';
+const ACP_NPM = '@mcpc-tech/acp-ai-provider';
+const DEFAULT_TIMEOUT_MS = 180_000;
+function redactHeaders(headers) {
+    if (!headers)
+        return undefined;
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => {
+        const lower = key.toLowerCase();
+        const sensitive = lower.includes('authorization') || lower.includes('api-key') || lower.includes('x-api');
+        return [key, sensitive ? '***' : value];
+    }));
+}
+function requestUrl(input) {
+    return typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+}
+export class LanguageModelFactory {
+    factories;
+    timeoutMs;
+    logger;
+    acp;
+    drivers = new Map();
+    /** Unshared drivers with a call in flight; tracked so `shutdown()` can stop them. Emptied as calls end. */
+    unsharedDrivers = new Set();
+    constructor(options = {}) {
+        this.factories = options.factories ?? new ProviderFactoryRegistry();
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.logger = options.logger;
+        this.acp = options.acp;
+    }
+    async create(model) {
+        if (model.npm === ACP_NPM)
+            return this.createAcp(model);
+        if (!model.npm) {
+            throw new ProviderConfigError(model.providerID, `Model "${model.modelID}" has no provider package`);
+        }
+        const factory = await this.factories.get(model.npm);
+        this.logger?.info(`[LLM Provider] Creating SDK for ${model.providerID}/${model.modelID} (npm=${model.npm})`);
+        this.logger?.info(`[LLM Provider] Base URL: ${model.apiUrl}`);
+        this.logger?.info(`[LLM Provider] Headers: ${JSON.stringify(redactHeaders(model.headers))}`);
+        return factory({
+            name: model.providerID,
+            apiKey: model.apiKey,
+            baseURL: model.apiUrl,
+            headers: model.headers,
+            fetch: this.createTimeoutFetch(),
+        }).languageModel(model.modelID);
+    }
+    /** Stops every ACP agent process started by this factory. */
+    async shutdown() {
+        const drivers = [...this.drivers.values(), ...this.unsharedDrivers];
+        this.drivers.clear();
+        this.unsharedDrivers.clear();
+        await Promise.all(drivers.map((driver) => driver.shutdown()));
+    }
+    async createAcp(model) {
+        const runtime = model.acpConfig;
+        if (!runtime) {
+            throw new ProviderConfigError(model.providerID, `ACP model "${model.modelID}" requires runtime config (resolve it with buildAcpRuntimeConfig)`);
+        }
+        const agentId = model.acpAgentId ?? model.modelID;
+        this.logger?.info(`[LLM Provider] Creating ACP agent for ${model.providerID}/${model.modelID}`);
+        this.logger?.info(`[LLM Provider] ACP command: ${runtime.command} (cwd: ${runtime.cwd})`);
+        const key = `${runtime.command}::${runtime.cwd}`;
+        const shared = this.acp?.shareDriver !== false;
+        let driver = shared ? this.drivers.get(key) : undefined;
+        if (!driver) {
+            driver = new AcpDriver(model.providerID, {
+                driver: 'acp',
+                agentId,
+                permissionPolicy: this.acp?.permissionPolicy ?? 'ask',
+                inheritEnv: this.acp?.inheritEnv ?? false,
+            }, { logger: this.logger, confirmation: this.acp?.confirmation, runtime });
+            if (shared)
+                this.drivers.set(key, driver);
+        }
+        const languageModel = await driver.getModel(agentId);
+        return shared ? languageModel : this.releaseWhenCallEnds(driver, languageModel);
+    }
+    /**
+     * Wraps a per-call model so its driver is tracked only while a call is in flight (so shutdown()
+     * can stop it) and released when the last call ends (result, error, stream end or cancel). A model
+     * that is never called is not tracked, so it is collected together with its driver.
+     */
+    releaseWhenCallEnds(driver, model) {
+        if (typeof model !== 'object' || model === null)
+            return model;
+        let inFlight = 0;
+        const begin = () => {
+            inFlight++;
+            this.unsharedDrivers.add(driver);
+        };
+        // The ACP model cleans up its own agent process at the end of each turn. The driver is not shut
+        // down here: that would drop its provider, and a later step of the same call would then start a
+        // process that factory.shutdown() could no longer reach.
+        const end = () => {
+            if (--inFlight > 0)
+                return;
+            this.unsharedDrivers.delete(driver);
+        };
+        return new Proxy(model, {
+            get: (target, prop) => {
+                const value = Reflect.get(target, prop, target);
+                if (prop === 'doGenerate' && typeof value === 'function') {
+                    return async (...args) => {
+                        begin();
+                        try {
+                            return await value.apply(target, args);
+                        }
+                        finally {
+                            end();
+                        }
+                    };
+                }
+                if (prop === 'doStream' && typeof value === 'function') {
+                    return async (...args) => {
+                        begin();
+                        let result;
+                        try {
+                            result = await value.apply(target, args);
+                        }
+                        catch (err) {
+                            end();
+                            throw err;
+                        }
+                        return { ...result, stream: this.endWith(result.stream, end) };
+                    };
+                }
+                return typeof value === 'function' ? value.bind(target) : value;
+            },
+        });
+    }
+    /** Re-exposes a stream, calling `done` exactly once when it ends, errors or is cancelled. */
+    endWith(source, done) {
+        const reader = source.getReader();
+        let finished = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            done();
+        };
+        return new ReadableStream({
+            async pull(controller) {
+                try {
+                    const chunk = await reader.read();
+                    if (chunk.done) {
+                        finish();
+                        controller.close();
+                    }
+                    else {
+                        controller.enqueue(chunk.value);
+                    }
+                }
+                catch (err) {
+                    finish();
+                    controller.error(err);
+                }
+            },
+            async cancel(reason) {
+                try {
+                    await reader.cancel(reason);
+                }
+                finally {
+                    finish();
+                }
+            },
+        });
+    }
+    createTimeoutFetch() {
+        const { timeoutMs, logger } = this;
+        return async (input, init) => {
+            const url = requestUrl(input).slice(0, 120);
+            const method = init?.method || 'POST';
+            const startMs = Date.now();
+            const timeout = AbortSignal.timeout(timeoutMs);
+            const signal = init?.signal ? AbortSignal.any([timeout, init.signal]) : timeout;
+            logger?.debug?.(`[LLM HTTP] ${method} ${url} | timeout=${timeoutMs}ms`);
+            try {
+                const response = await fetch(input, { ...init, signal });
+                logger?.debug?.(`[LLM HTTP] ${response.status} ${method} ${url} | ${Date.now() - startMs}ms`);
+                return response;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger?.error(`[LLM HTTP] FAILED ${method} ${url} | ${Date.now() - startMs}ms | ${msg}`);
+                throw err;
+            }
+        };
+    }
+}
+//# sourceMappingURL=language_model_factory.js.map

package/dist/src/models/language_model_factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"language_model_factory.js","sourceRoot":"","sources":["../../../src/models/language_model_factory.ts"],"names":[],"mappings":"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"}

package/dist/src/models/model_chain.d.ts

@@ -0,0 +1,58 @@
+import type { CircuitBreaker } from '../circuit_breaker.js';
+import { type ErrorClass } from '../error_classifier.js';
+import type { Logger } from '../logger.js';
+import type { ModelResolver } from './catalog_resolver.js';
+import type { ResolvedModel } from './types.js';
+export type ChainCandidate = {
+    kind: 'resolved';
+    model: ResolvedModel;
+    key: string;
+} | {
+    kind: 'ref';
+    ref: string;
+    key: string;
+};
+/**
+ * Builds the ordered candidate list. A non-empty `chain` is authoritative: it already encodes the
+ * caller's chosen order, so `primary` and `defaults` are not appended (falling through to a model
+ * nobody picked would trade a visible failure for a silent one). An empty chain counts as absent.
+ */
+export declare function buildChainCandidates(input: {
+    chain?: ResolvedModel[];
+    primary?: ResolvedModel | string;
+    defaults?: string[];
+}): ChainCandidate[];
+export interface FallbackEvent {
+    fromModel: string;
+    toModel: string;
+    error: unknown;
+    errorClass: ErrorClass;
+}
+export interface ChainAttempt {
+    model: ResolvedModel;
+    key: string;
+    isFallback: boolean;
+    /** Call once a tool has run: the chain will not fall back after that, so side effects are not repeated. */
+    markToolsExecuted(): void;
+}
+export interface ModelChainOptions {
+    breaker?: CircuitBreaker;
+    /** Required when a candidate is a `ref`. */
+    resolver?: ModelResolver;
+    abortSignal?: AbortSignal;
+    /** Exceptions thrown or rejected by the handler are swallowed (logged as a warning); it is not awaited. */
+    onFallback?: (event: FallbackEvent) => unknown;
+    logger?: Logger;
+}
+/**
+ * Runs `attempt` against each candidate in order until one succeeds. Each candidate is guarded by a
+ * per-credential circuit breaker; a retryable failure, or a candidate that cannot be attempted (missing provider
+ * package, config error, open breaker), moves on to the next candidate; anything else, any failure after tools ran
+ * and any caller abort is thrown. An exhausted chain rethrows the last error.
+ */
+export declare function runModelChain<T>(candidates: ChainCandidate[], attempt: (a: ChainAttempt) => Promise<T>, options?: ModelChainOptions): Promise<{
+    result: T;
+    model: ResolvedModel;
+    key: string;
+}>;
+//# sourceMappingURL=model_chain.d.ts.map

package/dist/src/models/model_chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model_chain.d.ts","sourceRoot":"","sources":["../../../src/models/model_chain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC1E,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAEvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7C;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,KAAK,CAAC,EAAE,aAAa,EAAE,CAAA;IACvB,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB,GAAG,cAAc,EAAE,CAoCnB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,EAAE,UAAU,CAAA;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,aAAa,CAAA;IACpB,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,OAAO,CAAA;IACnB,2GAA2G;IAC3G,iBAAiB,IAAI,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,2GAA2G;IAC3G,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAA;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,UAAU,EAAE,cAAc,EAAE,EAC5B,OAAO,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,CAAC,CAAC,EACxC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CA4F3D"}

package/dist/src/models/model_chain.js

@@ -0,0 +1,144 @@
+import { classifyError } from '../error_classifier.js';
+import { ProviderConfigError, ProviderUnavailableError } from '../errors.js';
+import { breakerKeyFor, modelKeyFor } from './keys.js';
+/**
+ * Builds the ordered candidate list. A non-empty `chain` is authoritative: it already encodes the
+ * caller's chosen order, so `primary` and `defaults` are not appended (falling through to a model
+ * nobody picked would trade a visible failure for a silent one). An empty chain counts as absent.
+ */
+export function buildChainCandidates(input) {
+    const candidates = [];
+    if (input.chain && input.chain.length > 0) {
+        // De-duplicate on ENTRY identity, not breaker identity: one credential legitimately appears
+        // once per model it serves, and those entries share a breaker (the credential is the failure domain).
+        const seenEntries = new Set();
+        for (const model of input.chain) {
+            const key = breakerKeyFor(model);
+            const entryId = `${key}|${modelKeyFor(model)}`;
+            if (seenEntries.has(entryId))
+                continue;
+            seenEntries.add(entryId);
+            candidates.push({ kind: 'resolved', model, key });
+        }
+        return candidates;
+    }
+    const seenKeys = new Set();
+    if (typeof input.primary === 'string') {
+        if (input.primary) {
+            candidates.push({ kind: 'ref', ref: input.primary, key: input.primary });
+            seenKeys.add(input.primary);
+        }
+    }
+    else if (input.primary) {
+        const key = breakerKeyFor(input.primary);
+        candidates.push({ kind: 'resolved', model: input.primary, key });
+        seenKeys.add(key);
+    }
+    for (const ref of input.defaults ?? []) {
+        if (!ref || seenKeys.has(ref))
+            continue;
+        candidates.push({ kind: 'ref', ref, key: ref });
+        seenKeys.add(ref);
+    }
+    return candidates;
+}
+/**
+ * Runs `attempt` against each candidate in order until one succeeds. Each candidate is guarded by a
+ * per-credential circuit breaker; a retryable failure, or a candidate that cannot be attempted (missing provider
+ * package, config error, open breaker), moves on to the next candidate; anything else, any failure after tools ran
+ * and any caller abort is thrown. An exhausted chain rethrows the last error.
+ */
+export async function runModelChain(candidates, attempt, options = {}) {
+    const { breaker, resolver, abortSignal, logger } = options;
+    const unresolved = candidates.find((c) => c.kind === 'ref');
+    if (unresolved && !resolver) {
+        throw new ProviderConfigError('model-chain', `a resolver is required to resolve "${unresolved.ref}"`);
+    }
+    let lastError;
+    let hasError = false;
+    let attempted = 0;
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        // Acquired synchronously, before the first await of this attempt, so concurrent callers
+        // cannot both claim the same half-open probe slot.
+        let permit = null;
+        if (breaker) {
+            permit = breaker.acquire(candidate.key);
+            if (!permit) {
+                logger?.warn(`[model-chain] circuit breaker is not accepting calls for ${candidate.key}, skipping`);
+                continue;
+            }
+        }
+        try {
+            let model;
+            if (candidate.kind === 'resolved') {
+                model = candidate.model;
+            }
+            else {
+                model = await resolver.resolve(candidate.ref);
+            }
+            attempted++;
+            let toolsExecuted = false;
+            try {
+                const result = await attempt({
+                    model,
+                    key: candidate.key,
+                    isFallback: attempted > 1,
+                    markToolsExecuted: () => {
+                        toolsExecuted = true;
+                    },
+                });
+                permit?.success();
+                return { result, model, key: candidate.key };
+            }
+            catch (error) {
+                lastError = error;
+                hasError = true;
+                const classification = classifyError(error, abortSignal);
+                if (classification.countsAsFailure)
+                    permit?.failure(error);
+                else
+                    permit?.release();
+                const next = nextAvailable(candidates, i + 1, breaker);
+                const canFallBack = classification.kind === 'retryable' || classification.kind === 'skip';
+                if (!canFallBack || toolsExecuted || !next) {
+                    logger?.warn(`[model-chain] ${candidate.key} failed with ${classification.errorClass}; not falling back ` +
+                        `(kind=${classification.kind}, toolsExecuted=${toolsExecuted}, hasNext=${Boolean(next)})`);
+                    throw error;
+                }
+                logger?.warn(`[model-chain] ${candidate.key} failed with ${classification.errorClass}; falling back to ${next.key}`);
+                try {
+                    const pending = options.onFallback?.({
+                        fromModel: candidate.key,
+                        toModel: next.key,
+                        error,
+                        errorClass: classification.errorClass,
+                    });
+                    if (pending && typeof pending.then === 'function') {
+                        Promise.resolve(pending).catch((handlerError) => {
+                            logger?.warn(`[model-chain] onFallback handler rejected: ${String(handlerError)}`);
+                        });
+                    }
+                }
+                catch (handlerError) {
+                    logger?.warn(`[model-chain] onFallback handler threw: ${String(handlerError)}`);
+                }
+            }
+        }
+        finally {
+            // Safety net for every exit path; a no-op once the permit has been settled.
+            permit?.release();
+        }
+    }
+    if (hasError)
+        throw lastError;
+    throw new ProviderUnavailableError('model-chain', 'no candidate model is available');
+}
+function nextAvailable(candidates, from, breaker) {
+    for (let i = from; i < candidates.length; i++) {
+        if (!breaker || breaker.isAvailable(candidates[i].key))
+            return candidates[i];
+    }
+    return null;
+}
+//# sourceMappingURL=model_chain.js.map

package/dist/src/models/model_chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model_chain.js","sourceRoot":"","sources":["../../../src/models/model_chain.ts"],"names":[],"mappings":"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"}

package/dist/src/models/model_ref.d.ts

@@ -0,0 +1,12 @@
+export interface ParseModelRefOptions {
+    modelRef?: string;
+    explicitProvider?: string;
+    knownProviderIds: string[];
+}
+export interface ParsedModelRef {
+    providerId: string;
+    modelId: string;
+    wasProviderPrefixed: boolean;
+}
+export declare function parseModelRef({ modelRef, explicitProvider, knownProviderIds, }: ParseModelRefOptions): ParsedModelRef;
+//# sourceMappingURL=model_ref.d.ts.map

package/dist/src/models/model_ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model_ref.d.ts","sourceRoot":"","sources":["../../../src/models/model_ref.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,mBAAmB,EAAE,OAAO,CAAA;CAC7B;AAED,wBAAgB,aAAa,CAAC,EAC5B,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,GACjB,EAAE,oBAAoB,GAAG,cAAc,CAsCvC"}

package/dist/src/models/model_ref.js

@@ -0,0 +1,33 @@
+export function parseModelRef({ modelRef, explicitProvider, knownProviderIds, }) {
+    const ref = modelRef?.trim();
+    const provider = explicitProvider?.trim();
+    if (provider) {
+        if (!knownProviderIds.includes(provider)) {
+            throw new Error(`Unknown provider: ${provider}`);
+        }
+        const providerPrefix = `${provider}/`;
+        if (ref?.startsWith(providerPrefix)) {
+            return {
+                providerId: provider,
+                modelId: ref.slice(providerPrefix.length),
+                wasProviderPrefixed: true,
+            };
+        }
+        if (ref) {
+            return { providerId: provider, modelId: ref, wasProviderPrefixed: false };
+        }
+    }
+    if (!ref) {
+        throw new Error('A model reference or an explicit provider is required');
+    }
+    const [candidateProvider, ...modelParts] = ref.split('/');
+    if (!candidateProvider || !knownProviderIds.includes(candidateProvider)) {
+        throw new Error(`Unknown provider: ${candidateProvider || ref}`);
+    }
+    const modelId = modelParts.join('/');
+    if (!modelId) {
+        throw new Error(`Model id is required for provider: ${candidateProvider}`);
+    }
+    return { providerId: candidateProvider, modelId, wasProviderPrefixed: true };
+}
+//# sourceMappingURL=model_ref.js.map

package/dist/src/models/model_ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model_ref.js","sourceRoot":"","sources":["../../../src/models/model_ref.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,aAAa,CAAC,EAC5B,QAAQ,EACR,gBAAgB,EAChB,gBAAgB,GACK;IACrB,MAAM,GAAG,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAA;IAC5B,MAAM,QAAQ,GAAG,gBAAgB,EAAE,IAAI,EAAE,CAAA;IAEzC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAA;QAClD,CAAC;QAED,MAAM,cAAc,GAAG,GAAG,QAAQ,GAAG,CAAA;QACrC,IAAI,GAAG,EAAE,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;YACpC,OAAO;gBACL,UAAU,EAAE,QAAQ;gBACpB,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC;gBACzC,mBAAmB,EAAE,IAAI;aAC1B,CAAA;QACH,CAAC;QAED,IAAI,GAAG,EAAE,CAAC;YACR,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,mBAAmB,EAAE,KAAK,EAAE,CAAA;QAC3E,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAA;IAC1E,CAAC;IAED,MAAM,CAAC,iBAAiB,EAAE,GAAG,UAAU,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACzD,IAAI,CAAC,iBAAiB,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CAAC,qBAAqB,iBAAiB,IAAI,GAAG,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACpC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,sCAAsC,iBAAiB,EAAE,CAAC,CAAA;IAC5E,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAA;AAC9E,CAAC"}

package/dist/src/models/protocols.d.ts

@@ -0,0 +1,6 @@
+export declare const PROTOCOL_TO_NPM: Readonly<Record<string, string>>;
+export declare function resolveProviderNpm(config: {
+    npmPackage?: string | null;
+    protocol?: string | null;
+}): string;
+//# sourceMappingURL=protocols.d.ts.map

package/dist/src/models/protocols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.d.ts","sourceRoot":"","sources":["../../../src/models/protocols.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAuB5D,CAAA;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB,GAAG,MAAM,CAOT"}

package/dist/src/models/protocols.js

@@ -0,0 +1,33 @@
+export const PROTOCOL_TO_NPM = {
+    'openai': '@ai-sdk/openai',
+    'anthropic': '@ai-sdk/anthropic',
+    'openai-compatible': '@ai-sdk/openai-compatible',
+    'openrouter': '@openrouter/ai-sdk-provider',
+    'google': '@ai-sdk/google',
+    'vertex': '@ai-sdk/google-vertex',
+    'vertex-anthropic': '@ai-sdk/google-vertex/anthropic',
+    'azure': '@ai-sdk/azure',
+    'groq': '@ai-sdk/groq',
+    'mistral': '@ai-sdk/mistral',
+    'cerebras': '@ai-sdk/cerebras',
+    'deepinfra': '@ai-sdk/deepinfra',
+    'togetherai': '@ai-sdk/togetherai',
+    'cohere': '@ai-sdk/cohere',
+    'xai': '@ai-sdk/xai',
+    'perplexity': '@ai-sdk/perplexity',
+    'bedrock': '@ai-sdk/amazon-bedrock',
+    'gateway': '@ai-sdk/gateway',
+    'vercel': '@ai-sdk/vercel',
+    'gitlab': '@gitlab/gitlab-ai-provider',
+    'qwencode': '@ai-sdk/openai-compatible',
+    'acp': '@mcpc-tech/acp-ai-provider',
+};
+export function resolveProviderNpm(config) {
+    if (config.npmPackage)
+        return config.npmPackage;
+    const npm = config.protocol ? PROTOCOL_TO_NPM[config.protocol] : undefined;
+    if (npm)
+        return npm;
+    throw new Error(`Unsupported provider protocol: ${config.protocol || 'unknown'}`);
+}
+//# sourceMappingURL=protocols.js.map

package/dist/src/models/protocols.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.js","sourceRoot":"","sources":["../../../src/models/protocols.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAqC;IAC/D,QAAQ,EAAE,gBAAgB;IAC1B,WAAW,EAAE,mBAAmB;IAChC,mBAAmB,EAAE,2BAA2B;IAChD,YAAY,EAAE,6BAA6B;IAC3C,QAAQ,EAAE,gBAAgB;IAC1B,QAAQ,EAAE,uBAAuB;IACjC,kBAAkB,EAAE,iCAAiC;IACrD,OAAO,EAAE,eAAe;IACxB,MAAM,EAAE,cAAc;IACtB,SAAS,EAAE,iBAAiB;IAC5B,UAAU,EAAE,kBAAkB;IAC9B,WAAW,EAAE,mBAAmB;IAChC,YAAY,EAAE,oBAAoB;IAClC,QAAQ,EAAE,gBAAgB;IAC1B,KAAK,EAAE,aAAa;IACpB,YAAY,EAAE,oBAAoB;IAClC,SAAS,EAAE,wBAAwB;IACnC,SAAS,EAAE,iBAAiB;IAC5B,QAAQ,EAAE,gBAAgB;IAC1B,QAAQ,EAAE,4BAA4B;IACtC,UAAU,EAAE,2BAA2B;IACvC,KAAK,EAAE,4BAA4B;CACpC,CAAA;AAED,MAAM,UAAU,kBAAkB,CAAC,MAGlC;IACC,IAAI,MAAM,CAAC,UAAU;QAAE,OAAO,MAAM,CAAC,UAAU,CAAA;IAE/C,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1E,IAAI,GAAG;QAAE,OAAO,GAAG,CAAA;IAEnB,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,CAAC,QAAQ,IAAI,SAAS,EAAE,CAAC,CAAA;AACnF,CAAC"}

package/dist/src/models/provider_factories.d.ts

@@ -0,0 +1,19 @@
+import type { LanguageModel } from 'ai';
+export type ProviderFactory = (settings: {
+    name: string;
+    apiKey?: string;
+    baseURL?: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+}) => {
+    languageModel(modelId: string): LanguageModel;
+};
+/** npm package (or alias) → name of its provider-factory export. */
+export declare const BUILTIN_PROVIDER_EXPORTS: Readonly<Record<string, string>>;
+export declare class ProviderFactoryRegistry {
+    #private;
+    register(npm: string, factory: ProviderFactory): this;
+    has(npm: string): boolean;
+    get(npm: string): Promise<ProviderFactory>;
+}
+//# sourceMappingURL=provider_factories.d.ts.map

package/dist/src/models/provider_factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider_factories.d.ts","sourceRoot":"","sources":["../../../src/models/provider_factories.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAA;AAGvC,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB,KAAK;IAAE,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAAA;CAAE,CAAA;AAEvD,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAsBrE,CAAA;AAOD,qBAAa,uBAAuB;;IAGlC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAKrD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAInB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CAiCjD"}