dsh-live-voice 0.0.1-developing → 0.0.2

package/src/engines/speaking/say.ts

@@ -0,0 +1,271 @@
+// @ts-nocheck
+import { spawn as nodeSpawn } from 'node:child_process';
+import * as nodeFs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+function failure(message, code, cause) {
+  return Object.assign(new Error(message, cause === undefined ? undefined : { cause }), { code });
+}
+function aborted(reason) {
+  return Object.assign(
+    new Error('Speech cancelled', reason === undefined ? undefined : { cause: reason }),
+    {
+      name: 'AbortError',
+      code: 'ABORT_ERR',
+    },
+  );
+}
+
+/** Local macOS adapter. No transcript is placed in argv or diagnostic messages.
+ * fs is the node:fs/promises interface; spawn returns a Node ChildProcess.
+ * A replacement cancels all earlier requests, and waits for their cleanup.
+ */
+export class SayEngine {
+  #spawn;
+  #fs;
+  #platform;
+  #tempRoot;
+  #killAfterMs;
+  #closeAfterMs;
+  #tail = Promise.resolve();
+  #requests = new Set();
+  #active = null;
+  #unclosed = null;
+  #state = 'idle';
+  #lastError = null;
+
+  constructor({
+    spawn = nodeSpawn,
+    fs = nodeFs,
+    platform = process.platform,
+    tempRoot = tmpdir(),
+    killAfterMs = 250,
+    closeAfterMs = 1000,
+  } = {}) {
+    for (const value of [killAfterMs, closeAfterMs]) {
+      if (!Number.isFinite(value) || value < 0 || value > 2147483647) {
+        throw new TypeError('Cancellation deadlines must be finite nonnegative milliseconds');
+      }
+    }
+    this.#spawn = spawn;
+    this.#fs = fs;
+    this.#platform = platform;
+    this.#tempRoot = tempRoot;
+    this.#killAfterMs = killAfterMs;
+    this.#closeAfterMs = closeAfterMs;
+  }
+
+  get state() {
+    return this.#state;
+  }
+  get lastError() {
+    return this.#lastError;
+  }
+
+  /** Checks the host executable, not browser support or installed voices. */
+  async getCapabilities() {
+    if (this.#platform !== 'darwin') {
+      return { supported: false, pause: false, resume: false, reason: 'unsupported-platform' };
+    }
+    try {
+      await this.#fs.access('/usr/bin/say', constants.X_OK);
+      return { supported: true, pause: true, resume: true, reason: null };
+    } catch {
+      return { supported: false, pause: false, resume: false, reason: 'executable-unavailable' };
+    }
+  }
+
+  speak(text, { voice, rate, signal } = {}) {
+    if (typeof text !== 'string') return Promise.reject(new TypeError('text must be a string'));
+    if (
+      voice !== undefined &&
+      (typeof voice !== 'string' || !voice.trim() || voice.includes('\0'))
+    ) {
+      return Promise.reject(new TypeError('voice must be a nonempty string without NUL'));
+    }
+    if (rate !== undefined && (!Number.isFinite(rate) || rate <= 0)) {
+      return Promise.reject(new TypeError('rate must be a positive finite number'));
+    }
+    if (
+      signal !== undefined &&
+      (signal === null ||
+        typeof signal.addEventListener !== 'function' ||
+        typeof signal.removeEventListener !== 'function' ||
+        typeof signal.aborted !== 'boolean')
+    ) {
+      return Promise.reject(new TypeError('signal must be an AbortSignal'));
+    }
+    for (const request of this.#requests) this.#cancel(request);
+    const request = { cancelled: false, reason: undefined, cancelChild: null };
+    const onAbort = () => this.#cancel(request, signal.reason);
+    this.#requests.add(request);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+    const result = this.#tail.then(() => this.#run(request, text, voice, rate));
+    const settled = result.finally(() => {
+      signal?.removeEventListener('abort', onAbort);
+      this.#requests.delete(request);
+    });
+    this.#tail = settled.catch(() => {});
+    return settled;
+  }
+
+  /** Resolves after queued requests and cleanup; rejects teardown failures. */
+  async stop() {
+    for (const request of this.#requests) this.#cancel(request);
+    const pending = this.#tail;
+    await pending;
+    if (this.#unclosed || this.#state === 'error') throw this.#lastError;
+  }
+
+  pause() {
+    return this.#control('speaking', 'paused', 'SIGSTOP');
+  }
+  resume() {
+    return this.#control('paused', 'speaking', 'SIGCONT');
+  }
+
+  #control(from, to, signal) {
+    if (
+      this.#platform !== 'darwin' ||
+      this.#state !== from ||
+      !this.#active?.child ||
+      this.#active.cancelled
+    )
+      return false;
+    try {
+      if (!this.#active.child.kill(signal))
+        throw failure('Unable to signal speech process', 'SAY_SIGNAL_FAILED');
+      this.#state = to;
+      return true;
+    } catch (error) {
+      this.#lastError = error;
+      return false;
+    }
+  }
+
+  #cancel(request, reason) {
+    if (request.cancelled) return;
+    request.cancelled = true;
+    request.reason = reason;
+    request.cancelChild?.();
+  }
+
+  async #run(request, text, voice, rate) {
+    let directory;
+    let error;
+    const check = () => {
+      if (request.cancelled) throw aborted(request.reason);
+    };
+    try {
+      check();
+      if (this.#unclosed)
+        throw failure('Previous speech process has not closed', 'SAY_PROCESS_UNCLOSED');
+      this.#active = request;
+      this.#state = 'preparing';
+      this.#lastError = null;
+      const capability = await this.getCapabilities();
+      check();
+      if (!capability.supported) throw failure('macOS say is unavailable', 'SAY_UNAVAILABLE');
+      directory = await this.#fs.mkdtemp(join(this.#tempRoot, 'dsh-live-voice-say-'));
+      check();
+      await this.#fs.chmod(directory, 0o700);
+      const file = join(directory, 'speech.txt');
+      await this.#fs.writeFile(file, text, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      await this.#fs.chmod(file, 0o600);
+      check();
+      const args = ['-f', file];
+      if (voice !== undefined) args.push('-v', voice);
+      if (rate !== undefined) args.push('-r', String(rate));
+      const child = this.#spawn('/usr/bin/say', args, { shell: false, stdio: 'ignore' });
+      request.child = child;
+      this.#state = 'speaking';
+      await this.#waitForClose(request, child);
+      check();
+    } catch (caught) {
+      error = caught;
+    } finally {
+      request.cancelChild = null;
+      if (directory) {
+        try {
+          await this.#fs.rm(directory, { recursive: true, force: true });
+        } catch (cleanupError) {
+          error = failure(
+            'Speech temporary-file cleanup failed',
+            'SAY_CLEANUP_FAILED',
+            error ? new AggregateError([error, cleanupError]) : cleanupError,
+          );
+        }
+      }
+      if (!error && request.cancelled) error = aborted(request.reason);
+      if (this.#active === request) this.#active = null;
+      if (error && error.name !== 'AbortError') {
+        this.#state = 'error';
+        this.#lastError = error;
+      } else if (!this.#unclosed && this.#state !== 'error') this.#state = 'idle';
+    }
+    if (error) throw error;
+  }
+
+  #waitForClose(request, child) {
+    return new Promise((resolve, reject) => {
+      let closed = false;
+      let processError;
+      let killTimer;
+      let closeTimer;
+      const send = (signal) => {
+        try {
+          if (!child.kill(signal))
+            processError ??= failure('Unable to signal speech process', 'SAY_SIGNAL_FAILED');
+        } catch (error) {
+          processError ??= error;
+        }
+      };
+      const onError = (error) => {
+        processError ??= error;
+      };
+      child.on('error', onError);
+      child.once('close', (code, signal) => {
+        closed = true;
+        clearTimeout(killTimer);
+        clearTimeout(closeTimer);
+        child.removeListener('error', onError);
+        if (this.#unclosed === child) this.#unclosed = null;
+        if (request.cancelled) reject(aborted(request.reason));
+        else if (processError) reject(processError);
+        else if (code !== 0)
+          reject(
+            failure('Speech process exited unsuccessfully', 'SAY_EXIT_FAILED', { code, signal }),
+          );
+        else resolve();
+      });
+      request.cancelChild = () => {
+        if (closed) return;
+        const paused = this.#state === 'paused';
+        this.#state = 'stopping';
+        if (paused) send('SIGCONT');
+        send('SIGTERM');
+        if (closed) return;
+        killTimer = setTimeout(() => {
+          send('SIGKILL');
+          if (closed) return;
+          closeTimer = setTimeout(() => {
+            if (closed) return;
+            // Never start another child while the timed-out one might still speak.
+            this.#unclosed = child;
+            reject(
+              failure(
+                'Speech process did not close after cancellation',
+                'SAY_STOP_TIMEOUT',
+                processError,
+              ),
+            );
+          }, this.#closeAfterMs);
+        }, this.#killAfterMs);
+      };
+      if (request.cancelled) request.cancelChild();
+    });
+  }
+}

package/src/server.ts

@@ -0,0 +1,365 @@
+// @ts-nocheck
+import { SayEngine } from './engines/speaking/say.ts';
+import {
+  WhisperHttpHost,
+  createWhisperConfigStore,
+  validateWhisperConfig,
+} from './engines/recognition/whisper-http-host.ts';
+import {
+  QwenHttpHost,
+  createQwenConfigStore,
+  validateQwenConfig,
+} from './engines/qwen-http-host.ts';
+
+export const name = 'dsh-live-voice';
+export const inject = ['connection'];
+export const SAY_CHANNEL = '/api/dsh-live-voice';
+const ok = (value) => ({ ok: true, value });
+const fail = (code, message) => ({ ok: false, error: { code, message, details: {} } });
+const identity = (value) => typeof value === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(value);
+
+/** One local speaker owner. IDs isolate control races, not authenticated users:
+ * Connection owns browser authentication; its RPC handler exposes no user identity.
+ */
+export function createSayHost({ engine = new SayEngine() } = {}) {
+  let active = null;
+  let disposed = false;
+  async function handle(endpoint, payload, signal) {
+    if (disposed) return fail('disposed', 'Speech service is closed.');
+    if (signal?.aborted) return fail('cancelled', 'Speech was cancelled.');
+    try {
+      if (endpoint === 'capabilities') return ok(await engine.getCapabilities());
+      if (!['speak', 'stop', 'pause', 'resume'].includes(endpoint))
+        return fail('not-found', 'Unknown speech endpoint.');
+      if (!payload || !identity(payload.clientId) || !identity(payload.operationId)) {
+        return fail('invalid-request', 'Valid client and operation IDs are required.');
+      }
+      const owns =
+        active?.clientId === payload.clientId && active?.operationId === payload.operationId;
+      if (endpoint !== 'speak') {
+        if (!owns) return ok({ applied: false });
+        const operation = active;
+        if (endpoint === 'stop') {
+          operation.abort.abort();
+          // Await this operation, never call a global stop after an await:
+          // a new request could already own the speaker by then.
+          await operation.done;
+          return ok({ applied: true });
+        }
+        return ok({ applied: Boolean(engine[endpoint]()) });
+      }
+      if (
+        typeof payload.text !== 'string' ||
+        !payload.text.trim() ||
+        payload.text.length > 100000 ||
+        payload.text.includes('\0')
+      )
+        return fail('invalid-request', 'Speech text must contain 1–100000 characters without NUL.');
+      if (
+        payload.voice !== undefined &&
+        (typeof payload.voice !== 'string' ||
+          !payload.voice.trim() ||
+          payload.voice.length > 200 ||
+          payload.voice.includes('\0'))
+      )
+        return fail('invalid-request', 'Invalid voice.');
+      if (!Number.isFinite(payload.rate) || payload.rate < 18 || payload.rate > 1750)
+        return fail('invalid-request', 'Invalid speech rate.');
+      if (active && active.clientId !== payload.clientId)
+        return fail('busy', 'Another voice client owns the host speaker.');
+      if (owns) return fail('duplicate-operation', 'The speech operation is already active.');
+      active?.abort.abort();
+      const operation = {
+        clientId: payload.clientId,
+        operationId: payload.operationId,
+        abort: new AbortController(),
+        done: null,
+      };
+      active = operation;
+      const cancel = () => operation.abort.abort();
+      signal?.addEventListener('abort', cancel, { once: true });
+      if (signal?.aborted) cancel();
+      // Keep the authenticated RPC open until process close and file cleanup.
+      // DSH aborts its signal when the browser connection closes prematurely.
+      operation.done = Promise.resolve()
+        .then(() =>
+          engine.speak(payload.text, {
+            voice: payload.voice,
+            rate: payload.rate,
+            signal: operation.abort.signal,
+          }),
+        )
+        .then(
+          () => ok({ completed: true }),
+          (error) =>
+            error?.name === 'AbortError'
+              ? fail('cancelled', 'Speech was cancelled.')
+              : fail('speech-failed', 'Local speech failed.'),
+        );
+      try {
+        return await operation.done;
+      } finally {
+        signal?.removeEventListener('abort', cancel);
+        if (active === operation) active = null;
+      }
+    } catch {
+      return fail('speech-failed', 'Local speech service failed.');
+    }
+  }
+  async function dispose() {
+    disposed = true;
+    active?.abort.abort();
+    await engine.stop();
+    active = null;
+  }
+  return { handle, dispose };
+}
+
+export function apply(
+  ctx,
+  {
+    whisperStore = createWhisperConfigStore(),
+    whisperFetch = globalThis.fetch,
+    qwenStore = createQwenConfigStore(),
+    qwenFetch = globalThis.fetch,
+  } = {},
+) {
+  const host = createSayHost();
+  const whisper = new WhisperHttpHost({ store: whisperStore, fetchImpl: whisperFetch });
+  const qwen = new QwenHttpHost({ store: qwenStore, fetchImpl: qwenFetch });
+  for (const endpoint of ['config', 'test']) {
+    const dispose = ctx.connection.fetch.register({
+      path: SAY_CHANNEL + '/whisper/' + endpoint,
+      methods: endpoint === 'config' ? ['GET', 'PUT'] : ['POST'],
+      requestBody: 'buffered',
+      fetch: async (request) => {
+        try {
+          if (request.method === 'GET') return Response.json(ok(await whisper.getConfig()));
+          let config;
+          try {
+            config = validateWhisperConfig(await request.json());
+          } catch (error) {
+            return Response.json(fail('invalid-config', error.message), { status: 400 });
+          }
+          const value =
+            endpoint === 'test'
+              ? await whisper.capability(request.signal, config)
+              : await whisper.replaceConfig(config);
+          return Response.json(ok(value));
+        } catch (error) {
+          return Response.json(
+            fail('config-failed', error.message || 'Whisper settings could not be saved.'),
+            { status: 500 },
+          );
+        }
+      },
+    });
+    ctx.effect(() => () => dispose(), 'dsh-live-voice: remove Whisper ' + endpoint + ' route');
+  }
+  ctx.effect(() => () => whisper.dispose(), 'dsh-live-voice: cancel Whisper requests');
+  const whisperCapability = ctx.connection.fetch.register({
+    path: SAY_CHANNEL + '/whisper/capabilities',
+    methods: ['GET'],
+    requestBody: 'buffered',
+    fetch: async (request) => Response.json(ok(await whisper.capability(request.signal))),
+  });
+  const whisperTranscribe = ctx.connection.fetch.register({
+    path: SAY_CHANNEL + '/whisper/transcribe',
+    methods: ['POST'],
+    requestBody: 'buffered',
+    fetch: async (request) => {
+      try {
+        const clientId = request.headers.get('x-dlv-client-id'),
+          operationId = request.headers.get('x-dlv-operation-id');
+        if (!identity(clientId) || !identity(operationId))
+          return Response.json(
+            fail('invalid-request', 'Valid client and operation IDs are required.'),
+            { status: 400 },
+          );
+        if (request.headers.get('content-type')?.split(';')[0] !== 'audio/wav')
+          return Response.json(
+            fail('invalid-audio', 'A mono 16 kHz PCM WAV recording is required.'),
+            { status: 400 },
+          );
+        const length = Number(request.headers.get('content-length') || 0);
+        if (length > whisper.maxBytes)
+          return Response.json(
+            fail('audio-too-large', 'The recording exceeds the configured Whisper limit.'),
+            { status: 413 },
+          );
+        const value = await whisper.transcribe(await request.arrayBuffer(), {
+          lang: request.headers.get('x-dlv-language') || 'auto',
+          signal: request.signal,
+        });
+        return Response.json(ok(value));
+      } catch (error) {
+        if (error?.name === 'AbortError')
+          return Response.json(fail('cancelled', 'Whisper transcription was cancelled.'), {
+            status: 499,
+          });
+        return Response.json(
+          fail('transcription-failed', error?.message || 'Whisper transcription failed.'),
+          { status: 502 },
+        );
+      }
+    },
+  });
+  ctx.effect(
+    () => async () => {
+      await whisperCapability();
+      await whisperTranscribe();
+    },
+    'dsh-live-voice: remove Whisper routes',
+  );
+  for (const endpoint of ['config', 'test']) {
+    const dispose = ctx.connection.fetch.register({
+      path: SAY_CHANNEL + '/qwen/' + endpoint,
+      methods: endpoint === 'config' ? ['GET', 'PUT'] : ['POST'],
+      requestBody: 'buffered',
+      fetch: async (request) => {
+        try {
+          if (request.method === 'GET') return Response.json(ok(await qwen.getConfig()));
+          let config;
+          try {
+            config = validateQwenConfig(await request.json());
+          } catch (error) {
+            return Response.json(fail('invalid-config', error.message), { status: 400 });
+          }
+          const value =
+            endpoint === 'test'
+              ? await qwen.capability(request.signal, config)
+              : await qwen.replaceConfig(config);
+          return Response.json(ok(value));
+        } catch (error) {
+          return Response.json(
+            fail('config-failed', error.message || 'Qwen settings could not be saved.'),
+            { status: 500 },
+          );
+        }
+      },
+    });
+    ctx.effect(() => () => dispose(), 'dsh-live-voice: remove Qwen ' + endpoint + ' route');
+  }
+  ctx.effect(() => () => qwen.dispose(), 'dsh-live-voice: cancel Qwen requests');
+  const qwenCapability = ctx.connection.fetch.register({
+    path: SAY_CHANNEL + '/qwen/capabilities',
+    methods: ['GET'],
+    requestBody: 'buffered',
+    fetch: async (request) => {
+      const kind = new URL(request.url).searchParams.get('kind');
+      return Response.json(
+        ok(
+          await qwen.capability(
+            request.signal,
+            undefined,
+            kind === 'asr' || kind === 'tts' ? kind : 'both',
+          ),
+        ),
+      );
+    },
+  });
+  const qwenTranscribe = ctx.connection.fetch.register({
+    path: SAY_CHANNEL + '/qwen/transcribe',
+    methods: ['POST'],
+    requestBody: 'buffered',
+    fetch: async (request) => {
+      try {
+        const clientId = request.headers.get('x-dlv-client-id'),
+          operationId = request.headers.get('x-dlv-operation-id');
+        if (!identity(clientId) || !identity(operationId))
+          return Response.json(
+            fail('invalid-request', 'Valid client and operation IDs are required.'),
+            { status: 400 },
+          );
+        if (request.headers.get('content-type')?.split(';')[0] !== 'audio/wav')
+          return Response.json(
+            fail('invalid-audio', 'A mono 16 kHz PCM WAV recording is required.'),
+            { status: 400 },
+          );
+        const length = Number(request.headers.get('content-length') || 0);
+        if (length > qwen.maxBytes)
+          return Response.json(
+            fail('audio-too-large', 'The recording exceeds the configured Qwen limit.'),
+            { status: 413 },
+          );
+        return Response.json(
+          ok(
+            await qwen.transcribe(await request.arrayBuffer(), {
+              lang: request.headers.get('x-dlv-language') || 'pt-BR',
+              signal: request.signal,
+            }),
+          ),
+        );
+      } catch (error) {
+        if (error?.name === 'AbortError')
+          return Response.json(fail('cancelled', 'Qwen transcription was cancelled.'), {
+            status: 499,
+          });
+        return Response.json(
+          fail('transcription-failed', error?.message || 'Qwen transcription failed.'),
+          { status: 502 },
+        );
+      }
+    },
+  });
+  const qwenSpeech = ctx.connection.fetch.register({
+    path: SAY_CHANNEL + '/qwen/speech',
+    methods: ['POST'],
+    requestBody: 'buffered',
+    fetch: async (request) => {
+      try {
+        const body = await request.json();
+        const bytes = await qwen.synthesize(body?.text, {
+          lang: body?.lang || 'pt-BR',
+          voice: body?.voice,
+          signal: request.signal,
+        });
+        return new Response(bytes, {
+          status: 200,
+          headers: { 'content-type': 'audio/wav', 'cache-control': 'no-store' },
+        });
+      } catch (error) {
+        if (error?.name === 'AbortError')
+          return Response.json(fail('cancelled', 'Qwen synthesis was cancelled.'), { status: 499 });
+        return Response.json(fail('synthesis-failed', error?.message || 'Qwen synthesis failed.'), {
+          status: 502,
+        });
+      }
+    },
+  });
+  ctx.effect(
+    () => async () => {
+      await qwenCapability();
+      await qwenTranscribe();
+      await qwenSpeech();
+    },
+    'dsh-live-voice: remove Qwen routes',
+  );
+  // Existing /api carrier preserves DSH authentication and disconnect signals.
+  for (const endpoint of ['capabilities', 'speak', 'stop', 'pause', 'resume']) {
+    const dispose = ctx.connection.fetch.register({
+      path: `${SAY_CHANNEL}/${endpoint}`,
+      methods: ['POST'],
+      requestBody: 'buffered',
+      fetch: async (request) => {
+        let body;
+        try {
+          body = await request.json();
+        } catch {
+          return new Response('Invalid JSON', { status: 400 });
+        }
+        if (
+          body?.type !== 'client-request' ||
+          typeof body.rpcId !== 'string' ||
+          body.rpcId.length > 128 ||
+          body.method !== `dsh-live-voice/${endpoint}`
+        )
+          return new Response('Invalid RPC envelope', { status: 400 });
+        const result = await host.handle(endpoint, body.payload, request.signal);
+        return Response.json({ type: 'server-response', rpcId: body.rpcId, result });
+      },
+    });
+    ctx.effect(() => () => dispose(), `dsh-live-voice: remove ${endpoint} route`);
+  }
+  ctx.effect(() => () => host.dispose(), 'dsh-live-voice: stop host speech');
+}

package/AGENTS.md

@@ -1,52 +0,0 @@
-# Agent Instructions
-
-## Project identity and current stage
-
-- Project: **DSH Live Voice**; npm package: `dsh-live-voice`.
-- Current version: `0.0.1-developing`. This repository is a documentation-only development placeholder, not a functioning DSH plugin.
-- Read `README.md`, `HISTORY.md`, and `package.json` before making project changes.
-- Write repository documentation, code comments, and public package metadata in English. Keep the requested filename `HISTORY.md`.
-
-## Product priorities
-
-- Lead with **local-first voice conversations**. Both STT and TTS should be able to run on the user’s machine. External providers are optional.
-- Do not claim full offline operation merely because voice processing is local; the DSH language model can be remote.
-- Coordinate input and output in one plugin. Preserve separate states for capture/recognition, synthesis/playback, and agent generation.
-- Keep pause, resume, and cancel distinct. Do not automatically resume obsolete speech just because the user becomes silent.
-- Plan for speaker mode with recognition gating and manual interruption, and headphone mode with open-microphone interruption. Exact policies remain undecided.
-- Capability detection must distinguish the DSH host from the browser/device environment. Do not assume OS detection proves feature support or that a browser shortcut is global.
-- Make capture, recognition, transmission, playback, and permission states understandable to users. Avoid recording or logging raw audio/transcripts by default.
-
-## History is strictly append-only
-
-**Never edit, delete, reorder, reformat, or replace existing content in `HISTORY.md`.**
-
-When a history update is requested or a meaningful approved decision needs recording:
-
-1. Read the existing file.
-2. Preserve its entire existing content exactly.
-3. Append a new English entry at the end using the actual local date (`YYYY-MM-DD`) and a descriptive heading.
-4. Explain what changed and why; distinguish proposals, decisions, and completed implementation.
-5. If correcting or reversing an earlier statement, reference it in the new entry rather than modifying it.
-
-Do not invent approvals, dates, completed work, or releases. Do not add secrets or sensitive data. Other documentation may be updated normally to reflect the current state; history preserves the evolution.
-
-## Implementation discipline
-
-- Inspect actual DSH extension APIs before selecting integration points. Do not fabricate hooks, plugin manifests, install commands, or support guarantees.
-- Existing STT/TTS plugin reuse versus direct engine integration is unresolved.
-- Keep conversation policy separate from provider adapters and UI.
-- Do not implement features or add dependencies just to make the placeholder look complete.
-- Keep planned capabilities clearly labeled until implemented and validated.
-- Future audio work must account for echo, false interruptions, recognition latency, playback position, and stale asynchronous results after cancellation.
-- Third-party engines and model weights require their own license and platform checks. This repository uses GPL-3.0-only. Commercial use and paid redistribution are allowed subject to GPL obligations; do not describe the license as non-commercial. Check DSH and dependency license compatibility before integration.
-
-## Packaging and authorization
-
-- Keep public metadata and README aligned with the local-first focus.
-- Do not invent author or repository URLs.
-- Use explicit `--tag developing` for this prerelease. Never silently promote it to `latest`.
-- `npm publish --dry-run --tag developing` validates packaging without publishing; it does not reserve a name or prove registry authorization.
-- No automated test suite or runnable plugin exists yet. Report validation honestly; do not describe a package dry run as a runtime test.
-- Commit, push, actual npm publication, and secondary package creation require explicit maintainer authorization.
-- The maintainer supplied `git@github.com:victorwads/dsh-live-voice.git` and authorized the first commit and push to `main`. npm publication requires separate authorization.