@deepseek-ai/dsh-experimental-speech-to-text 0.1.7-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/experimental/speech-to-text/README.md
+README.md: 64202aba4ae7e0ffc47c86243d818caa8f85a9e4
+README.zh.md: 38466f18a0670a252958c6b51c17457fcf80f14c

package/README.md

@@ -0,0 +1,80 @@
+---
+description: "Named experimental transcription providers and cancellation ownership."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-speech-to-text
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This Service Definition selects named speech recognizers through `ctx.speechToText`. Consumers resolve their request before execution; providers register independently.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Load through the [voice input bundle](../voice-input-bundle/README.md), or compose the service with a provider and consumer. `defaultProvider` is required and selects an exact registered id; the bundle supplies `sensevoice-local`. `language` supplies the omitted language hint. A missing or duplicate provider fails explicitly.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Maintainer details — click to expand</summary>
+
+`resolve()` captures the provider instance, recording and language. `transcribe()` rejects a withdrawn or replaced registration. A registration disposer closes admission, aborts accepted requests and joins provider settlement; providers must honor cancellation. No fallback selects a different recognizer or uploads audio. No runtime invariant companion is published because the registry is the sole source of provider and preparation observations.
+
+`defaultProvider` and `language` are volatile Config fields: `configure()` writes the supplied fields into this plugin's profile entry through the `settings` service, and the running instance reads the updated values without remounting; composition defaults apply until an override is saved. `configure()` fails without `settings` or a profile entry, and rejects a language unsupported by the selected provider before saving. Providers advertise accepted language hints through `languages`; `resolve()` validates the selected hint before transcription. Provider-owned preparation is observed through complete `SpeechSnapshot` values; closing an observer never cancels preparation.
+
+The `./wave` helper validates canonical 16 kHz mono PCM16 WAV for the Remote consumer and the native recognition process. Both reject inconsistent headers and lengths before decoding samples.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+[Voice input subsystem](../../../docs/subsystems/voice-input.md)
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as recordings and preparation remain outside model requests; ordinary user submission owns any later text.
+
+#### KV Cache effect
+
+No direct effect; ordinary submission owns the message content.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Only complete-recording transcription is supported. Streaming recognition and speech synthesis have no service methods.
+
+-----
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Maintainer details — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,80 @@
+---
+description: "具名实验性转写 Provider 及取消操作的所有权。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-experimental-speech-to-text
+
+[English](README.md) | 中文
+
+## 概述
+
+此服务定义通过 `ctx.speechToText` 选择具名语音识别器。消费者先解析请求再执行，Provider 独立注册。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此包
+
+通过[语音输入 Bundle](../voice-input-bundle/README.zh.md)加载，或组合此服务、Provider 与消费者。`defaultProvider` 为必填项，选择确切的注册 id；Bundle 提供 `sensevoice-local`。`language` 提供省略的语言提示。缺失或重复的 Provider 会明确报错。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>维护者信息 — 点击展开</summary>
+
+`resolve()` 捕获 Provider 实例、录音和语言。`transcribe()` 拒绝已撤销或替换的注册。注册的清理函数先拒绝新请求，再取消已接收的请求并等待 Provider 完成；Provider 必须响应取消。服务不会回退到其他识别器或上传音频。不发布运行时不变量伴随模块，因为注册表是 Provider 与准备状态观测的唯一来源。
+
+`defaultProvider` 与 `language` 是 volatile Config 字段：`configure()` 通过 `settings` 服务把传入的字段写入本插件的 profile 条目，运行中的实例无需重挂载即可读到更新值；保存覆盖值之前使用组合配置默认值。没有 `settings` 或 profile 条目时 `configure()` 失败，并在保存前拒绝所选 Provider 不支持的语言。Provider 通过 `languages` 公布支持的语言提示；`resolve()` 在转写前校验所选提示。观察者通过完整 `SpeechSnapshot` 接收 Provider 拥有的准备状态；关闭观察者不会取消准备。
+
+`./wave` 辅助函数为 Remote 消费者与原生识别进程校验规范的 16 kHz 单声道 PCM16 WAV。两者均在解码采样前拒绝不一致的头部和长度。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+[语音输入子系统](../../../docs/subsystems/voice-input.zh.md)
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为录音与准备不进入模型请求；之后的文字由普通用户提交拥有。
+
+#### KV 缓存影响
+
+没有直接影响；普通提交拥有消息内容。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 仅支持完整录音转写。服务没有流式识别或语音合成方法。
+
+-----
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者信息 — 点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,200 @@
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/index.js
+/** Named transcription providers with disposable registration and explicit routing. */
+/** Registry shared by all transcription consumers in one Host composition. */
+var SpeechToText = class extends Service {
+	config;
+	static Config = z.object({
+		defaultProvider: z.string().min(1).required().volatile(),
+		language: z.string().min(1).default("auto").volatile()
+	});
+	providers = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	lifetime = new AbortController();
+	/** Profile entry `configure()` writes to; absent when the plugin was mounted without Loader. */
+	entryId;
+	constructor(ctx, config) {
+		super(ctx, "speechToText");
+		this.config = config;
+		this.entryId = ctx.fiber.entry?.id;
+		ctx.on("loader/volatile-update", () => {
+			this.changed();
+		});
+		ctx.effect(() => async () => {
+			this.lifetime.abort(/* @__PURE__ */ new Error("Speech service disposed"));
+			await Promise.all([...this.providers.values()].map((registration) => this.remove(registration)));
+			this.listeners.clear();
+		});
+	}
+	/**
+	* Register one recognizer; duplicate ids fail without replacing the original.
+	* @param provider - recognizer owned by the contributing fiber.
+	* @returns idempotent disposer which rejects admission, cancels, and joins accepted work.
+	*/
+	register(provider) {
+		this.lifetime.signal.throwIfAborted();
+		if (this.providers.has(provider.info.id)) throw new Error(`Speech provider already registered: ${provider.info.id}`);
+		const registration = {
+			provider,
+			lifetime: new AbortController(),
+			pending: /* @__PURE__ */ new Set(),
+			unsubscribe: provider.preparation?.subscribe(() => {
+				this.changed();
+			}) ?? (() => {})
+		};
+		this.providers.set(provider.info.id, registration);
+		this.changed();
+		return async () => {
+			await this.remove(registration);
+		};
+	}
+	async remove(registration) {
+		if (this.providers.get(registration.provider.info.id) !== registration) return;
+		this.providers.delete(registration.provider.info.id);
+		registration.unsubscribe();
+		this.changed();
+		registration.lifetime.abort(/* @__PURE__ */ new Error("Speech provider unloaded"));
+		await Promise.allSettled(registration.pending);
+	}
+	/**
+	* Read the current recognizer roster.
+	* @returns available provider facts in registration order.
+	*/
+	listProviders() {
+		return [...this.providers.values()].map(({ provider }) => provider.info);
+	}
+	changed() {
+		for (const listener of this.listeners) listener();
+	}
+	/**
+	* Observe complete readiness snapshots; a slow reader coalesces intermediate progress.
+	* @param caller - observer lifetime, independent of any preparation task.
+	* @returns an initial snapshot followed by the latest provider states.
+	*/
+	async *follow(caller) {
+		const signal = AbortSignal.any([caller, this.lifetime.signal]);
+		signal.throwIfAborted();
+		let wake = Promise.withResolvers();
+		let changed = true;
+		const aborted = () => signal.aborted;
+		const notify = () => {
+			changed = true;
+			wake.resolve(void 0);
+		};
+		this.listeners.add(notify);
+		signal.addEventListener("abort", notify, { once: true });
+		try {
+			while (!aborted()) {
+				if (!changed) await wake.promise;
+				if (aborted()) break;
+				wake = Promise.withResolvers();
+				changed = false;
+				yield this.snapshot();
+			}
+		} finally {
+			this.listeners.delete(notify);
+			signal.removeEventListener("abort", notify);
+		}
+	}
+	/**
+	* Read provider readiness and current user preferences together.
+	* @returns one detached complete observation.
+	*/
+	snapshot() {
+		return {
+			providers: [...this.providers.values()].map(({ provider }) => ({
+				...provider.info,
+				preparation: provider.preparation?.snapshot() ?? { phase: "ready" }
+			})),
+			selection: {
+				providerId: this.config.defaultProvider.get(),
+				language: this.config.language.get()
+			}
+		};
+	}
+	/**
+	* Persist changed selection fields into this plugin's profile entry; the resulting language must be accepted by the selected provider.
+	* @param patch - explicit provider or language changes.
+	* @returns after the profile write and the live update it applies.
+	*/
+	async configure(patch) {
+		const settings = this.ctx.get("settings");
+		const entry = this.entryId;
+		if (settings === void 0 || entry === void 0) throw new Error("Speech selection requires the settings service and a profile entry");
+		const id = patch.providerId ?? this.config.defaultProvider.get();
+		this.selectedProvider(id, patch.language ?? this.config.language.get());
+		await settings.update(entry, {
+			...patch.providerId === void 0 ? {} : { defaultProvider: patch.providerId },
+			...patch.language === void 0 ? {} : { language: patch.language }
+		});
+	}
+	selectedProvider(id, language) {
+		const registration = this.providers.get(id);
+		if (!registration) throw new Error(`Speech provider is unavailable: ${id}`);
+		if (!registration.provider.info.languages.includes(language)) throw new Error(`Speech provider ${id} does not support language: ${language}`);
+		return registration.provider;
+	}
+	/**
+	* Start or join provider-owned preparation.
+	* @param id - exact registered provider identity.
+	*/
+	prepare(id) {
+		const registration = this.providers.get(id);
+		if (!registration) throw new Error(`Speech provider is unavailable: ${id}`);
+		registration.provider.preparation?.prepare();
+	}
+	/**
+	* Explicitly cancel provider preparation without tying it to a browser connection.
+	* @param id - exact registered provider identity.
+	* @returns after the preparation task settles.
+	*/
+	async cancelPreparation(id) {
+		const registration = this.providers.get(id);
+		if (!registration) throw new Error(`Speech provider is unavailable: ${id}`);
+		await registration.provider.preparation?.cancel();
+	}
+	/**
+	* Apply composition defaults and capture the selected provider. Missing providers and unsupported languages fail explicitly.
+	* @param request - complete recording and optional selection.
+	* @returns provider-pinned input for transcribe().
+	*/
+	resolve(request) {
+		const id = request.providerId ?? this.config.defaultProvider.get();
+		const language = request.language ?? this.config.language.get();
+		return {
+			provider: this.selectedProvider(id, language),
+			audio: request.audio,
+			language
+		};
+	}
+	/**
+	* Execute exactly the resolved provider; no fallback sends audio elsewhere.
+	* @param spec - resolved input; a withdrawn or replaced registration is rejected.
+	* @param signal - caller cancellation.
+	* @returns final transcript after provider settlement.
+	*/
+	async transcribe(spec, signal) {
+		signal.throwIfAborted();
+		const registration = this.providers.get(spec.provider.info.id);
+		if (registration?.provider !== spec.provider) throw new Error("Resolved speech provider is no longer registered");
+		const combined = AbortSignal.any([signal, registration.lifetime.signal]);
+		const pending = Promise.resolve().then(() => {
+			combined.throwIfAborted();
+			return spec.provider.transcribe({
+				audio: spec.audio,
+				language: spec.language
+			}, combined);
+		});
+		registration.pending.add(pending);
+		try {
+			const result = await pending;
+			combined.throwIfAborted();
+			return result;
+		} finally {
+			registration.pending.delete(pending);
+		}
+	}
+};
+//#endregion
+export { SpeechToText as default };

package/lib/types/index.d.ts

@@ -0,0 +1,91 @@
+/** Named transcription providers with disposable registration and explicit routing. */
+import { Context, Service, type Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { SpeechProvider, SpeechProviderId, SpeechProviderInfo, SpeechSnapshot, SpeechSelectionPatch, SpeechRequest, SpeechSpec, Transcript } from './types.ts';
+export type * from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Experimental speech recognition provider registry. */
+        speechToText: SpeechToText;
+    }
+}
+/** Live selection read before a transcription starts; `configure()` writes it through the profile. */
+export interface Config {
+    /** Registered provider selected when the caller omits an id. */
+    defaultProvider: Volatile<string>;
+    /** Provider language hint selected when the caller omits one. */
+    language: Volatile<string>;
+}
+/** Registry shared by all transcription consumers in one Host composition. */
+export default class SpeechToText extends Service {
+    private readonly config;
+    static Config: z<Schemastery.ObjectS<NoInfer<{
+        defaultProvider: z<string, string, "volatile-defined">;
+        language: z<string, string, "volatile-defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        defaultProvider: z<string, string, "volatile-defined">;
+        language: z<string, string, "volatile-defined">;
+    }>>, "plain">;
+    private readonly providers;
+    private readonly listeners;
+    private readonly lifetime;
+    /** Profile entry `configure()` writes to; absent when the plugin was mounted without Loader. */
+    private readonly entryId;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Register one recognizer; duplicate ids fail without replacing the original.
+     * @param provider - recognizer owned by the contributing fiber.
+     * @returns idempotent disposer which rejects admission, cancels, and joins accepted work.
+     */
+    register(provider: SpeechProvider): () => Promise<void>;
+    private remove;
+    /**
+     * Read the current recognizer roster.
+     * @returns available provider facts in registration order.
+     */
+    listProviders(): readonly SpeechProviderInfo[];
+    private changed;
+    /**
+     * Observe complete readiness snapshots; a slow reader coalesces intermediate progress.
+     * @param caller - observer lifetime, independent of any preparation task.
+     * @returns an initial snapshot followed by the latest provider states.
+     */
+    follow(caller: AbortSignal): AsyncIterable<SpeechSnapshot>;
+    /**
+     * Read provider readiness and current user preferences together.
+     * @returns one detached complete observation.
+     */
+    snapshot(): SpeechSnapshot;
+    /**
+     * Persist changed selection fields into this plugin's profile entry; the resulting language must be accepted by the selected provider.
+     * @param patch - explicit provider or language changes.
+     * @returns after the profile write and the live update it applies.
+     */
+    configure(patch: SpeechSelectionPatch): Promise<void>;
+    private selectedProvider;
+    /**
+     * Start or join provider-owned preparation.
+     * @param id - exact registered provider identity.
+     */
+    prepare(id: SpeechProviderId): void;
+    /**
+     * Explicitly cancel provider preparation without tying it to a browser connection.
+     * @param id - exact registered provider identity.
+     * @returns after the preparation task settles.
+     */
+    cancelPreparation(id: SpeechProviderId): Promise<void>;
+    /**
+     * Apply composition defaults and capture the selected provider. Missing providers and unsupported languages fail explicitly.
+     * @param request - complete recording and optional selection.
+     * @returns provider-pinned input for transcribe().
+     */
+    resolve(request: SpeechRequest): SpeechSpec;
+    /**
+     * Execute exactly the resolved provider; no fallback sends audio elsewhere.
+     * @param spec - resolved input; a withdrawn or replaced registration is rejected.
+     * @param signal - caller cancellation.
+     * @returns final transcript after provider settlement.
+     */
+    transcribe(spec: SpeechSpec, signal: AbortSignal): Promise<Transcript>;
+}
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,181 @@
+/** Named transcription providers with disposable registration and explicit routing. */
+import { Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Registry shared by all transcription consumers in one Host composition. */
+export default class SpeechToText extends Service {
+    config;
+    static Config = z.object({
+        defaultProvider: z.string().min(1).required().volatile(),
+        language: z.string().min(1).default('auto').volatile(),
+    });
+    providers = new Map();
+    listeners = new Set();
+    lifetime = new AbortController();
+    /** Profile entry `configure()` writes to; absent when the plugin was mounted without Loader. */
+    entryId;
+    constructor(ctx, config) {
+        super(ctx, 'speechToText');
+        this.config = config;
+        this.entryId = ctx.fiber.entry?.id;
+        ctx.on('loader/volatile-update', () => { this.changed(); });
+        ctx.effect(() => async () => {
+            this.lifetime.abort(new Error('Speech service disposed'));
+            await Promise.all([...this.providers.values()].map(registration => this.remove(registration)));
+            this.listeners.clear();
+        });
+    }
+    /**
+     * Register one recognizer; duplicate ids fail without replacing the original.
+     * @param provider - recognizer owned by the contributing fiber.
+     * @returns idempotent disposer which rejects admission, cancels, and joins accepted work.
+     */
+    register(provider) {
+        this.lifetime.signal.throwIfAborted();
+        if (this.providers.has(provider.info.id))
+            throw new Error(`Speech provider already registered: ${provider.info.id}`);
+        const registration = { provider, lifetime: new AbortController(), pending: new Set(),
+            unsubscribe: provider.preparation?.subscribe(() => { this.changed(); }) ?? (() => { }) };
+        this.providers.set(provider.info.id, registration);
+        this.changed();
+        return async () => { await this.remove(registration); };
+    }
+    async remove(registration) {
+        if (this.providers.get(registration.provider.info.id) !== registration)
+            return;
+        this.providers.delete(registration.provider.info.id);
+        registration.unsubscribe();
+        this.changed();
+        registration.lifetime.abort(new Error('Speech provider unloaded'));
+        await Promise.allSettled(registration.pending);
+    }
+    /**
+     * Read the current recognizer roster.
+     * @returns available provider facts in registration order.
+     */
+    listProviders() {
+        return [...this.providers.values()].map(({ provider }) => provider.info);
+    }
+    changed() { for (const listener of this.listeners)
+        listener(); }
+    /**
+     * Observe complete readiness snapshots; a slow reader coalesces intermediate progress.
+     * @param caller - observer lifetime, independent of any preparation task.
+     * @returns an initial snapshot followed by the latest provider states.
+     */
+    async *follow(caller) {
+        const signal = AbortSignal.any([caller, this.lifetime.signal]);
+        signal.throwIfAborted();
+        let wake = Promise.withResolvers();
+        let changed = true;
+        const aborted = () => signal.aborted;
+        const notify = () => { changed = true; wake.resolve(undefined); };
+        this.listeners.add(notify);
+        signal.addEventListener('abort', notify, { once: true });
+        try {
+            while (!aborted()) {
+                if (!changed)
+                    await wake.promise;
+                if (aborted())
+                    break;
+                wake = Promise.withResolvers();
+                changed = false;
+                yield this.snapshot();
+            }
+        }
+        finally {
+            this.listeners.delete(notify);
+            signal.removeEventListener('abort', notify);
+        }
+    }
+    /**
+     * Read provider readiness and current user preferences together.
+     * @returns one detached complete observation.
+     */
+    snapshot() {
+        return { providers: [...this.providers.values()].map(({ provider }) => ({ ...provider.info,
+                preparation: provider.preparation?.snapshot() ?? { phase: 'ready' },
+            })), selection: { providerId: this.config.defaultProvider.get(), language: this.config.language.get() } };
+    }
+    /**
+     * Persist changed selection fields into this plugin's profile entry; the resulting language must be accepted by the selected provider.
+     * @param patch - explicit provider or language changes.
+     * @returns after the profile write and the live update it applies.
+     */
+    async configure(patch) {
+        const settings = this.ctx.get('settings');
+        const entry = this.entryId;
+        if (settings === undefined || entry === undefined)
+            throw new Error('Speech selection requires the settings service and a profile entry');
+        const id = patch.providerId ?? this.config.defaultProvider.get();
+        this.selectedProvider(id, patch.language ?? this.config.language.get());
+        await settings.update(entry, { ...patch.providerId === undefined ? {} : { defaultProvider: patch.providerId },
+            ...patch.language === undefined ? {} : { language: patch.language } });
+    }
+    selectedProvider(id, language) {
+        const registration = this.providers.get(id);
+        if (!registration)
+            throw new Error(`Speech provider is unavailable: ${id}`);
+        if (!registration.provider.info.languages.includes(language)) {
+            throw new Error(`Speech provider ${id} does not support language: ${language}`);
+        }
+        return registration.provider;
+    }
+    /**
+     * Start or join provider-owned preparation.
+     * @param id - exact registered provider identity.
+     */
+    prepare(id) {
+        const registration = this.providers.get(id);
+        if (!registration)
+            throw new Error(`Speech provider is unavailable: ${id}`);
+        registration.provider.preparation?.prepare();
+    }
+    /**
+     * Explicitly cancel provider preparation without tying it to a browser connection.
+     * @param id - exact registered provider identity.
+     * @returns after the preparation task settles.
+     */
+    async cancelPreparation(id) {
+        const registration = this.providers.get(id);
+        if (!registration)
+            throw new Error(`Speech provider is unavailable: ${id}`);
+        await registration.provider.preparation?.cancel();
+    }
+    /**
+     * Apply composition defaults and capture the selected provider. Missing providers and unsupported languages fail explicitly.
+     * @param request - complete recording and optional selection.
+     * @returns provider-pinned input for transcribe().
+     */
+    resolve(request) {
+        const id = request.providerId ?? this.config.defaultProvider.get();
+        const language = request.language ?? this.config.language.get();
+        return { provider: this.selectedProvider(id, language), audio: request.audio, language };
+    }
+    /**
+     * Execute exactly the resolved provider; no fallback sends audio elsewhere.
+     * @param spec - resolved input; a withdrawn or replaced registration is rejected.
+     * @param signal - caller cancellation.
+     * @returns final transcript after provider settlement.
+     */
+    async transcribe(spec, signal) {
+        signal.throwIfAborted();
+        const registration = this.providers.get(spec.provider.info.id);
+        if (registration?.provider !== spec.provider)
+            throw new Error('Resolved speech provider is no longer registered');
+        const combined = AbortSignal.any([signal, registration.lifetime.signal]);
+        const pending = Promise.resolve().then(() => {
+            combined.throwIfAborted();
+            return spec.provider.transcribe({ audio: spec.audio, language: spec.language }, combined);
+        });
+        registration.pending.add(pending);
+        try {
+            const result = await pending;
+            combined.throwIfAborted();
+            return result;
+        }
+        finally {
+            registration.pending.delete(pending);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,119 @@
+/** Provider-neutral speech transcription inputs and registration metadata. */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/** Configured identity of one transcription provider. */
+export type SpeechProviderId = Branded<'SpeechProviderId'>;
+/** Provider-specific planning estimates, not measured progress or guaranteed resource limits. */
+export interface SpeechSetupEstimate {
+    readonly recommendedDiskBytes: number;
+    readonly expectedMemoryBytes: number;
+    readonly minimumMinutes: number;
+    readonly maximumMinutes: number;
+}
+/** Public provider facts; credentials and filesystem paths are excluded. */
+export interface SpeechProviderInfo {
+    readonly id: SpeechProviderId;
+    readonly name: string;
+    readonly location: 'host-local' | 'cloud';
+    /** Accepted language hints, including automatic detection when supported. */
+    readonly languages: readonly string[];
+    readonly setupEstimate?: SpeechSetupEstimate;
+}
+/** Ordered resource-preparation operations understood by the speech UI. Providers omit operations they do not need. */
+export type SpeechPreparationStepKind = 'check' | 'model' | 'vad' | 'verify' | 'load';
+/** One Host-owned operation; only its running state has a live elapsed clock. */
+export interface SpeechPreparationStep {
+    readonly kind: SpeechPreparationStepKind;
+    readonly status: 'pending' | 'running' | 'complete' | 'failed' | 'cancelled';
+    readonly startedAt?: number;
+}
+/** Safe download diagnostics for localized preparation guidance; URLs omit credentials and query strings. */
+export interface SpeechDownloadFailure {
+    readonly resource: string;
+    readonly source: string;
+    readonly reason: 'network' | 'dns' | 'timeout' | 'certificate' | 'http' | 'integrity' | 'storage' | 'unknown';
+    readonly code?: string;
+    readonly status?: number;
+}
+/** Host-owned preparation state; byte totals describe downloads, never estimated installation percentages. */
+export type SpeechPreparationState = ({
+    readonly phase: 'unprepared' | 'ready' | 'standby' | 'cancelled';
+} | {
+    readonly phase: 'downloading';
+    readonly resource: string;
+    readonly completedBytes: number;
+    readonly totalBytes?: number;
+} | {
+    readonly phase: 'checking' | 'loading' | 'waking' | 'cancelling';
+    readonly startedAt: number;
+} | {
+    readonly phase: 'failed';
+    readonly message: string;
+    readonly download?: SpeechDownloadFailure;
+}) & {
+    readonly step?: SpeechPreparationStepKind;
+    readonly steps?: readonly SpeechPreparationStep[];
+};
+/** Provider facts and its current resource readiness; independent of plugin activation. */
+export interface SpeechProviderView extends SpeechProviderInfo {
+    readonly preparation: SpeechPreparationState;
+}
+/** Host-persisted default selection captured when a recording starts. */
+export interface SpeechSelection {
+    readonly providerId: SpeechProviderId;
+    readonly language: string;
+}
+/** User intent updates only the preference fields explicitly changed. */
+export interface SpeechSelectionPatch {
+    readonly providerId?: SpeechProviderId;
+    readonly language?: string;
+}
+/** One consistent provider roster and default-selection observation. */
+export interface SpeechSnapshot {
+    readonly providers: readonly SpeechProviderView[];
+    readonly selection: SpeechSelection;
+}
+/** Optional resource preparation controls. Providers without them are immediately usable. */
+export interface SpeechPreparation {
+    /** @returns the latest Host-owned state. */
+    snapshot(): SpeechPreparationState;
+    /** @param listener - state invalidation callback. @returns subscription disposer. */
+    subscribe(listener: () => void): () => void;
+    /** Start or join the current preparation task; page and transport lifetimes do not own it. */
+    prepare(): void;
+    /** Cancel preparation. @returns after its resources settle. */
+    cancel(): Promise<void>;
+}
+/** Complete audio recording and an explicit language hint. */
+export interface SpeechInput {
+    readonly audio: Uint8Array;
+    readonly language: string;
+}
+/** Final transcription; an empty string means no speech was recognized. */
+export interface Transcript {
+    readonly text: string;
+    readonly audioSeconds: number;
+    readonly inferenceSeconds: number;
+}
+/** One replaceable recognizer. It owns preparation, execution, and cancellation. */
+export interface SpeechProvider {
+    readonly info: SpeechProviderInfo;
+    readonly preparation?: SpeechPreparation;
+    /**
+     * Recognize one complete recording without submitting an Agent message.
+     * @param input - WAV bytes and language, borrowed until settlement.
+     * @param signal - caller or registration cancellation; rejection follows resource cleanup.
+     * @returns final text and measured audio/inference durations.
+     */
+    transcribe(input: SpeechInput, signal: AbortSignal): Promise<Transcript>;
+}
+/** Caller selection before composition defaults are resolved. */
+export interface SpeechRequest {
+    readonly audio: Uint8Array;
+    readonly providerId?: SpeechProviderId;
+    readonly language?: string;
+}
+/** Resolved selection pins the exact registered provider, including its lifetime. */
+export interface SpeechSpec extends SpeechInput {
+    readonly provider: SpeechProvider;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

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

package/lib/types/wave.d.ts

@@ -0,0 +1,9 @@
+/** Validate browser PCM WAV headers before retaining or forwarding audio. */
+/**
+ * Read a canonical 16 kHz mono PCM16 WAV recording, rejecting inconsistent lengths.
+ * @param audio - decoded wire bytes.
+ * @param maxDurationSeconds - maximum admitted recording duration.
+ * @returns complete recording duration in seconds.
+ */
+export declare function validateWave(audio: Uint8Array, maxDurationSeconds: number): number;
+//# sourceMappingURL=wave.d.ts.map

package/lib/types/wave.js

@@ -0,0 +1,24 @@
+/** Validate browser PCM WAV headers before retaining or forwarding audio. */
+/**
+ * Read a canonical 16 kHz mono PCM16 WAV recording, rejecting inconsistent lengths.
+ * @param audio - decoded wire bytes.
+ * @param maxDurationSeconds - maximum admitted recording duration.
+ * @returns complete recording duration in seconds.
+ */
+export function validateWave(audio, maxDurationSeconds) {
+    const data = Buffer.from(audio.buffer, audio.byteOffset, audio.byteLength);
+    if (data.length < 46 || data.toString('ascii', 0, 4) !== 'RIFF'
+        || data.toString('ascii', 8, 12) !== 'WAVE' || data.toString('ascii', 12, 16) !== 'fmt '
+        || data.readUInt32LE(16) !== 16 || data.readUInt16LE(20) !== 1 || data.readUInt16LE(22) !== 1
+        || data.readUInt32LE(24) !== 16000 || data.readUInt32LE(28) !== 32000
+        || data.readUInt16LE(32) !== 2 || data.readUInt16LE(34) !== 16
+        || data.toString('ascii', 36, 40) !== 'data' || data.readUInt32LE(4) !== data.length - 8
+        || data.readUInt32LE(40) !== data.length - 44 || (data.length - 44) % 2 !== 0) {
+        throw new Error('Audio must be a canonical 16 kHz mono PCM16 WAV recording');
+    }
+    const seconds = (data.length - 44) / 32000;
+    if (seconds > maxDurationSeconds)
+        throw new Error(`Audio exceeds ${maxDurationSeconds} seconds`);
+    return seconds;
+}
+//# sourceMappingURL=wave.js.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@deepseek-ai/dsh-experimental-speech-to-text",
+  "description": "Experimental speech recognition with independently selectable providers",
+  "version": "0.1.7-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/experimental/speech-to-text"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./wave": {
+      "types": "./lib/types/wave.d.ts",
+      "default": "./lib/types/wave.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-brand": "^0.1.7-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-settings": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.4",
+    "@deepseek-ai/cordis": "^4.0.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-settings": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.4"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis-plugin-loader": {
+      "optional": true
+    }
+  }
+}