@henjicc/ai-sdk 0.2.8

package/dist/capabilities/builtin-descriptors.js

@@ -0,0 +1,32 @@
+/** 仅用于统一发现；执行继续由 generation client 持有。 */
+export const GENERATION_CAPABILITY_DESCRIPTOR = {
+    id: 'builtin.media-generation',
+    kind: 'media-generation',
+    source: { kind: 'builtin', namespace: '@henjicc/ai-sdk' },
+    contract: {
+        input: [
+            { kind: 'text' },
+            { kind: 'image', multiple: true },
+            { kind: 'video', multiple: true },
+            { kind: 'audio', multiple: true },
+        ],
+        output: [
+            { kind: 'image' },
+            { kind: 'video' },
+            { kind: 'audio' },
+        ],
+    },
+};
+/** 仅用于统一发现；执行继续由 LLM/chat client 持有。 */
+export const CHAT_CAPABILITY_DESCRIPTOR = {
+    id: 'builtin.chat',
+    kind: 'chat',
+    source: { kind: 'builtin', namespace: '@henjicc/ai-sdk' },
+    contract: {
+        input: [{ kind: 'text', required: true }],
+        output: [
+            { kind: 'text' },
+            { kind: 'structured-data' },
+        ],
+    },
+};

package/dist/capabilities/client.d.ts

@@ -0,0 +1,21 @@
+import { type RuntimeContext } from '../runtime/RuntimeContext.js';
+import type { CapabilityDescriptor, CapabilityExecuteOptions, CapabilityHandle, CapabilityKind, CapabilityModule, CapabilityRealtimeModule, CapabilityRealtimeSession } from './types.js';
+export interface CreateCapabilityClientConfig {
+    runtime: RuntimeContext;
+    modules?: readonly CapabilityModule<unknown, unknown, unknown>[];
+    realtimeModules?: readonly CapabilityRealtimeModule<unknown, unknown, unknown, unknown>[];
+}
+export interface CapabilityClient {
+    register<TInput, TOutput, TEvent = never>(module: CapabilityModule<TInput, TOutput, TEvent>): CapabilityHandle<TInput, TOutput, TEvent>;
+    registerRealtime<TStart, TInput, TEvent, TOutput>(module: CapabilityRealtimeModule<TStart, TInput, TEvent, TOutput>): CapabilityDescriptor;
+    unregister(moduleId: string): Promise<boolean>;
+    /** 注销同一包/插件命名空间拥有的全部模块，并等待活动请求与资源释放完成。 */
+    unregisterSource(namespace: string): Promise<number>;
+    list(kind?: CapabilityKind): readonly CapabilityDescriptor[];
+    get<TInput, TOutput, TEvent = never>(moduleId: string): CapabilityHandle<TInput, TOutput, TEvent> | undefined;
+    execute<TInput, TOutput, TEvent = never>(moduleId: string, input: TInput, options?: CapabilityExecuteOptions<TEvent>): Promise<TOutput>;
+    openSession<TStart, TInput, TEvent, TOutput>(moduleId: string, input: TStart, options?: CapabilityExecuteOptions<TEvent>): Promise<CapabilityRealtimeSession<TInput, TOutput>>;
+    cancel(requestId: string): void;
+    dispose(): Promise<void>;
+}
+export declare function createCapabilityClient(config: CreateCapabilityClientConfig): CapabilityClient;

package/dist/capabilities/client.js

@@ -0,0 +1,427 @@
+import { AiRuntimeError, cancelledError } from '../runtime/AiRuntimeError.js';
+import { resolveRuntimeContext } from '../runtime/RuntimeContext.js';
+import { capabilityModelCoordinates, describeCapabilitySource, normalizeCapabilityStableId, snapshotCapabilityDescriptor, validateCapabilityDescriptor, } from './validation.js';
+export function createCapabilityClient(config) {
+    const runtime = resolveRuntimeContext(config.runtime);
+    const modules = new Map();
+    const modelCoordinates = new Map();
+    const active = new Map();
+    let disposed = false;
+    const ensureActive = () => {
+        if (disposed)
+            throw new AiRuntimeError('client_disposed', 'Capability client has been disposed');
+    };
+    const client = {
+        register(module) {
+            ensureActive();
+            const descriptor = registerModule(modules, modelCoordinates, module, 'execute');
+            return createHandle(client, descriptor);
+        },
+        registerRealtime(module) {
+            ensureActive();
+            return registerModule(modules, modelCoordinates, module, 'realtime');
+        },
+        async unregister(moduleId) {
+            ensureActive();
+            const id = normalizeModuleId(moduleId);
+            const registered = modules.get(id);
+            if (!registered)
+                return false;
+            const pending = abortModuleExecutions(active, id);
+            modules.delete(id);
+            releaseModelCoordinates(modelCoordinates, registered.module.descriptor, id);
+            await Promise.all(pending);
+            await disposeRegisteredModule(registered);
+            return true;
+        },
+        async unregisterSource(namespace) {
+            ensureActive();
+            const normalizedNamespace = normalizeCapabilityStableId(namespace, 'invalid_capability_source', 'Capability source namespace');
+            const ownedIds = [...modules.entries()]
+                .filter(([, registered]) => registered.module.descriptor.source.namespace === normalizedNamespace)
+                .map(([id]) => id);
+            await Promise.all(ownedIds.map(async (id) => await client.unregister(id)));
+            return ownedIds.length;
+        },
+        list(kind) {
+            ensureActive();
+            return [...modules.values()]
+                .map(({ module }) => module.descriptor)
+                .filter((descriptor) => kind === undefined || descriptor.kind === kind);
+        },
+        get(moduleId) {
+            ensureActive();
+            const registered = modules.get(normalizeModuleId(moduleId));
+            return registered?.mode === 'execute'
+                ? createHandle(client, registered.module.descriptor)
+                : undefined;
+        },
+        async execute(moduleId, input, options = {}) {
+            ensureActive();
+            const id = normalizeModuleId(moduleId);
+            const registered = modules.get(id);
+            if (!registered) {
+                throw new AiRuntimeError('capability_not_found', `Unknown capability module: ${id}`);
+            }
+            if (registered.mode !== 'execute') {
+                throw new AiRuntimeError('capability_mode_mismatch', `Capability module requires a realtime session: ${id}`);
+            }
+            const requestId = options.requestId?.trim() || `${id}-${Date.now()}`;
+            if (active.has(requestId)) {
+                throw new AiRuntimeError('capability_request_active', `Capability request already active: ${requestId}`);
+            }
+            const controller = new AbortController();
+            let markFinished = () => undefined;
+            const finished = new Promise((resolve) => {
+                markFinished = resolve;
+            });
+            const forwardAbort = () => controller.abort();
+            if (options.signal?.aborted)
+                controller.abort();
+            else
+                options.signal?.addEventListener('abort', forwardAbort, { once: true });
+            let timedOut = false;
+            const timeout = createTimeout(options.timeoutMs, () => {
+                timedOut = true;
+                controller.abort();
+            });
+            active.set(requestId, { moduleId: id, controller, finished, markFinished });
+            const span = runtime.tracer.startSpan('capability.execute', {
+                requestId,
+                capabilityId: id,
+                capabilityKind: registered.module.descriptor.kind,
+            });
+            runtime.logger.info('能力模块执行开始', {
+                event: 'capability.execute.start',
+                requestId,
+                context: { capabilityId: id, capabilityKind: registered.module.descriptor.kind },
+            });
+            try {
+                if (controller.signal.aborted)
+                    throw cancelledError(requestId);
+                const module = registered.module;
+                const output = await module.execute(input, {
+                    runtime,
+                    requestId,
+                    signal: controller.signal,
+                    emit: async (event) => await options.onEvent?.(event),
+                });
+                if (controller.signal.aborted)
+                    throw cancelledError(requestId);
+                runtime.logger.info('能力模块执行完成', {
+                    event: 'capability.execute.completed',
+                    requestId,
+                    context: { capabilityId: id },
+                });
+                span.end();
+                return output;
+            }
+            catch (error) {
+                const normalized = timedOut
+                    ? new AiRuntimeError('timeout', `Capability request timed out: ${requestId}`)
+                    : controller.signal.aborted
+                        ? cancelledError(requestId)
+                        : normalizeExecutionError(id, error);
+                runtime.logger.error('能力模块执行失败', {
+                    event: 'capability.execute.failed',
+                    requestId,
+                    context: { capabilityId: id },
+                    error: normalized,
+                });
+                span.end(normalized);
+                throw normalized;
+            }
+            finally {
+                options.signal?.removeEventListener('abort', forwardAbort);
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+                active.delete(requestId);
+                markFinished();
+            }
+        },
+        async openSession(moduleId, input, options = {}) {
+            ensureActive();
+            const id = normalizeModuleId(moduleId);
+            const registered = modules.get(id);
+            if (!registered) {
+                throw new AiRuntimeError('capability_not_found', `Unknown capability module: ${id}`);
+            }
+            if (registered.mode !== 'realtime') {
+                throw new AiRuntimeError('capability_mode_mismatch', `Capability module is not realtime: ${id}`);
+            }
+            const requestId = options.requestId?.trim() || `${id}-${Date.now()}`;
+            if (active.has(requestId)) {
+                throw new AiRuntimeError('capability_request_active', `Capability request already active: ${requestId}`);
+            }
+            const controller = new AbortController();
+            let markFinished = () => undefined;
+            const finished = new Promise((resolve) => { markFinished = resolve; });
+            const forwardAbort = () => controller.abort();
+            if (options.signal?.aborted)
+                controller.abort();
+            else
+                options.signal?.addEventListener('abort', forwardAbort, { once: true });
+            let timedOut = false;
+            const timeout = createTimeout(options.timeoutMs, () => {
+                timedOut = true;
+                controller.abort();
+            });
+            active.set(requestId, { moduleId: id, controller, finished, markFinished });
+            const span = runtime.tracer.startSpan('capability.session', {
+                requestId,
+                capabilityId: id,
+                capabilityKind: registered.module.descriptor.kind,
+            });
+            runtime.logger.info('能力实时会话开始', {
+                event: 'capability.session.start',
+                requestId,
+                context: { capabilityId: id, capabilityKind: registered.module.descriptor.kind },
+            });
+            try {
+                if (controller.signal.aborted)
+                    throw cancelledError(requestId);
+                const module = registered.module;
+                const driver = await module.open(input, {
+                    runtime,
+                    requestId,
+                    signal: controller.signal,
+                    emit: async (event) => await options.onEvent?.(event),
+                });
+                if (controller.signal.aborted) {
+                    await driver.close?.();
+                    throw timedOut
+                        ? new AiRuntimeError('timeout', `Capability session timed out: ${requestId}`)
+                        : cancelledError(requestId);
+                }
+                let ended = false;
+                let closePromise;
+                let finishPromise;
+                const closeDriver = () => {
+                    closePromise ??= Promise.resolve().then(async () => await driver.close?.());
+                    return closePromise;
+                };
+                const end = (error) => {
+                    if (ended)
+                        return;
+                    ended = true;
+                    options.signal?.removeEventListener('abort', forwardAbort);
+                    if (timeout !== undefined)
+                        clearTimeout(timeout);
+                    active.delete(requestId);
+                    markFinished();
+                    span.end(error);
+                };
+                const closeAfterAbort = async () => {
+                    if (ended)
+                        return;
+                    const error = timedOut
+                        ? new AiRuntimeError('timeout', `Capability session timed out: ${requestId}`)
+                        : cancelledError(requestId);
+                    try {
+                        await closeDriver();
+                    }
+                    finally {
+                        runtime.logger.error('能力实时会话失败', {
+                            event: 'capability.session.failed', requestId, context: { capabilityId: id }, error,
+                        });
+                        end(error);
+                    }
+                };
+                controller.signal.addEventListener('abort', () => { void closeAfterAbort(); }, { once: true });
+                const sessionInactiveError = () => timedOut
+                    ? new AiRuntimeError('timeout', `Capability session timed out: ${requestId}`)
+                    : cancelledError(requestId);
+                return {
+                    requestId,
+                    descriptor: registered.module.descriptor,
+                    send: async (value) => {
+                        if (ended || controller.signal.aborted)
+                            throw sessionInactiveError();
+                        await driver.send(value);
+                    },
+                    finish: () => {
+                        if (finishPromise)
+                            return finishPromise;
+                        if (ended || controller.signal.aborted)
+                            return Promise.reject(sessionInactiveError());
+                        finishPromise = (async () => {
+                            let output;
+                            try {
+                                output = await driver.finish();
+                                if (controller.signal.aborted)
+                                    throw cancelledError(requestId);
+                            }
+                            catch (error) {
+                                const normalized = controller.signal.aborted
+                                    ? cancelledError(requestId)
+                                    : normalizeExecutionError(id, error);
+                                try {
+                                    await closeDriver();
+                                }
+                                catch {
+                                    // 保留 finish 的首个失败；close 仅负责尽力释放连接。
+                                }
+                                runtime.logger.error('能力实时会话失败', {
+                                    event: 'capability.session.failed', requestId, context: { capabilityId: id }, error: normalized,
+                                });
+                                end(normalized);
+                                throw normalized;
+                            }
+                            try {
+                                await closeDriver();
+                            }
+                            catch (error) {
+                                const normalized = normalizeExecutionError(id, error);
+                                runtime.logger.error('能力实时会话失败', {
+                                    event: 'capability.session.failed', requestId, context: { capabilityId: id }, error: normalized,
+                                });
+                                end(normalized);
+                                throw normalized;
+                            }
+                            runtime.logger.info('能力实时会话完成', {
+                                event: 'capability.session.completed', requestId, context: { capabilityId: id },
+                            });
+                            end();
+                            return output;
+                        })();
+                        return finishPromise;
+                    },
+                    close: async () => {
+                        if (ended)
+                            return;
+                        try {
+                            await closeDriver();
+                            runtime.logger.info('能力实时会话关闭', {
+                                event: 'capability.session.closed', requestId, context: { capabilityId: id },
+                            });
+                            end();
+                        }
+                        catch (error) {
+                            const normalized = normalizeExecutionError(id, error);
+                            runtime.logger.error('能力实时会话失败', {
+                                event: 'capability.session.failed', requestId, context: { capabilityId: id }, error: normalized,
+                            });
+                            end(normalized);
+                            throw normalized;
+                        }
+                    },
+                };
+            }
+            catch (error) {
+                options.signal?.removeEventListener('abort', forwardAbort);
+                if (timeout !== undefined)
+                    clearTimeout(timeout);
+                active.delete(requestId);
+                markFinished();
+                const normalized = timedOut
+                    ? new AiRuntimeError('timeout', `Capability session timed out: ${requestId}`)
+                    : controller.signal.aborted
+                        ? cancelledError(requestId)
+                        : normalizeExecutionError(id, error);
+                runtime.logger.error('能力实时会话失败', {
+                    event: 'capability.session.failed', requestId, context: { capabilityId: id }, error: normalized,
+                });
+                span.end(normalized);
+                throw normalized;
+            }
+        },
+        cancel(requestId) {
+            ensureActive();
+            active.get(requestId.trim())?.controller.abort();
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            const pending = [...active.values()];
+            for (const execution of pending)
+                execution.controller.abort();
+            await Promise.all(pending.map((execution) => execution.finished));
+            active.clear();
+            const registered = [...modules.values()];
+            modules.clear();
+            modelCoordinates.clear();
+            await Promise.all(registered.map(async (entry) => await disposeRegisteredModule(entry)));
+        },
+    };
+    try {
+        for (const module of config.modules ?? [])
+            client.register(module);
+        for (const module of config.realtimeModules ?? [])
+            client.registerRealtime(module);
+    }
+    catch (error) {
+        void client.dispose();
+        throw error;
+    }
+    return client;
+}
+function createHandle(client, descriptor) {
+    return {
+        descriptor,
+        execute: async (input, options) => await client.execute(descriptor.id, input, options),
+    };
+}
+function registerModule(modules, modelCoordinates, module, mode) {
+    validateCapabilityDescriptor(module.descriptor);
+    const descriptor = snapshotCapabilityDescriptor(module.descriptor);
+    const id = normalizeModuleId(descriptor.id);
+    const existing = modules.get(id);
+    if (existing) {
+        throw new AiRuntimeError('capability_already_registered', `Capability module id "${id}" from ${describeCapabilitySource(descriptor)} conflicts with ` +
+            `${existing.mode} module from ${describeCapabilitySource(existing.module.descriptor)}`);
+    }
+    for (const coordinate of capabilityModelCoordinates(descriptor)) {
+        const existingId = modelCoordinates.get(coordinate);
+        if (existingId) {
+            const existingModule = modules.get(existingId);
+            throw new AiRuntimeError('capability_model_already_registered', `Capability model coordinate "${coordinate}" from ${describeCapabilitySource(descriptor)} ` +
+                `is already owned by module "${existingId}" from ${existingModule ? describeCapabilitySource(existingModule.module.descriptor) : 'an unknown source'}`);
+        }
+    }
+    const registeredModule = { ...module, descriptor };
+    modules.set(id, { module: registeredModule, mode, disposed: false });
+    for (const coordinate of capabilityModelCoordinates(descriptor)) {
+        modelCoordinates.set(coordinate, id);
+    }
+    return descriptor;
+}
+function createTimeout(timeoutMs, abort) {
+    if (timeoutMs === undefined)
+        return undefined;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new AiRuntimeError('invalid_timeout', 'Capability timeoutMs must be a positive finite number');
+    }
+    return setTimeout(abort, timeoutMs);
+}
+function normalizeModuleId(id) {
+    return normalizeCapabilityStableId(id, 'invalid_capability_id', 'Capability module id');
+}
+function releaseModelCoordinates(coordinates, descriptor, moduleId) {
+    for (const coordinate of capabilityModelCoordinates(descriptor)) {
+        if (coordinates.get(coordinate) === moduleId)
+            coordinates.delete(coordinate);
+    }
+}
+function abortModuleExecutions(active, moduleId) {
+    const pending = [];
+    for (const execution of active.values()) {
+        if (execution.moduleId !== moduleId)
+            continue;
+        execution.controller.abort();
+        pending.push(execution.finished);
+    }
+    return pending;
+}
+async function disposeRegisteredModule(registered) {
+    if (registered.disposed)
+        return;
+    registered.disposed = true;
+    await registered.module.dispose?.();
+}
+function normalizeExecutionError(moduleId, error) {
+    if (error instanceof AiRuntimeError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new AiRuntimeError('capability_execution_failed', `Capability module ${moduleId} failed: ${message}`);
+}

package/dist/capabilities/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './client.js';
+export * from './builtin-descriptors.js';
+export * from './media.js';
+export * from './validation.js';

package/dist/capabilities/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './client.js';
+export * from './builtin-descriptors.js';
+export * from './media.js';
+export * from './validation.js';

package/dist/capabilities/media.d.ts

@@ -0,0 +1,23 @@
+import type { MediaBinary, MediaReader } from '../runtime/index.js';
+export interface CapabilityBytesSource {
+    kind: 'bytes';
+    bytes: Uint8Array;
+    mediaType: string;
+    filename?: string;
+}
+export interface CapabilityMediaReference {
+    kind: 'media-ref';
+    ref: string;
+    /** 可用于提前校验；最终以宿主 MediaReader 返回值为准。 */
+    mediaType?: string;
+}
+export interface CapabilityRemoteUrlSource {
+    kind: 'remote-url';
+    /** 供应商可直接读取的 HTTP(S) URL；具体协议是否接受由能力模块校验。 */
+    url: string;
+    mediaType?: string;
+    filename?: string;
+}
+/** 可移植媒体输入：显式字节、宿主资源引用，或供应商可直接读取的远端 URL。 */
+export type CapabilityMediaSource = CapabilityBytesSource | CapabilityMediaReference | CapabilityRemoteUrlSource;
+export declare function readCapabilityMediaSource(source: CapabilityMediaSource, reader: MediaReader): Promise<MediaBinary>;

package/dist/capabilities/media.js

@@ -0,0 +1,18 @@
+import { AiRuntimeError } from '../runtime/AiRuntimeError.js';
+export async function readCapabilityMediaSource(source, reader) {
+    if (source.kind === 'bytes') {
+        return {
+            bytes: source.bytes,
+            mimeType: source.mediaType,
+            filename: source.filename?.trim() || 'input',
+        };
+    }
+    if (source.kind === 'remote-url') {
+        throw new AiRuntimeError('capability_remote_media_requires_provider', 'Remote media URL must be handled by the selected capability provider');
+    }
+    const media = await reader.read(source.ref);
+    if (source.mediaType && media.mimeType !== source.mediaType) {
+        throw new AiRuntimeError('capability_media_type_mismatch', `Host media type ${media.mimeType} does not match expected ${source.mediaType}`);
+    }
+    return media;
+}

package/dist/capabilities/realtime.d.ts

@@ -0,0 +1,2 @@
+export type { CapabilityRealtimeModule, CapabilityRealtimeSession, CapabilityRealtimeSessionDriver, } from './types.js';
+export type { RealtimeConnectOptions, RealtimeConnection, RealtimeMessage, RealtimePayload, RealtimeTransport, } from '../runtime/RealtimeTransport.js';

package/dist/capabilities/realtime.js

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

package/dist/capabilities/speech-recognition/bailian/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './presets.js';
+export * from './module.js';

package/dist/capabilities/speech-recognition/bailian/index.js

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './presets.js';
+export * from './module.js';

package/dist/capabilities/speech-recognition/bailian/module.d.ts

@@ -0,0 +1,5 @@
+import type { SpeechRecognitionModule } from '../index.js';
+import type { BailianAsrPreset } from './presets.js';
+import type { BailianAsrModuleOptions } from './types.js';
+/** 创建一个百炼非实时 ASR 模块；只导入本子路径时才会带入供应商实现。 */
+export declare function createBailianAsrModule(preset: BailianAsrPreset, options?: BailianAsrModuleOptions): SpeechRecognitionModule;