adonis-ai-kit 0.0.0-stage → 1.2.0

package/dist/src/guard/types.d.ts

@@ -0,0 +1,63 @@
+export type { Logger } from '../logger.js';
+export type ToolPermission = 'allow' | 'ask' | 'deny';
+/**
+ * Structural shape of an AI SDK tool (v5+: `inputSchema`; legacy v4 tools used `parameters`).
+ * Extra keys (`outputSchema`, `providerOptions`, ...) are preserved when a tool is wrapped.
+ */
+export interface ToolDefinition<TArgs = any, TResult = any> {
+    /**
+     * Tool description. AI SDK v7 also allows a function that builds the description
+     * from the call context, so both shapes are accepted.
+     */
+    description?: string | ((options: any) => string);
+    inputSchema?: unknown;
+    /** @deprecated AI SDK v4 name of `inputSchema`. */
+    parameters?: unknown;
+    execute?: (args: TArgs, options?: any) => Promise<TResult> | TResult;
+    [key: string]: unknown;
+}
+export interface PendingAction<TParams = Record<string, unknown>> {
+    id: string;
+    sessionId?: string;
+    toolName: string;
+    action: string;
+    params: TParams;
+    createdAt: number;
+    expiresAt: number;
+    status: 'pending' | 'approved' | 'rejected' | 'timeout';
+    reason?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ConfirmationResponse {
+    status: 'approved' | 'rejected' | 'timeout';
+    reason?: string;
+}
+export interface ActionGuard {
+    /**
+     * Validates tool invocation before execution.
+     * Returns a violation error message if rejected, or null if allowed.
+     *
+     * A guard that returns `null` may reserve capacity (e.g. a call slot). Every allowed `check()`
+     * is followed by exactly one `record()` (the tool ran) or one `release()` (it did not).
+     */
+    check(toolName: string, args: unknown): string | null;
+    /**
+     * Optional callback invoked after tool execution completes to record result stats.
+     */
+    record?(toolName: string, result: unknown): void;
+    /**
+     * Optional callback invoked when a call that passed `check()` was NOT executed
+     * (confirmation denied, timed out, aborted). Lets the guard give back reserved capacity.
+     */
+    release?(toolName: string): void;
+    /**
+     * Optional summary of guard activity (e.g. accepted count, violations).
+     */
+    summary?(): Record<string, unknown>;
+}
+export interface ExecutionReconciliation {
+    claimed: number;
+    verified: number;
+    mismatch: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/guard/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/guard/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAE1C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAA;AAErD;;;GAGG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IACxD;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,MAAM,CAAC,CAAA;IACjD,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,mDAAmD;IACnD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IACpE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,aAAa,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC9D,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAA;IACvD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAAA;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;IAErD;;OAEG;IACH,MAAM,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IAEhD;;;OAGG;IACH,OAAO,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhC;;OAEG;IACH,OAAO,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACpC;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;CAClB"}

package/dist/src/guard/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/guard/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/guard/types.ts"],"names":[],"mappings":""}

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+export * from './types.js';
+export type { Logger } from './logger.js';
+export * from './errors.js';
+export * from './error_classifier.js';
+export * from './circuit_breaker.js';
+export * from './define_config.js';
+export * from './ai_manager.js';
+export * from './response_macro.js';
+export * from './catalog/index.js';
+export * from './acp/index.js';
+export * from './agents/index.js';
+export * from './guard/index.js';
+export * from './budget/index.js';
+export * from './models/index.js';
+export type { ToolPermission } from './guard/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,cAAc,aAAa,CAAA;AAC3B,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,oBAAoB,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA;AAGjC,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,14 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './error_classifier.js';
+export * from './circuit_breaker.js';
+export * from './define_config.js';
+export * from './ai_manager.js';
+export * from './response_macro.js';
+export * from './catalog/index.js';
+export * from './acp/index.js';
+export * from './agents/index.js';
+export * from './guard/index.js';
+export * from './budget/index.js';
+export * from './models/index.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAE1B,cAAc,aAAa,CAAA;AAC3B,cAAc,uBAAuB,CAAA;AACrC,cAAc,sBAAsB,CAAA;AACpC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,qBAAqB,CAAA;AACnC,cAAc,oBAAoB,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,kBAAkB,CAAA;AAChC,cAAc,mBAAmB,CAAA;AACjC,cAAc,mBAAmB,CAAA"}

package/dist/src/logger.d.ts

@@ -0,0 +1,7 @@
+export interface Logger {
+    debug?(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/src/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CACjD"}

package/dist/src/logger.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=logger.js.map

package/dist/src/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/logger.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,24 @@
+import type { AcpRuntimeOptions } from '../acp/types.js';
+import type { ModelsDevCatalog } from '../catalog/models_dev.js';
+import type { ResolvedModel } from './types.js';
+export interface ModelResolver {
+    resolve(ref?: string): Promise<ResolvedModel>;
+}
+export interface CatalogModelResolverOptions {
+    catalog: {
+        load(): Promise<ModelsDevCatalog>;
+    };
+    /** Model reference used when `resolve()` is called without one. */
+    defaultModelRef?: () => string | undefined;
+    /** Provider to use for refs that are not provider-prefixed. */
+    explicitProvider?: () => string | undefined;
+    /** Default: the first non-empty `process.env[name]`. */
+    getApiKey?: (envNames: string[]) => string | undefined;
+    acp?: AcpRuntimeOptions;
+}
+export declare class CatalogModelResolver implements ModelResolver {
+    private readonly options;
+    constructor(options: CatalogModelResolverOptions);
+    resolve(ref?: string): Promise<ResolvedModel>;
+}
+//# sourceMappingURL=catalog_resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog_resolver.d.ts","sourceRoot":"","sources":["../../../src/models/catalog_resolver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAGhE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CAC9C;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE;QAAE,IAAI,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAA;KAAE,CAAA;IAC9C,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC1C,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC3C,wDAAwD;IACxD,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,MAAM,GAAG,SAAS,CAAA;IACtD,GAAG,CAAC,EAAE,iBAAiB,CAAA;CACxB;AAYD,qBAAa,oBAAqB,YAAW,aAAa;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,2BAA2B;IAE3D,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAkDpD"}

package/dist/src/models/catalog_resolver.js

@@ -0,0 +1,66 @@
+import { buildAcpRuntimeConfig } from '../acp/acp_agents.js';
+import { parseModelRef } from './model_ref.js';
+import { resolveProviderNpm } from './protocols.js';
+const ACP_NPM = '@mcpc-tech/acp-ai-provider';
+function firstEnvValue(envNames) {
+    for (const name of envNames) {
+        const value = process.env[name];
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+export class CatalogModelResolver {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async resolve(ref) {
+        const { options } = this;
+        const catalog = await options.catalog.load();
+        const resolved = ref || options.defaultModelRef?.();
+        const explicitProvider = options.explicitProvider?.();
+        let providerID;
+        let modelID;
+        if (resolved) {
+            const parsed = parseModelRef({
+                modelRef: resolved,
+                explicitProvider,
+                knownProviderIds: Object.keys(catalog),
+            });
+            providerID = parsed.providerId;
+            modelID = parsed.modelId;
+            if (!catalog[providerID])
+                throw new Error(`Unknown provider: ${providerID}`);
+        }
+        else {
+            providerID = explicitProvider || '';
+            if (!catalog[providerID])
+                throw new Error('A model or provider is required');
+            modelID = Object.keys(catalog[providerID].models)[0];
+        }
+        const provider = catalog[providerID];
+        if (!provider.models[modelID] && resolved && provider.models[resolved]) {
+            modelID = resolved;
+        }
+        const modelInfo = provider.models[modelID];
+        const apiKey = (options.getApiKey ?? firstEnvValue)(provider.env ?? []);
+        const npm = resolveProviderNpm({ npmPackage: provider.npm, protocol: provider.protocol });
+        if (provider.protocol === 'acp') {
+            const agentId = modelID || Object.keys(provider.models)[0];
+            const acpConfig = buildAcpRuntimeConfig(agentId, options.acp);
+            if (acpConfig) {
+                return { providerID, modelID: agentId, npm: npm || ACP_NPM, acpAgentId: agentId, acpConfig };
+            }
+        }
+        return {
+            providerID,
+            modelID,
+            apiUrl: provider.api,
+            npm,
+            apiKey,
+            headers: modelInfo?.headers,
+        };
+    }
+}
+//# sourceMappingURL=catalog_resolver.js.map

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

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

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

@@ -0,0 +1,14 @@
+export type { ResolvedModel } from './types.js';
+export { parseModelRef } from './model_ref.js';
+export type { ParseModelRefOptions, ParsedModelRef } from './model_ref.js';
+export { modelKeyFor, breakerKeyFor } from './keys.js';
+export { PROTOCOL_TO_NPM, resolveProviderNpm } from './protocols.js';
+export { BUILTIN_PROVIDER_EXPORTS, ProviderFactoryRegistry } from './provider_factories.js';
+export type { ProviderFactory } from './provider_factories.js';
+export { LanguageModelFactory } from './language_model_factory.js';
+export type { LanguageModelFactoryOptions } from './language_model_factory.js';
+export { CatalogModelResolver } from './catalog_resolver.js';
+export type { CatalogModelResolverOptions, ModelResolver } from './catalog_resolver.js';
+export { buildChainCandidates, runModelChain } from './model_chain.js';
+export type { ChainAttempt, ChainCandidate, FallbackEvent, ModelChainOptions, } from './model_chain.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/models/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAC9C,YAAY,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACtD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACpE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AAC3F,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAClE,YAAY,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAA;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAC5D,YAAY,EAAE,2BAA2B,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACvF,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACtE,YAAY,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,iBAAiB,GAClB,MAAM,kBAAkB,CAAA"}

package/dist/src/models/index.js

@@ -0,0 +1,8 @@
+export { parseModelRef } from './model_ref.js';
+export { modelKeyFor, breakerKeyFor } from './keys.js';
+export { PROTOCOL_TO_NPM, resolveProviderNpm } from './protocols.js';
+export { BUILTIN_PROVIDER_EXPORTS, ProviderFactoryRegistry } from './provider_factories.js';
+export { LanguageModelFactory } from './language_model_factory.js';
+export { CatalogModelResolver } from './catalog_resolver.js';
+export { buildChainCandidates, runModelChain } from './model_chain.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/models/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAE9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACtD,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AACpE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AAE3F,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAElE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAE5D,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA"}

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

@@ -0,0 +1,9 @@
+import type { ResolvedModel } from './types.js';
+export declare function modelKeyFor(m: Pick<ResolvedModel, 'providerID' | 'modelID'>): string;
+/**
+ * Identity used for circuit-breaker lookups. Two credentials of the same
+ * provider/model are different failure domains, so a non-empty credential key
+ * wins; otherwise the plain `provider/model` key is used.
+ */
+export declare function breakerKeyFor(m: Pick<ResolvedModel, 'providerID' | 'modelID' | 'credentialKey'>): string;
+//# sourceMappingURL=keys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/models/keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,GAAG,SAAS,CAAC,GAAG,MAAM,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,GAAG,SAAS,GAAG,eAAe,CAAC,GACjE,MAAM,CAER"}

package/dist/src/models/keys.js

@@ -0,0 +1,12 @@
+export function modelKeyFor(m) {
+    return `${m.providerID}/${m.modelID}`;
+}
+/**
+ * Identity used for circuit-breaker lookups. Two credentials of the same
+ * provider/model are different failure domains, so a non-empty credential key
+ * wins; otherwise the plain `provider/model` key is used.
+ */
+export function breakerKeyFor(m) {
+    return m.credentialKey ? m.credentialKey : modelKeyFor(m);
+}
+//# sourceMappingURL=keys.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/models/keys.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,WAAW,CAAC,CAAgD;IAC1E,OAAO,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,OAAO,EAAE,CAAA;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,CAAkE;IAElE,OAAO,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAA;AAC3D,CAAC"}

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":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAE9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGlD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAA;AAkBjE,MAAM,OAAO,GAAG,4BAA4B,CAAA;AAC5C,MAAM,kBAAkB,GAAG,OAAO,CAAA;AAElC,SAAS,aAAa,CAAC,OAAgC;IACrD,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAA;IAC9B,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAA;QAC/B,MAAM,SAAS,GACb,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QACzF,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;IACzC,CAAC,CAAC,CACH,CAAA;AACH,CAAC;AAED,SAAS,UAAU,CAAC,KAAkC;IACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,YAAY,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAA;AAChG,CAAC;AAED,MAAM,OAAO,oBAAoB;IACd,SAAS,CAAyB;IAClC,SAAS,CAAQ;IACjB,MAAM,CAAS;IACf,GAAG,CAAoC;IACvC,OAAO,GAAG,IAAI,GAAG,EAAqB,CAAA;IACvD,2GAA2G;IAC1F,eAAe,GAAG,IAAI,GAAG,EAAa,CAAA;IAEvD,YAAY,UAAuC,EAAE;QACnD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,uBAAuB,EAAE,CAAA;QACnE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAA;QACxD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAA;QAC5B,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAA;IACxB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAoB;QAC/B,IAAI,KAAK,CAAC,GAAG,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;QAEvD,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;YACf,MAAM,IAAI,mBAAmB,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAA;QACrG,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;QAEnD,IAAI,CAAC,MAAM,EAAE,IAAI,CACf,mCAAmC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,OAAO,SAAS,KAAK,CAAC,GAAG,GAAG,CAC1F,CAAA;QACD,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,4BAA4B,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;QAC7D,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,2BAA2B,IAAI,CAAC,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;QAE5F,OAAO,OAAO,CAAC;YACb,IAAI,EAAE,KAAK,CAAC,UAAU;YACtB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,KAAK,CAAC,MAAM;YACrB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE;SACjC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IACjC,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,QAAQ;QACZ,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,eAAe,CAAC,CAAA;QACnE,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACpB,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAA;QAC5B,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAA;IAC/D,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,KAAoB;QAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAA;QAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,mBAAmB,CAC3B,KAAK,CAAC,UAAU,EAChB,cAAc,KAAK,CAAC,OAAO,mEAAmE,CAC/F,CAAA;QACH,CAAC;QAED,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,OAAO,CAAA;QACjD,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,yCAAyC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;QAC/F,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,+BAA+B,OAAO,CAAC,OAAO,UAAU,OAAO,CAAC,GAAG,GAAG,CAAC,CAAA;QAEzF,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,GAAG,EAAE,CAAA;QAChD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,WAAW,KAAK,KAAK,CAAA;QAC9C,IAAI,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QACvD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,IAAI,SAAS,CACpB,KAAK,CAAC,UAAU,EAChB;gBACE,MAAM,EAAE,KAAK;gBACb,OAAO;gBACP,gBAAgB,EAAE,IAAI,CAAC,GAAG,EAAE,gBAAgB,IAAI,KAAK;gBACrD,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,IAAI,KAAK;aAC1C,EACD,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,CACvE,CAAA;YACD,IAAI,MAAM;gBAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;QAC3C,CAAC;QACD,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;QACpD,OAAO,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACjF,CAAC;IAED;;;;OAIG;IACK,mBAAmB,CAAC,MAAiB,EAAE,KAAoB;QACjE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAA;QAC7D,IAAI,QAAQ,GAAG,CAAC,CAAA;QAChB,MAAM,KAAK,GAAG,GAAG,EAAE;YACjB,QAAQ,EAAE,CAAA;YACV,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAClC,CAAC,CAAA;QACD,gGAAgG;QAChG,gGAAgG;QAChG,yDAAyD;QACzD,MAAM,GAAG,GAAG,GAAG,EAAE;YACf,IAAI,EAAE,QAAQ,GAAG,CAAC;gBAAE,OAAM;YAC1B,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACrC,CAAC,CAAA;QAED,OAAO,IAAI,KAAK,CAAC,KAAe,EAAE;YAChC,GAAG,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;gBACpB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;gBAC/C,IAAI,IAAI,KAAK,YAAY,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;oBACzD,OAAO,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;wBAClC,KAAK,EAAE,CAAA;wBACP,IAAI,CAAC;4BACH,OAAO,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;wBACxC,CAAC;gCAAS,CAAC;4BACT,GAAG,EAAE,CAAA;wBACP,CAAC;oBACH,CAAC,CAAA;gBACH,CAAC;gBACD,IAAI,IAAI,KAAK,UAAU,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;oBACvD,OAAO,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;wBAClC,KAAK,EAAE,CAAA;wBACP,IAAI,MAAkC,CAAA;wBACtC,IAAI,CAAC;4BACH,MAAM,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;wBAC1C,CAAC;wBAAC,OAAO,GAAG,EAAE,CAAC;4BACb,GAAG,EAAE,CAAA;4BACL,MAAM,GAAG,CAAA;wBACX,CAAC;wBACD,OAAO,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAA;oBAChE,CAAC,CAAA;gBACH,CAAC;gBACD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;YACjE,CAAC;SACF,CAAkB,CAAA;IACrB,CAAC;IAED,6FAA6F;IACrF,OAAO,CAAI,MAAyB,EAAE,IAAgB;QAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAA;QACjC,IAAI,QAAQ,GAAG,KAAK,CAAA;QACpB,MAAM,MAAM,GAAG,GAAG,EAAE;YAClB,IAAI,QAAQ;gBAAE,OAAM;YACpB,QAAQ,GAAG,IAAI,CAAA;YACf,IAAI,EAAE,CAAA;QACR,CAAC,CAAA;QACD,OAAO,IAAI,cAAc,CAAI;YAC3B,KAAK,CAAC,IAAI,CAAC,UAAU;gBACnB,IAAI,CAAC;oBACH,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;oBACjC,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;wBACf,MAAM,EAAE,CAAA;wBACR,UAAU,CAAC,KAAK,EAAE,CAAA;oBACpB,CAAC;yBAAM,CAAC;wBACN,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;oBACjC,CAAC;gBACH,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,EAAE,CAAA;oBACR,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;gBACvB,CAAC;YACH,CAAC;YACD,KAAK,CAAC,MAAM,CAAC,MAAM;gBACjB,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBAC7B,CAAC;wBAAS,CAAC;oBACT,MAAM,EAAE,CAAA;gBACV,CAAC;YACH,CAAC;SACF,CAAC,CAAA;IACJ,CAAC;IAEO,kBAAkB;QACxB,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;QAClC,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAC3B,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;YAC3C,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,MAAM,CAAA;YACrC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;YAC1B,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;YAC9C,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;YAE/E,MAAM,EAAE,KAAK,EAAE,CAAC,cAAc,MAAM,IAAI,GAAG,cAAc,SAAS,IAAI,CAAC,CAAA;YACvE,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC,CAAA;gBACxD,MAAM,EAAE,KAAK,EAAE,CAAC,cAAc,QAAQ,CAAC,MAAM,IAAI,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,IAAI,CAAC,CAAA;gBAC7F,OAAO,QAAQ,CAAA;YACjB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBAC5D,MAAM,EAAE,KAAK,CAAC,qBAAqB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,QAAQ,GAAG,EAAE,CAAC,CAAA;gBACxF,MAAM,GAAG,CAAA;YACX,CAAC;QACH,CAAC,CAAA;IACH,CAAC;CACF"}

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"}