@henjicc/ai-sdk 0.2.8

package/dist/llm/modules/client.js

@@ -0,0 +1,365 @@
+import { AiRuntimeError, cancelledError } from '../../runtime/AiRuntimeError.js';
+import { resolveRuntimeContext } from '../../runtime/RuntimeContext.js';
+import { normalizeCapabilityStableId } from '../../capabilities/validation.js';
+import { countLlmInputChars } from '../message-metrics.js';
+import { validateDiscoveredModels, validateLlmModuleOutput, validateLlmModuleStreamEvent, } from './result-validation.js';
+import { describeLlmModuleCoordinate, describeLlmModuleSource, llmModuleCoordinate, snapshotLlmModuleDescriptor, } from './validation.js';
+export function createLlmModuleClient(config) {
+    const runtime = resolveRuntimeContext(config.runtime);
+    const modules = new Map();
+    const coordinates = new Map();
+    const active = new Map();
+    let disposed = false;
+    const ensureActive = () => {
+        if (disposed)
+            throw new AiRuntimeError('llm_module_client_disposed', 'LLM module client has been disposed');
+    };
+    const client = {
+        register(module) {
+            ensureActive();
+            const descriptor = snapshotLlmModuleDescriptor(module.descriptor);
+            const existing = modules.get(descriptor.id);
+            if (existing) {
+                throw new AiRuntimeError('llm_module_already_registered', `LLM module id "${descriptor.id}" from ${describeLlmModuleSource(descriptor)} conflicts with ` +
+                    `module from ${describeLlmModuleSource(existing.module.descriptor)}`);
+            }
+            const coordinate = llmModuleCoordinate(descriptor);
+            const existingId = coordinates.get(coordinate);
+            if (existingId) {
+                const owner = modules.get(existingId);
+                throw new AiRuntimeError('llm_model_already_registered', `LLM model coordinate "${describeLlmModuleCoordinate(descriptor)}" from ` +
+                    `${describeLlmModuleSource(descriptor)} is already owned by module "${existingId}" from ` +
+                    `${owner ? describeLlmModuleSource(owner.module.descriptor) : 'an unknown source'}`);
+            }
+            const registered = { ...module, descriptor };
+            modules.set(descriptor.id, { module: registered, disposed: false });
+            coordinates.set(coordinate, descriptor.id);
+            return createHandle(client, descriptor);
+        },
+        async unregister(moduleId) {
+            ensureActive();
+            const id = normalizeModuleId(moduleId);
+            const registered = modules.get(id);
+            if (!registered)
+                return false;
+            modules.delete(id);
+            releaseCoordinate(coordinates, registered.module.descriptor, id);
+            await abortAndWait([...active.values()].filter((operation) => operation.moduleId === id));
+            await disposeRegistered(registered);
+            return true;
+        },
+        async drainSource(namespace) {
+            ensureActive();
+            const owner = normalizeSourceNamespace(namespace);
+            const pending = [...active.values()].filter((operation) => operation.sourceNamespace === owner);
+            await abortAndWait(pending);
+            return pending.length;
+        },
+        async unregisterSource(namespace) {
+            ensureActive();
+            const owner = normalizeSourceNamespace(namespace);
+            const owned = [...modules.entries()].filter(([, entry]) => (entry.module.descriptor.source.namespace === owner));
+            for (const [id, entry] of owned) {
+                modules.delete(id);
+                releaseCoordinate(coordinates, entry.module.descriptor, id);
+            }
+            await abortAndWait([...active.values()].filter((operation) => operation.sourceNamespace === owner));
+            await Promise.all(owned.map(async ([, entry]) => await disposeRegistered(entry)));
+            return owned.length;
+        },
+        list() {
+            ensureActive();
+            return [...modules.values()].map((entry) => entry.module.descriptor);
+        },
+        get(moduleId) {
+            ensureActive();
+            const registered = modules.get(normalizeModuleId(moduleId));
+            return registered ? createHandle(client, registered.module.descriptor) : undefined;
+        },
+        async execute(moduleId, request, options = {}) {
+            ensureActive();
+            const id = normalizeModuleId(moduleId);
+            const registered = requireModule(modules, id);
+            const descriptor = registered.module.descriptor;
+            const mode = resolveMode(descriptor, options.mode);
+            validateRequestCoordinates(descriptor, request);
+            const requestId = normalizeRequestId(options.requestId, `${id}-${Date.now()}`);
+            const lease = beginOperation(active, descriptor, requestId, options);
+            const fullRequest = {
+                ...request,
+                providerId: descriptor.providerId,
+                modelId: descriptor.modelId,
+                capabilities: { ...descriptor.capabilities },
+            };
+            const startedAtMs = Date.now();
+            const inputChars = countLlmInputChars(fullRequest.messages);
+            const span = runtime.tracer.startSpan('llm.module.execute', {
+                requestId, moduleId: id, providerId: descriptor.providerId, modelId: descriptor.modelId,
+                sourceNamespace: descriptor.source.namespace, mode,
+            });
+            runtime.logger.info('LLM 模块执行开始', logContext(descriptor, requestId, {
+                event: 'llm.module.execute.start', mode,
+            }));
+            try {
+                if (lease.signal.aborted)
+                    throw cancelledError(requestId);
+                const output = validateLlmModuleOutput(await registered.module.execute(fullRequest, {
+                    runtime,
+                    requestId,
+                    signal: lease.signal,
+                    mode,
+                    emit: async (event) => {
+                        validateLlmModuleStreamEvent(event, id);
+                        if (mode !== 'event-stream') {
+                            throw new AiRuntimeError('llm_module_mode_violation', `LLM module "${id}" emitted ${event.type} in request-response mode; ` +
+                                'use event-stream mode or stop emitting incremental events');
+                        }
+                        await options.onEvent?.(event);
+                    },
+                }), id);
+                if (lease.signal.aborted)
+                    throw cancelledError(requestId);
+                if (output.usage)
+                    await emit(options, { type: 'Usage', data: output.usage });
+                await emit(options, { type: 'Finish', data: { finishReason: output.finishReason } });
+                const elapsedMs = Date.now() - startedAtMs;
+                const outputChars = output.output.length + output.reasoningOutput.length;
+                const outcome = {
+                    ...output,
+                    providerId: descriptor.providerId,
+                    modelId: descriptor.modelId,
+                    startedAtMs,
+                    elapsedMs,
+                    inputChars,
+                    outputChars,
+                };
+                await emit(options, {
+                    type: 'Done',
+                    data: {
+                        providerId: descriptor.providerId,
+                        modelId: descriptor.modelId,
+                        startedAtMs,
+                        elapsedMs,
+                        inputChars,
+                        outputChars,
+                    },
+                });
+                runtime.logger.info('LLM 模块执行完成', logContext(descriptor, requestId, {
+                    event: 'llm.module.execute.completed', elapsedMs, inputChars, outputChars,
+                }));
+                span.end();
+                return outcome;
+            }
+            catch (error) {
+                const normalized = normalizeOperationError(id, requestId, error, lease);
+                try {
+                    await emit(options, { type: 'Error', data: normalized.message });
+                }
+                catch { /* 保留首个失败。 */ }
+                runtime.logger.error('LLM 模块执行失败', logContext(descriptor, requestId, {
+                    event: 'llm.module.execute.failed', error: normalized,
+                }));
+                span.end(normalized);
+                throw normalized;
+            }
+            finally {
+                lease.release();
+            }
+        },
+        async discover(moduleId, options = {}) {
+            ensureActive();
+            const id = normalizeModuleId(moduleId);
+            const registered = requireModule(modules, id);
+            const descriptor = registered.module.descriptor;
+            if (!registered.module.discover) {
+                throw new AiRuntimeError('llm_discovery_unsupported', `LLM module "${id}" (${describeLlmModuleCoordinate(descriptor)}) has no dynamic discovery adapter; ` +
+                    'use its descriptor modelId or register a module with discover()');
+            }
+            const requestId = normalizeRequestId(options.requestId, `${id}-discover-${Date.now()}`);
+            const lease = beginOperation(active, descriptor, requestId, options);
+            const span = runtime.tracer.startSpan('llm.module.discover', {
+                requestId, moduleId: id, providerId: descriptor.providerId, sourceNamespace: descriptor.source.namespace,
+            });
+            runtime.logger.info('LLM 模块模型发现开始', logContext(descriptor, requestId, {
+                event: 'llm.module.discover.start',
+            }));
+            try {
+                if (lease.signal.aborted)
+                    throw cancelledError(requestId);
+                const models = validateDiscoveredModels(await registered.module.discover({
+                    runtime, requestId, signal: lease.signal,
+                }), id);
+                if (lease.signal.aborted)
+                    throw cancelledError(requestId);
+                runtime.logger.info('LLM 模块模型发现完成', logContext(descriptor, requestId, {
+                    event: 'llm.module.discover.completed', modelCount: models.length,
+                }));
+                span.end();
+                return models;
+            }
+            catch (error) {
+                const normalized = normalizeOperationError(id, requestId, error, lease);
+                runtime.logger.error('LLM 模块模型发现失败', logContext(descriptor, requestId, {
+                    event: 'llm.module.discover.failed', error: normalized,
+                }));
+                span.end(normalized);
+                throw normalized;
+            }
+            finally {
+                lease.release();
+            }
+        },
+        cancel(requestId) {
+            ensureActive();
+            active.get(requestId.trim())?.controller.abort();
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            const registered = [...modules.values()];
+            modules.clear();
+            coordinates.clear();
+            await abortAndWait([...active.values()]);
+            active.clear();
+            await Promise.all(registered.map(async (entry) => await disposeRegistered(entry)));
+        },
+    };
+    try {
+        for (const module of config.modules ?? [])
+            client.register(module);
+    }
+    catch (error) {
+        void client.dispose();
+        throw error;
+    }
+    return client;
+}
+function createHandle(client, descriptor) {
+    return {
+        descriptor,
+        execute: async (request, options) => await client.execute(descriptor.id, request, options),
+        discover: async (options) => await client.discover(descriptor.id, options),
+    };
+}
+function requireModule(modules, id) {
+    const module = modules.get(id);
+    if (module)
+        return module;
+    const available = [...modules.keys()];
+    throw new AiRuntimeError('llm_module_not_found', `Unknown LLM module "${id}". Available modules: ${available.length ? available.join(', ') : '(none)'}`);
+}
+function beginOperation(active, descriptor, requestId, options) {
+    if (active.has(requestId)) {
+        throw new AiRuntimeError('llm_request_active', `LLM request "${requestId}" is already active; choose a unique requestId or cancel the existing request`);
+    }
+    if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0)) {
+        throw new AiRuntimeError('invalid_llm_timeout', 'LLM module timeoutMs must be a positive finite number');
+    }
+    const controller = new AbortController();
+    const forwardAbort = () => controller.abort();
+    if (options.signal?.aborted)
+        controller.abort();
+    else
+        options.signal?.addEventListener('abort', forwardAbort, { once: true });
+    let didTimeOut = false;
+    const timer = options.timeoutMs === undefined ? undefined : setTimeout(() => {
+        didTimeOut = true;
+        controller.abort();
+    }, options.timeoutMs);
+    let markFinished = () => undefined;
+    const finished = new Promise((resolve) => { markFinished = resolve; });
+    active.set(requestId, {
+        moduleId: descriptor.id,
+        sourceNamespace: descriptor.source.namespace,
+        controller,
+        finished,
+        markFinished,
+    });
+    let released = false;
+    return {
+        signal: controller.signal,
+        timedOut: () => didTimeOut,
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            options.signal?.removeEventListener('abort', forwardAbort);
+            if (timer !== undefined)
+                clearTimeout(timer);
+            active.delete(requestId);
+            markFinished();
+        },
+    };
+}
+function resolveMode(descriptor, requested) {
+    const mode = requested ?? (descriptor.executionModes.includes('event-stream')
+        ? 'event-stream'
+        : 'request-response');
+    if (!descriptor.executionModes.includes(mode)) {
+        throw new AiRuntimeError('llm_module_mode_unsupported', `LLM module "${descriptor.id}" does not support ${mode}. Available modes: ` +
+            descriptor.executionModes.join(', '));
+    }
+    return mode;
+}
+function validateRequestCoordinates(descriptor, request) {
+    const providerId = request.providerId === undefined
+        ? descriptor.providerId
+        : normalizeCapabilityStableId(request.providerId, 'invalid_llm_provider_id', 'LLM request provider id');
+    const modelId = request.modelId === undefined
+        ? descriptor.modelId
+        : normalizeCapabilityStableId(request.modelId, 'invalid_llm_model_id', 'LLM request model id');
+    if (providerId !== descriptor.providerId || modelId !== descriptor.modelId) {
+        throw new AiRuntimeError('llm_module_coordinate_mismatch', `LLM module "${descriptor.id}" owns ${describeLlmModuleCoordinate(descriptor)}, ` +
+            `but request selected ${providerId}/${modelId}; choose the matching module or omit request coordinates`);
+    }
+}
+function normalizeOperationError(moduleId, requestId, error, lease) {
+    if (lease.timedOut()) {
+        return new AiRuntimeError('llm_timeout', `LLM module "${moduleId}" timed out: ${requestId}`);
+    }
+    if (lease.signal.aborted)
+        return cancelledError(requestId);
+    if (error instanceof AiRuntimeError)
+        return error;
+    return new AiRuntimeError('llm_module_execution_failed', `LLM module "${moduleId}" failed: ${error instanceof Error ? error.message : String(error)}`);
+}
+function normalizeModuleId(id) {
+    return normalizeCapabilityStableId(id, 'invalid_llm_module_id', 'LLM module id');
+}
+function normalizeSourceNamespace(namespace) {
+    return normalizeCapabilityStableId(namespace, 'invalid_llm_module_source', 'LLM module source namespace');
+}
+function normalizeRequestId(value, fallback) {
+    return normalizeCapabilityStableId(value?.trim() || fallback, 'invalid_llm_request_id', 'LLM request id');
+}
+function releaseCoordinate(coordinates, descriptor, moduleId) {
+    const coordinate = llmModuleCoordinate(descriptor);
+    if (coordinates.get(coordinate) === moduleId)
+        coordinates.delete(coordinate);
+}
+async function abortAndWait(operations) {
+    for (const operation of operations)
+        operation.controller.abort();
+    await Promise.all(operations.map(async (operation) => await operation.finished));
+}
+async function disposeRegistered(registered) {
+    if (registered.disposed)
+        return;
+    registered.disposed = true;
+    await registered.module.dispose?.();
+}
+async function emit(options, event) {
+    await options.onEvent?.(event);
+}
+function logContext(descriptor, requestId, detail) {
+    const { event, error, ...context } = detail;
+    return {
+        event,
+        requestId,
+        providerId: descriptor.providerId,
+        modelId: descriptor.modelId,
+        context: { moduleId: descriptor.id, sourceNamespace: descriptor.source.namespace, ...context },
+        error,
+    };
+}

package/dist/llm/modules/index.d.ts

@@ -0,0 +1,4 @@
+/** 外部包、插件与内置 LLM 共用的按需注册/执行边界；不隐式导入具体供应商。 */
+export * from './types.js';
+export * from './validation.js';
+export * from './client.js';

package/dist/llm/modules/index.js

@@ -0,0 +1,4 @@
+/** 外部包、插件与内置 LLM 共用的按需注册/执行边界；不隐式导入具体供应商。 */
+export * from './types.js';
+export * from './validation.js';
+export * from './client.js';

package/dist/llm/modules/result-validation.d.ts

@@ -0,0 +1,5 @@
+import type { DiscoveredModelItem } from '../discovery.js';
+import type { LlmModuleOutput, LlmModuleStreamEvent } from './types.js';
+export declare function validateLlmModuleOutput(output: LlmModuleOutput, moduleId: string): LlmModuleOutput;
+export declare function validateLlmModuleStreamEvent(event: LlmModuleStreamEvent, moduleId: string): void;
+export declare function validateDiscoveredModels(models: readonly DiscoveredModelItem[], moduleId: string): readonly DiscoveredModelItem[];

package/dist/llm/modules/result-validation.js

@@ -0,0 +1,54 @@
+import { AiRuntimeError } from '../../runtime/AiRuntimeError.js';
+import { normalizeCapabilityStableId } from '../../capabilities/validation.js';
+export function validateLlmModuleOutput(output, moduleId) {
+    if (!output || typeof output.output !== 'string' || typeof output.reasoningOutput !== 'string') {
+        throw new AiRuntimeError('llm_module_output_invalid', `LLM module "${moduleId}" must return string output and reasoningOutput`);
+    }
+    if (output.finishReason !== null && typeof output.finishReason !== 'string') {
+        throw new AiRuntimeError('llm_module_output_invalid', `LLM module "${moduleId}" finishReason must be string or null`);
+    }
+    if (output.usage !== null)
+        validateUsage(output.usage, moduleId);
+    if (output.providerMetadata !== undefined && (typeof output.providerMetadata !== 'object' || output.providerMetadata === null ||
+        Array.isArray(output.providerMetadata))) {
+        throw new AiRuntimeError('llm_module_output_invalid', `LLM module "${moduleId}" providerMetadata must be an object when provided`);
+    }
+    return output;
+}
+export function validateLlmModuleStreamEvent(event, moduleId) {
+    if (!['Token', 'ReasoningToken'].includes(event?.type) || typeof event?.data !== 'string') {
+        throw new AiRuntimeError('llm_module_event_invalid', `LLM module "${moduleId}" may emit only Token/ReasoningToken events with string data; ` +
+            'Usage/Finish/Done/Error are owned by the client');
+    }
+}
+export function validateDiscoveredModels(models, moduleId) {
+    if (!Array.isArray(models)) {
+        throw new AiRuntimeError('llm_discovery_invalid', `LLM module "${moduleId}" discover() must return an array`);
+    }
+    const seen = new Set();
+    return Object.freeze(models.map((model, index) => {
+        const modelId = normalizeCapabilityStableId(model?.modelId, 'llm_discovery_invalid', `LLM module "${moduleId}" discovered model[${index}].modelId`);
+        if (seen.has(modelId)) {
+            throw new AiRuntimeError('llm_discovery_invalid', `LLM module "${moduleId}" discovered duplicate modelId: ${modelId}`);
+        }
+        seen.add(modelId);
+        if (typeof model.displayName !== 'string' || !model.displayName.trim()) {
+            throw new AiRuntimeError('llm_discovery_invalid', `LLM module "${moduleId}" discovered model "${modelId}" with blank displayName`);
+        }
+        validateDiscoveryLimit(model.contextWindow, moduleId, modelId, 'contextWindow');
+        validateDiscoveryLimit(model.maxOutputTokens, moduleId, modelId, 'maxOutputTokens');
+        return Object.freeze({ ...model, modelId, displayName: model.displayName.trim() });
+    }));
+}
+function validateUsage(usage, moduleId) {
+    for (const [key, value] of Object.entries(usage)) {
+        if (value !== null && (!Number.isInteger(value) || value < 0)) {
+            throw new AiRuntimeError('llm_module_output_invalid', `LLM module "${moduleId}" usage.${key} must be null or a non-negative integer`);
+        }
+    }
+}
+function validateDiscoveryLimit(value, moduleId, modelId, label) {
+    if (value !== null && (!Number.isInteger(value) || value <= 0)) {
+        throw new AiRuntimeError('llm_discovery_invalid', `LLM module "${moduleId}" discovered model "${modelId}" ${label} must be null or a positive integer`);
+    }
+}

package/dist/llm/modules/types.d.ts

@@ -0,0 +1,102 @@
+import type { CapabilitySource } from '../../capabilities/types.js';
+import type { ResolvedRuntimeContext, RuntimeContext } from '../../runtime/RuntimeContext.js';
+import type { DiscoveredModelItem } from '../discovery.js';
+import type { LlmChatRequestDto, LlmStreamEventDto, LlmStreamOutput, LlmUsageDto } from '../chatTypes.js';
+import type { LlmCapabilities } from '../types.js';
+export type LlmModuleExecutionMode = 'request-response' | 'event-stream';
+export interface LlmModuleDescriptor {
+    /** 宿主内全局稳定的模块 ID；与 provider/model 坐标分别校验。 */
+    id: string;
+    source: CapabilitySource;
+    providerId: string;
+    modelId: string;
+    displayName?: string;
+    capabilities: LlmCapabilities;
+    executionModes: readonly LlmModuleExecutionMode[];
+    tags?: readonly string[];
+}
+export type LlmModuleRequest = Omit<LlmChatRequestDto, 'providerId' | 'modelId'> & {
+    /** 可省略；填写时必须与所选模块一致，防止宿主路由串线。 */
+    providerId?: string;
+    modelId?: string;
+};
+export interface LlmModuleOutput extends LlmStreamOutput {
+    providerMetadata?: Readonly<Record<string, unknown>>;
+}
+export type LlmModuleStreamEvent = Extract<LlmStreamEventDto, {
+    type: 'Token' | 'ReasoningToken';
+}>;
+export type LlmModuleEvent = LlmModuleStreamEvent | {
+    type: 'Usage';
+    data: LlmUsageDto;
+} | {
+    type: 'Finish';
+    data: {
+        finishReason: string | null;
+    };
+} | Extract<LlmStreamEventDto, {
+    type: 'Done' | 'Error';
+}>;
+export interface LlmModuleExecutionContext {
+    runtime: ResolvedRuntimeContext;
+    requestId: string;
+    signal: AbortSignal;
+    mode: LlmModuleExecutionMode;
+    /** 只接收增量 token；Usage/Finish/Done/Error 由 client 统一发射。 */
+    emit(event: LlmModuleStreamEvent): Promise<void>;
+}
+export interface LlmModuleDiscoveryContext {
+    runtime: ResolvedRuntimeContext;
+    requestId: string;
+    signal: AbortSignal;
+}
+export interface LlmModule {
+    descriptor: LlmModuleDescriptor;
+    execute(request: LlmChatRequestDto, context: LlmModuleExecutionContext): Promise<LlmModuleOutput>;
+    discover?(context: LlmModuleDiscoveryContext): Promise<readonly DiscoveredModelItem[]>;
+    dispose?(): void | Promise<void>;
+}
+export interface LlmModuleExecuteOptions {
+    requestId?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    mode?: LlmModuleExecutionMode;
+    /** 逐条等待，给 QuickJS/IPC 等宿主桥提供背压。 */
+    onEvent?(event: LlmModuleEvent): void | Promise<void>;
+}
+export interface LlmModuleDiscoveryOptions {
+    requestId?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+export interface LlmModuleExecutionOutcome extends LlmModuleOutput {
+    providerId: string;
+    modelId: string;
+    startedAtMs: number;
+    elapsedMs: number;
+    inputChars: number;
+    outputChars: number;
+}
+export interface LlmModuleHandle {
+    readonly descriptor: LlmModuleDescriptor;
+    execute(request: LlmModuleRequest, options?: LlmModuleExecuteOptions): Promise<LlmModuleExecutionOutcome>;
+    discover(options?: LlmModuleDiscoveryOptions): Promise<readonly DiscoveredModelItem[]>;
+}
+export interface CreateLlmModuleClientConfig {
+    runtime: RuntimeContext;
+    modules?: readonly LlmModule[];
+}
+export interface LlmModuleClient {
+    register(module: LlmModule): LlmModuleHandle;
+    unregister(moduleId: string): Promise<boolean>;
+    /** 取消并等待当前 namespace 的活动操作，但保留注册；返回本次等待的操作数。 */
+    drainSource(namespace: string): Promise<number>;
+    /** 先从注册表移除，再取消/等待并 dispose namespace 下全部模块。 */
+    unregisterSource(namespace: string): Promise<number>;
+    list(): readonly LlmModuleDescriptor[];
+    get(moduleId: string): LlmModuleHandle | undefined;
+    execute(moduleId: string, request: LlmModuleRequest, options?: LlmModuleExecuteOptions): Promise<LlmModuleExecutionOutcome>;
+    discover(moduleId: string, options?: LlmModuleDiscoveryOptions): Promise<readonly DiscoveredModelItem[]>;
+    cancel(requestId: string): void;
+    dispose(): Promise<void>;
+}

package/dist/llm/modules/types.js

@@ -0,0 +1 @@
+export {};

package/dist/llm/modules/validation.d.ts

@@ -0,0 +1,7 @@
+import type { LlmModuleDescriptor } from './types.js';
+export declare function validateLlmModuleDescriptor(descriptor: LlmModuleDescriptor): void;
+export declare function snapshotLlmModuleDescriptor(descriptor: LlmModuleDescriptor): LlmModuleDescriptor;
+export declare function defineLlmModuleDescriptor(descriptor: LlmModuleDescriptor): LlmModuleDescriptor;
+export declare function llmModuleCoordinate(descriptor: LlmModuleDescriptor): string;
+export declare function describeLlmModuleCoordinate(descriptor: LlmModuleDescriptor): string;
+export declare function describeLlmModuleSource(descriptor: LlmModuleDescriptor): string;

package/dist/llm/modules/validation.js

@@ -0,0 +1,90 @@
+import { AiRuntimeError } from '../../runtime/AiRuntimeError.js';
+import { normalizeCapabilityStableId } from '../../capabilities/validation.js';
+const CAPABILITY_BOOLEAN_KEYS = [
+    'text', 'image', 'video', 'audio', 'streaming', 'toolCall', 'parallelTools',
+    'jsonOutput', 'reasoning', 'sampling', 'usage',
+];
+const EXECUTION_MODES = new Set(['request-response', 'event-stream']);
+export function validateLlmModuleDescriptor(descriptor) {
+    normalizeCapabilityStableId(descriptor.id, 'invalid_llm_module_id', 'LLM module id');
+    normalizeCapabilityStableId(descriptor.source?.kind, 'invalid_llm_module_source', 'LLM module source kind');
+    normalizeCapabilityStableId(descriptor.source?.namespace, 'invalid_llm_module_source', 'LLM module source namespace');
+    normalizeCapabilityStableId(descriptor.providerId, 'invalid_llm_provider_id', 'LLM provider id');
+    normalizeCapabilityStableId(descriptor.modelId, 'invalid_llm_model_id', 'LLM model id');
+    if (descriptor.displayName !== undefined && !descriptor.displayName.trim()) {
+        throw new AiRuntimeError('invalid_llm_module_descriptor', 'LLM module displayName must not be blank');
+    }
+    validateCapabilities(descriptor.capabilities);
+    if (!Array.isArray(descriptor.executionModes) || descriptor.executionModes.length === 0) {
+        throw new AiRuntimeError('invalid_llm_module_descriptor', 'LLM module executionModes must contain request-response and/or event-stream');
+    }
+    validateUnique(descriptor.executionModes, 'execution mode', (mode) => {
+        if (!EXECUTION_MODES.has(mode)) {
+            throw new AiRuntimeError('invalid_llm_module_descriptor', `Unsupported LLM module execution mode: ${mode}. Available modes: request-response, event-stream`);
+        }
+    });
+    validateUnique(descriptor.tags ?? [], 'tag', (tag) => {
+        normalizeCapabilityStableId(tag, 'invalid_llm_module_descriptor', 'LLM module tag');
+    });
+    if (descriptor.executionModes.includes('event-stream') && !descriptor.capabilities.streaming) {
+        throw new AiRuntimeError('invalid_llm_module_descriptor', `LLM module "${descriptor.id}" declares event-stream but capabilities.streaming is false`);
+    }
+}
+export function snapshotLlmModuleDescriptor(descriptor) {
+    validateLlmModuleDescriptor(descriptor);
+    return Object.freeze({
+        ...descriptor,
+        source: Object.freeze({ ...descriptor.source }),
+        capabilities: Object.freeze({ ...descriptor.capabilities }),
+        executionModes: Object.freeze([...descriptor.executionModes]),
+        tags: descriptor.tags ? Object.freeze([...descriptor.tags]) : undefined,
+    });
+}
+export function defineLlmModuleDescriptor(descriptor) {
+    return snapshotLlmModuleDescriptor(descriptor);
+}
+export function llmModuleCoordinate(descriptor) {
+    return `${descriptor.providerId}\u0000${descriptor.modelId}`;
+}
+export function describeLlmModuleCoordinate(descriptor) {
+    return `${descriptor.providerId}/${descriptor.modelId}`;
+}
+export function describeLlmModuleSource(descriptor) {
+    return `${descriptor.source.kind} source "${descriptor.source.namespace}"`;
+}
+function validateCapabilities(capabilities) {
+    if (!capabilities || typeof capabilities !== 'object') {
+        throw new AiRuntimeError('invalid_llm_module_descriptor', 'LLM module capabilities are required');
+    }
+    for (const key of CAPABILITY_BOOLEAN_KEYS) {
+        if (typeof capabilities[key] !== 'boolean') {
+            throw new AiRuntimeError('invalid_llm_module_descriptor', `LLM module capabilities.${key} must be boolean`);
+        }
+    }
+    if (!['none', 'json', 'schema'].includes(capabilities.structuredOutputMode)) {
+        throw new AiRuntimeError('invalid_llm_module_descriptor', 'LLM module capabilities.structuredOutputMode must be none, json, or schema');
+    }
+    if (capabilities.jsonOutput !== (capabilities.structuredOutputMode !== 'none')) {
+        throw new AiRuntimeError('invalid_llm_module_descriptor', 'LLM module capabilities.jsonOutput must match structuredOutputMode');
+    }
+    if (capabilities.parallelTools && !capabilities.toolCall) {
+        throw new AiRuntimeError('invalid_llm_module_descriptor', 'LLM module capabilities.parallelTools requires toolCall');
+    }
+    validateNullablePositiveInteger(capabilities.contextWindow, 'contextWindow');
+    validateNullablePositiveInteger(capabilities.maxOutputTokens, 'maxOutputTokens');
+}
+function validateNullablePositiveInteger(value, label) {
+    if (value !== null && (!Number.isInteger(value) || value <= 0)) {
+        throw new AiRuntimeError('invalid_llm_module_descriptor', `LLM module capabilities.${label} must be null or a positive integer`);
+    }
+}
+function validateUnique(values, label, validate) {
+    const seen = new Set();
+    for (const value of values) {
+        validate(value);
+        if (seen.has(value)) {
+            throw new AiRuntimeError('invalid_llm_module_descriptor', `LLM module ${label} is duplicated: ${value}`);
+        }
+        seen.add(value);
+    }
+}