handmux 0.26.0 → 0.27.2

package/dist/src/agents/nativeInbox.js

@@ -1,9 +1,3 @@
-import { createHash } from 'node:crypto';
-function attachmentId(sourceId, candidate) {
-    return `${sourceId}:${createHash('sha256').update(JSON.stringify({
-        paneId: candidate.paneId, process: candidate.process,
-    })).digest('hex')}`;
-}
 function operation(sourceId, row) {
     const base = {
         source: { sourceId, cursor: row.cursor },
@@ -87,9 +81,7 @@ export class NativeInboxCoordinator {
             clearTimeout(this.#timer);
         this.#timer = undefined;
         await this.#tail.catch(() => { });
-        const tracked = [...this.#tracked.values()];
         this.#tracked.clear();
-        await Promise.all(tracked.map((entry) => (this.#context.runControl.revoke(entry.lease, 'adapter_stopped').catch(() => { }))));
     }
     reconcile() {
         const pending = this.#tail.then(() => this.#reconcile());
@@ -151,8 +143,8 @@ export class NativeInboxCoordinator {
         let topologyChanged = !this.#baselineReady;
         const rows = new Map(snapshot.rows.map((row) => [row.paneId, structuredClone(row)]));
         // Root Runtime independently revokes a run when its foreground-process proof changes. A coordinator
-        // entry must not outlive that lease: retaining it makes this loop skip re-attach forever, then feeds a
-        // revoked run into Inbox.restore() and blocks every healthy pane in the same provider snapshot.
+        // entry must not outlive that lease: retaining it feeds a revoked run into Inbox.restore() and blocks
+        // every healthy pane in the same provider snapshot.
         for (const [paneId, tracked] of [...this.#tracked]) {
             if (!tracked.lease.signal.aborted
                 && this.#context.runs.resolve(tracked.lease.ref) === tracked.lease)
@@ -160,74 +152,50 @@ export class NativeInboxCoordinator {
             this.#tracked.delete(paneId);
             topologyChanged = true;
         }
-        for (const [paneId, tracked] of [...this.#tracked]) {
+        for (const [paneId] of [...this.#tracked]) {
             if (rows.has(paneId))
                 continue;
             this.#tracked.delete(paneId);
-            await this.#context.runControl.revoke(tracked.lease, 'adapter_stopped').catch(() => { });
             topologyChanged = true;
         }
-        let attachmentError;
+        let associationError;
         for (const row of rows.values()) {
             try {
-                const pane = paneMap.get(row.paneId);
-                const process = await this.#context.process.inspectForeground(pane);
-                if (!process)
-                    throw new Error(`${this.#agentId} foreground process is unavailable`);
-                const candidateBase = {
-                    paneId: row.paneId,
-                    ...(row.sessionId === undefined ? {} : { sessionId: row.sessionId }),
-                    process: {
-                        pid: process.pid,
-                        ...(process.startedAt === undefined ? {} : { startedAt: process.startedAt }),
-                        ...(process.tty === undefined ? (pane.tty === undefined ? {} : { tty: pane.tty }) : { tty: process.tty }),
-                    },
-                };
-                const nextAttachmentId = attachmentId(this.#sourceId, candidateBase);
-                const candidate = { ...candidateBase, attachmentId: nextAttachmentId };
-                let tracked = this.#tracked.get(row.paneId);
-                if (!tracked) {
-                    const lease = await this.#context.runControl.attach(candidate);
-                    tracked = {
-                        lease, projector: this.#context.inbox.forRun(lease),
-                        attachmentId: nextAttachmentId, row,
-                    };
-                    this.#tracked.set(row.paneId, tracked);
+                let lease = this.#context.currentRunForPane(row.paneId);
+                if (!lease || lease.ref.agentId !== this.#agentId
+                    || this.#context.runs.resolve(lease.ref) !== lease) {
+                    // A stale socket/source row is not process ownership evidence. Runtime will retry process
+                    // discovery independently; until then this row must not create or degrade a run.
+                    rows.delete(row.paneId);
+                    continue;
+                }
+                if (row.sessionId !== undefined && lease.ref.sessionId === undefined) {
+                    await this.#context.runControl.associateSession(lease, row.sessionId);
                     topologyChanged = true;
                 }
-                else if (tracked.attachmentId !== nextAttachmentId) {
-                    const lease = await this.#context.runControl.attach(candidate);
-                    tracked = {
-                        lease, projector: this.#context.inbox.forRun(lease),
-                        attachmentId: nextAttachmentId, row,
-                    };
-                    this.#tracked.set(row.paneId, tracked);
+                else if (row.sessionId !== undefined && lease.ref.sessionId !== row.sessionId) {
+                    lease = await this.#context.runControl.replaceSession(lease, row.sessionId);
                     topologyChanged = true;
                 }
-                else if (tracked.lease.ref.sessionId !== undefined && row.sessionId !== undefined
-                    && tracked.lease.ref.sessionId !== row.sessionId) {
-                    const lease = await this.#context.runControl.replace(tracked.lease, candidate, 'session_replaced');
+                let tracked = this.#tracked.get(row.paneId);
+                if (!tracked || tracked.lease !== lease) {
                     tracked = {
                         lease, projector: this.#context.inbox.forRun(lease),
-                        attachmentId: nextAttachmentId, row,
+                        row,
                     };
                     this.#tracked.set(row.paneId, tracked);
                     topologyChanged = true;
                 }
-                else if (tracked.lease.ref.sessionId === undefined && row.sessionId !== undefined) {
-                    await this.#context.runControl.associateSession(tracked.lease, row.sessionId);
-                    topologyChanged = true;
-                }
             }
             catch (error) {
-                // One transient/invalid pane must not suppress every other pane from the same provider. Keep any
-                // previously verified row, exclude only the failed newcomer from this cycle, and retry next poll.
+                // One stale run/session association must not suppress every other pane from the same provider.
+                // Keep any previously projected row and retry after Runtime has reconciled process ownership.
                 rows.delete(row.paneId);
-                attachmentError ??= error instanceof Error ? error.message : String(error);
+                associationError ??= error instanceof Error ? error.message : String(error);
             }
         }
-        const effectiveAvailability = attachmentError ? 'degraded' : snapshot.availability;
-        const effectiveMessage = attachmentError ?? snapshot.message;
+        const effectiveAvailability = associationError ? 'degraded' : snapshot.availability;
+        const effectiveMessage = associationError ?? snapshot.message;
         const availabilityChanged = this.#availability !== effectiveAvailability
             || this.#availabilityMessage !== effectiveMessage;
         const restoreNeeded = topologyChanged || availabilityChanged;

package/dist/src/agents/scanUtils.js

@@ -14,7 +14,13 @@ const isRecord = (value) => value !== null && typeof value === 'object';
 // Detection is best-effort and must never throw the whole request.
 export function defaultRun(cmd, args) {
     return new Promise((resolve) => {
-        execFile(cmd, args, { maxBuffer: 8 * 1024 * 1024 }, (err, stdout) => {
+        // These commands are parsed as machine output. Inherited locales can translate fields such as
+        // macOS `ps lstart` (for example Chinese weekday/month names), making otherwise stable output
+        // unparsable and leaving safety-critical process identities incomplete.
+        execFile(cmd, args, {
+            maxBuffer: 8 * 1024 * 1024,
+            env: { ...process.env, LC_ALL: 'C' },
+        }, (err, stdout) => {
             resolve(err ? '' : String(stdout));
         });
     });

package/dist/src/apiErrors.js

@@ -3,13 +3,19 @@ export class PublicApiError extends Error {
     status;
     code;
     retryAfterSeconds;
-    constructor(status, code, message, retryAfterSeconds) {
+    providerRequestId;
+    logFields;
+    constructor(status, code, message, retryAfterSeconds, diagnostics = {}) {
         super(message);
         this.name = 'PublicApiError';
         this.status = status;
         this.code = code;
         if (retryAfterSeconds !== undefined)
             this.retryAfterSeconds = retryAfterSeconds;
+        if (diagnostics.providerRequestId)
+            this.providerRequestId = diagnostics.providerRequestId;
+        if (diagnostics.logFields)
+            this.logFields = diagnostics.logFields;
     }
 }
 function requestIdFor(locals, idFactory) {
@@ -68,6 +74,7 @@ export function apiErrorBoundary({ idFactory = randomUUID, log = console, } = {}
         }
         if (status >= 500) {
             log.error('[handmux] api error', {
+                ...(error instanceof PublicApiError ? error.logFields : {}),
                 requestId,
                 method: req.method,
                 path: req.originalUrl,
@@ -80,6 +87,8 @@ export function apiErrorBoundary({ idFactory = randomUUID, log = console, } = {}
         const body = {
             error: message, code, requestId,
             ...(retryAfterSeconds === undefined ? {} : { retryAfterSeconds }),
+            ...(error instanceof PublicApiError && error.providerRequestId
+                ? { providerRequestId: error.providerRequestId } : {}),
         };
         res.status(status).json(body);
     };

package/dist/src/asr/config.js

@@ -0,0 +1,29 @@
+import { providerMode, voiceProviderRegistry } from './providerRegistry.js';
+// HANDMUX_ASR_PROVIDER selects exactly one configured provider. Without it, keep legacy XFYUN_* installs
+// working; a Tencent-only environment is also detected for direct server launches.
+export function asrConfigFromRegistry(env, registry) {
+    const selected = env.HANDMUX_ASR_PROVIDER;
+    if (selected) {
+        const adapter = registry.get(selected);
+        if (!adapter)
+            return null;
+        const config = adapter.readConfig(env, providerMode(adapter, env.HANDMUX_ASR_MODE));
+        return adapter.isConfigured(config) ? config : null;
+    }
+    for (const provider of ['xfyun', ...registry.adapters
+            .map((adapter) => adapter.id).filter((id) => id !== 'xfyun')]) {
+        const adapter = registry.get(provider);
+        if (!adapter)
+            continue;
+        const config = adapter.readConfig(env, adapter.defaultMode);
+        if (adapter.isConfigured(config))
+            return config;
+    }
+    return null;
+}
+export function asrConfig(env = process.env) {
+    return asrConfigFromRegistry(env, voiceProviderRegistry);
+}
+export function isAsrConfigured(env = process.env) {
+    return asrConfig(env) !== null;
+}

package/dist/src/asr/providerRegistry.js

@@ -0,0 +1,19 @@
+import { tencentAdapter } from './providers/tencent.js';
+import { xfyunAdapter } from './providers/xfyun.js';
+export function createVoiceProviderRegistry(adapters) {
+    const byId = new Map();
+    for (const adapter of adapters) {
+        if (!adapter.id || byId.has(adapter.id))
+            throw new Error(`duplicate voice provider: ${adapter.id}`);
+        byId.set(adapter.id, adapter);
+    }
+    return {
+        adapters: [...adapters],
+        get: (id) => typeof id === 'string' ? byId.get(id) : undefined,
+    };
+}
+export const voiceProviderRegistry = createVoiceProviderRegistry([tencentAdapter, xfyunAdapter]);
+export function providerMode(adapter, value) {
+    return adapter.profiles.some((profile) => profile.mode === value)
+        ? value : adapter.defaultMode;
+}

package/dist/src/asr/providers/tencent.js

@@ -0,0 +1,135 @@
+import { recognizeTencentSentence, TencentSentenceEmptyResultError, TencentSentenceError, } from '../tencentSentence.js';
+import { buildTencentAsrSignedUrl } from '../tencentSign.js';
+import { silentPcmProbe, verifyStreamingConnection, VoiceVerificationError, } from '../verify.js';
+const FILTER_MODAL = {
+    low: '0', medium: '1', high: '2',
+};
+async function verifyTencentStreamingConfig(config, dependencies) {
+    const session = buildTencentAsrSignedUrl({ ...config, filterModal: '1' });
+    await verifyStreamingConnection({
+        url: session.url,
+        sendOnOpen: (socket) => {
+            socket.send(silentPcmProbe().subarray(0, 1_280));
+            socket.send(JSON.stringify({ type: 'end' }));
+        },
+        acceptMessage: (message) => {
+            let value;
+            try {
+                value = JSON.parse(message);
+            }
+            catch {
+                throw new VoiceVerificationError('invalid_response', 'provider returned an invalid response');
+            }
+            const root = value && typeof value === 'object' ? value : {};
+            if (typeof root.code !== 'number') {
+                throw new VoiceVerificationError('invalid_response', 'provider returned an invalid response');
+            }
+            if (root.code !== 0) {
+                throw new VoiceVerificationError(`tencent_${root.code}`, `Tencent Cloud ASR rejected the configuration (${root.code}): ${String(root.message || 'unknown error')}`);
+            }
+            return true;
+        },
+    }, dependencies);
+}
+export async function verifyTencentAsr(config, dependencies = {}) {
+    const timeoutMs = dependencies.timeoutMs ?? 8_000;
+    const startedAt = Date.now();
+    // SentenceRecognition authenticates SecretId/SecretKey but has no AppId parameter. Probe the signed
+    // streaming endpoint first so a mistyped AppId cannot produce a false-positive sentence verification.
+    await verifyTencentStreamingConfig(config, { ...dependencies, timeoutMs });
+    if (config.mode === 'streaming') {
+        return;
+    }
+    const remainingMs = timeoutMs - (Date.now() - startedAt);
+    if (remainingMs <= 0) {
+        throw new VoiceVerificationError('verification_timeout', 'provider verification timed out');
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), remainingMs);
+    try {
+        await recognizeTencentSentence(config, silentPcmProbe(), {
+            ...(dependencies.fetch ? { fetch: dependencies.fetch } : {}),
+            filterModal: 1, signal: controller.signal,
+        });
+    }
+    catch (error) {
+        if (controller.signal.aborted) {
+            throw new VoiceVerificationError('verification_timeout', 'provider verification timed out');
+        }
+        // The verification probe is deliberately silent. An empty recognition proves the signed request,
+        // credentials, permission, and model were all accepted, so it is a successful configuration check.
+        if (error instanceof TencentSentenceEmptyResultError)
+            return;
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+export const tencentAdapter = {
+    id: 'tencent',
+    defaultMode: 'streaming',
+    fields: [
+        { key: 'appId', env: 'TENCENT_ASR_APPID', promptKey: 'setup.voiceTencentAppId' },
+        { key: 'secretId', env: 'TENCENT_ASR_SECRET_ID', promptKey: 'setup.voiceTencentSecretId', secret: true },
+        { key: 'secretKey', env: 'TENCENT_ASR_SECRET_KEY', promptKey: 'setup.voiceTencentSecretKey', secret: true },
+        {
+            key: 'engineModelType', env: 'TENCENT_ASR_ENGINE_MODEL_TYPE',
+            promptKey: 'setup.voiceTencentEngine', defaultValue: '16k_zh',
+        },
+    ],
+    profiles: [
+        { mode: 'streaming', labelKey: 'setup.voiceTencent', hintKey: 'setup.voiceTencentHint' },
+        {
+            mode: 'sentence', labelKey: 'setup.voiceTencentSentence',
+            hintKey: 'setup.voiceTencentSentenceHint',
+        },
+    ],
+    capabilities: { fillerFilter: true },
+    readConfig: (env, mode) => ({
+        provider: 'tencent', mode,
+        appId: env.TENCENT_ASR_APPID || '',
+        secretId: env.TENCENT_ASR_SECRET_ID || '',
+        secretKey: env.TENCENT_ASR_SECRET_KEY || '',
+        engineModelType: env.TENCENT_ASR_ENGINE_MODEL_TYPE || '16k_zh',
+    }),
+    isConfigured: (config) => config.provider === 'tencent'
+        && !!(config.appId && config.secretId && config.secretKey && config.engineModelType),
+    verify: (config) => {
+        if (config.provider !== 'tencent')
+            throw new Error('tencent adapter received another provider config');
+        return verifyTencentAsr(config);
+    },
+    createStreamingSession: (config, options) => {
+        if (config.provider !== 'tencent')
+            throw new Error('tencent adapter received another provider config');
+        return {
+            provider: 'tencent', protocol: 'tencent-asr-v2',
+            ...buildTencentAsrSignedUrl({
+                ...config,
+                filterModal: FILTER_MODAL[options.fillerFilter],
+            }),
+        };
+    },
+    recognizeSentence: (config, audio, options) => {
+        if (config.provider !== 'tencent')
+            throw new Error('tencent adapter received another provider config');
+        return recognizeTencentSentence(config, audio, {
+            filterModal: Number(FILTER_MODAL[options.fillerFilter]),
+        });
+    },
+    publicError: (error) => error instanceof TencentSentenceError ? {
+        message: error.message,
+        code: error.code,
+        ...(error.requestId ? { providerRequestId: error.requestId } : {}),
+        ...(error instanceof TencentSentenceEmptyResultError ? {
+            logFields: {
+                provider: 'tencent',
+                mode: 'sentence',
+                ...(error.requestId ? { providerRequestId: error.requestId } : {}),
+                audioByteLength: error.audioByteLength,
+                audioDurationMs: error.audioDurationMs,
+            },
+        } : {}),
+    } : null,
+};

package/dist/src/asr/providers/xfyun.js

@@ -0,0 +1,73 @@
+import { buildIatSignedUrl } from '../iflySign.js';
+import { silentPcmProbe, verifyStreamingConnection, VoiceVerificationError, } from '../verify.js';
+const XFYUN_BUSINESS = {
+    language: 'zh_cn', domain: 'iat', accent: 'mandarin', vad_eos: 10_000,
+    dwa: 'wpgs', ptt: 1, nunum: 1,
+};
+const XFYUN_FORMAT = 'audio/L16;rate=16000';
+export async function verifyXfyunAsr(config, dependencies = {}) {
+    const session = buildIatSignedUrl({ ...config, date: new Date().toUTCString() });
+    const audio = Buffer.from(silentPcmProbe().subarray(0, 1_280)).toString('base64');
+    await verifyStreamingConnection({
+        url: session.url,
+        sendOnOpen: (socket) => {
+            socket.send(JSON.stringify({
+                common: { app_id: config.appId },
+                business: XFYUN_BUSINESS,
+                data: { status: 0, format: XFYUN_FORMAT, encoding: 'raw', audio },
+            }));
+            socket.send(JSON.stringify({
+                data: { status: 2, format: XFYUN_FORMAT, encoding: 'raw', audio: '' },
+            }));
+        },
+        acceptMessage: (message) => {
+            let value;
+            try {
+                value = JSON.parse(message);
+            }
+            catch {
+                throw new VoiceVerificationError('invalid_response', 'provider returned an invalid response');
+            }
+            const root = value && typeof value === 'object' ? value : {};
+            if (typeof root.code !== 'number') {
+                throw new VoiceVerificationError('invalid_response', 'provider returned an invalid response');
+            }
+            if (root.code !== 0) {
+                throw new VoiceVerificationError(`xfyun_${root.code}`, `XFYUN rejected the configuration (${root.code}): ${String(root.message || 'unknown error')}`);
+            }
+            return true;
+        },
+    }, dependencies);
+}
+export const xfyunAdapter = {
+    id: 'xfyun',
+    defaultMode: 'streaming',
+    fields: [
+        { key: 'appId', env: 'XFYUN_APPID', promptKey: 'setup.voiceAppId' },
+        { key: 'apiKey', env: 'XFYUN_APIKEY', promptKey: 'setup.voiceApiKey', secret: true },
+        { key: 'apiSecret', env: 'XFYUN_APISECRET', promptKey: 'setup.voiceApiSecret', secret: true },
+    ],
+    profiles: [
+        { mode: 'streaming', labelKey: 'setup.voiceXfyun', hintKey: 'setup.voiceXfyunHint' },
+    ],
+    readConfig: (env) => ({
+        provider: 'xfyun', mode: 'streaming',
+        appId: env.XFYUN_APPID || '', apiKey: env.XFYUN_APIKEY || '', apiSecret: env.XFYUN_APISECRET || '',
+    }),
+    isConfigured: (config) => config.provider === 'xfyun'
+        && !!(config.appId && config.apiKey && config.apiSecret),
+    verify: (config) => {
+        if (config.provider !== 'xfyun')
+            throw new Error('xfyun adapter received another provider config');
+        return verifyXfyunAsr(config);
+    },
+    createStreamingSession: (config) => {
+        if (config.provider !== 'xfyun')
+            throw new Error('xfyun adapter received another provider config');
+        const credentials = config;
+        return {
+            provider: 'xfyun', protocol: 'xfyun-iat-v2',
+            ...buildIatSignedUrl({ ...credentials, date: new Date().toUTCString() }),
+        };
+    },
+};

package/dist/src/asr/tencentSentence.js

@@ -0,0 +1,111 @@
+import { createHash, createHmac } from 'node:crypto';
+const HOST = 'asr.tencentcloudapi.com';
+const ENDPOINT = `https://${HOST}`;
+const ACTION = 'SentenceRecognition';
+const VERSION = '2019-06-14';
+const SERVICE = 'asr';
+const ALGORITHM = 'TC3-HMAC-SHA256';
+const CONTENT_TYPE = 'application/json; charset=utf-8';
+export class TencentSentenceError extends Error {
+    code;
+    requestId;
+    constructor(code, message, requestId) {
+        super(message);
+        this.name = 'TencentSentenceError';
+        this.code = code;
+        if (requestId)
+            this.requestId = requestId;
+    }
+}
+export class TencentSentenceEmptyResultError extends TencentSentenceError {
+    audioByteLength;
+    audioDurationMs;
+    constructor(audioByteLength, requestId) {
+        super('speech_not_recognized', 'Tencent Cloud ASR did not recognize any speech', requestId);
+        this.name = 'TencentSentenceEmptyResultError';
+        this.audioByteLength = audioByteLength;
+        // SentenceRecognition receives 16 kHz, mono, signed 16-bit PCM: 32 bytes per millisecond.
+        this.audioDurationMs = audioByteLength / 32;
+    }
+}
+const isRecord = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value));
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+const hmac = (key, value) => (createHmac('sha256', key).update(value).digest());
+function utcDate(timestamp) {
+    return new Date(timestamp * 1000).toISOString().slice(0, 10);
+}
+export function buildTencentSentenceRequest(config, audio, timestamp = Math.floor(Date.now() / 1000), filterModal = 1) {
+    const body = JSON.stringify({
+        ProjectId: 0,
+        SubServiceType: 2,
+        EngSerViceType: config.engineModelType,
+        SourceType: 1,
+        VoiceFormat: 'pcm',
+        FilterModal: filterModal,
+        Data: Buffer.from(audio).toString('base64'),
+        DataLen: audio.byteLength,
+    });
+    const canonicalHeaders = `content-type:${CONTENT_TYPE}\nhost:${HOST}\n`;
+    const signedHeaders = 'content-type;host';
+    const canonicalRequest = [
+        'POST', '/', '', canonicalHeaders, signedHeaders, sha256(body),
+    ].join('\n');
+    const date = utcDate(timestamp);
+    const credentialScope = `${date}/${SERVICE}/tc3_request`;
+    const stringToSign = [
+        ALGORITHM, String(timestamp), credentialScope, sha256(canonicalRequest),
+    ].join('\n');
+    const secretDate = hmac(`TC3${config.secretKey}`, date);
+    const secretService = hmac(secretDate, SERVICE);
+    const secretSigning = hmac(secretService, 'tc3_request');
+    const signature = createHmac('sha256', secretSigning).update(stringToSign).digest('hex');
+    const authorization = `${ALGORITHM} Credential=${config.secretId}/${credentialScope}, `
+        + `SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    return {
+        url: ENDPOINT,
+        headers: {
+            Authorization: authorization,
+            'Content-Type': CONTENT_TYPE,
+            Host: HOST,
+            'X-TC-Action': ACTION,
+            'X-TC-Timestamp': String(timestamp),
+            'X-TC-Version': VERSION,
+        },
+        body,
+    };
+}
+export async function recognizeTencentSentence(config, audio, { fetch: fetchImpl = fetch, timestamp, filterModal = 1, signal } = {}) {
+    const request = buildTencentSentenceRequest(config, audio, timestamp, filterModal);
+    let response;
+    try {
+        response = await fetchImpl(request.url, {
+            method: 'POST', headers: request.headers, body: request.body,
+            ...(signal ? { signal } : {}),
+        });
+    }
+    catch (error) {
+        throw new TencentSentenceError('TencentNetworkError', `Tencent Cloud ASR could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let value;
+    try {
+        value = await response.json();
+    }
+    catch {
+        throw new TencentSentenceError('TencentInvalidResponse', `Tencent Cloud ASR returned HTTP ${response.status} with an invalid response`);
+    }
+    const root = isRecord(value) && isRecord(value.Response) ? value.Response : null;
+    const requestId = typeof root?.RequestId === 'string' ? root.RequestId : undefined;
+    const cloudError = isRecord(root?.Error) ? root.Error : null;
+    if (cloudError) {
+        const code = typeof cloudError.Code === 'string' ? cloudError.Code : 'TencentCloudError';
+        const message = typeof cloudError.Message === 'string' ? cloudError.Message : 'Tencent Cloud ASR rejected the request';
+        throw new TencentSentenceError(code, message, requestId);
+    }
+    if (!response.ok || !root || typeof root.Result !== 'string') {
+        throw new TencentSentenceError('TencentInvalidResponse', `Tencent Cloud ASR returned an invalid response (HTTP ${response.status})`, requestId);
+    }
+    if (root.Result.trim() === '') {
+        throw new TencentSentenceEmptyResultError(audio.byteLength, requestId);
+    }
+    return { text: root.Result, ...(requestId ? { requestId } : {}) };
+}

package/dist/src/asr/tencentSign.js

@@ -0,0 +1,20 @@
+import { createHmac, randomInt, randomUUID } from 'node:crypto';
+// Tencent Real-time ASR WebSocket 2.0. The signature covers host/path and the key-sorted raw query;
+// only the resulting short-lived URL leaves the server.
+export function buildTencentAsrSignedUrl({ appId, secretId, secretKey, engineModelType = '16k_zh', filterModal = '1', host = 'asr.cloud.tencent.com', timestamp = Math.floor(Date.now() / 1000), expired = timestamp + 300, nonce = randomInt(100000, 1000000), voiceId = randomUUID(), }) {
+    const params = {
+        engine_model_type: engineModelType,
+        expired: String(expired),
+        filter_modal: filterModal,
+        nonce: String(nonce),
+        secretid: secretId,
+        speaker_diarization: '0',
+        timestamp: String(timestamp),
+        voice_format: '1',
+        voice_id: voiceId,
+    };
+    const query = Object.keys(params).sort().map((key) => `${key}=${params[key]}`).join('&');
+    const signingText = `${host}/asr/v2/${appId}?${query}`;
+    const signature = createHmac('sha1', secretKey).update(signingText).digest('base64');
+    return { url: `wss://${signingText}&signature=${encodeURIComponent(signature)}` };
+}

package/dist/src/asr/verify.js

@@ -0,0 +1,80 @@
+import WebSocket from 'ws';
+export class VoiceVerificationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'VoiceVerificationError';
+        this.code = code;
+    }
+}
+const socketMessage = (data) => {
+    if (typeof data === 'string')
+        return data;
+    if (Buffer.isBuffer(data))
+        return data.toString('utf8');
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data).toString('utf8');
+    if (ArrayBuffer.isView(data)) {
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString('utf8');
+    }
+    if (Array.isArray(data) && data.every(Buffer.isBuffer))
+        return Buffer.concat(data).toString('utf8');
+    return String(data);
+};
+// Opens the provider's real signed endpoint with a short, hard timeout. Provider adapters own the frames
+// and response semantics; this helper owns only the shared socket lifecycle and never includes the signed URL
+// in an error, so credentials and signed query material cannot leak into setup output.
+export function verifyStreamingConnection(verification, { socketFactory = (url) => new WebSocket(url), timeoutMs = 8_000 } = {}) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let socket;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                socket?.terminate();
+            }
+            catch { /* already closed */ }
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const timer = setTimeout(() => finish(new VoiceVerificationError('verification_timeout', 'provider verification timed out')), timeoutMs);
+        try {
+            socket = socketFactory(verification.url);
+        }
+        catch {
+            finish(new VoiceVerificationError('connection_failed', 'could not open provider connection'));
+            return;
+        }
+        socket.on('open', () => {
+            try {
+                verification.sendOnOpen?.(socket);
+                if (verification.successOnOpen)
+                    finish();
+            }
+            catch {
+                finish(new VoiceVerificationError('probe_failed', 'could not send provider verification data'));
+            }
+        });
+        socket.on('message', (data) => {
+            try {
+                if (verification.acceptMessage?.(socketMessage(data)))
+                    finish();
+            }
+            catch (error) {
+                finish(error instanceof Error ? error
+                    : new VoiceVerificationError('provider_rejected', 'provider rejected the configuration'));
+            }
+        });
+        socket.on('unexpected-response', (_request, response) => finish(new VoiceVerificationError('handshake_rejected', `provider rejected the WebSocket handshake${response.statusCode ? ` (HTTP ${response.statusCode})` : ''}`)));
+        socket.on('error', () => finish(new VoiceVerificationError('connection_failed', 'could not connect to the provider')));
+        socket.on('close', (code) => finish(new VoiceVerificationError('connection_closed', `provider closed the verification connection (code ${code})`)));
+    });
+}
+// One second of 16 kHz mono signed 16-bit PCM. It contains no user audio and forms a valid request body
+// while keeping validation cost and transfer size minimal.
+export const silentPcmProbe = () => new Uint8Array(16_000 * 2);