@kaleidorg/mind 0.3.0 → 0.4.0

package/dist/qvac/provider.js

@@ -0,0 +1,68 @@
+import { consumeRun } from './stream.js';
+export function createQvacProvider(options) {
+    return {
+        name: 'qvac',
+        async runTurn(input) {
+            const modelId = options.getModelId();
+            if (!modelId)
+                throw new Error('QVAC model not loaded');
+            const history = input.system
+                ? [{ role: 'system', content: input.system }, ...input.messages]
+                : input.messages;
+            // Tools are forwarded by schema only (name/description/parameters). We
+            // carry `parameters` through verbatim (Zod for in-process tools, JSON
+            // Schema for MCP) — the model only needs the shape to pick a call; the
+            // Engine validates + executes.
+            const tools = input.tools.length
+                ? input.tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                }))
+                : undefined;
+            // QVAC 0.13 nests sampling under `generationParams`; top-level
+            // `temperature`/`max_tokens` (as older rate code passed) are dropped by
+            // validation, so the cap silently no-op'd. Build it here, and only send it
+            // when a value is set so a host that passes neither keeps SDK defaults.
+            const temp = input.temperature ?? options.defaultTemperature;
+            const predict = input.maxTokens ?? options.defaultMaxTokens;
+            const generationParams = temp !== undefined || predict !== undefined
+                ? {
+                    ...(temp !== undefined ? { temp } : {}),
+                    ...(predict !== undefined ? { predict } : {}),
+                }
+                : undefined;
+            const run = options.completion({
+                modelId,
+                history,
+                stream: true,
+                // Split `<think>` into separate thinkingDelta events so reasoning never
+                // pollutes the visible answer.
+                captureThinking: true,
+                ...(generationParams ? { generationParams } : {}),
+                ...(tools ? { tools } : {}),
+            });
+            const result = await consumeRun(run, {
+                onToken: input.onToken,
+                onThinking: input.onThinking ?? options.onThinking,
+            });
+            return {
+                text: result.text,
+                rawContent: result.rawContent,
+                toolCalls: result.toolCalls,
+                requestId: result.requestId,
+            };
+        },
+        async cancel(requestId) {
+            // The cancel only lands once the server has begun the request; a same-tick
+            // cancel may race the begin and is logged as a no-match by the SDK.
+            try {
+                await options.cancel({ requestId });
+            }
+            catch (err) {
+                console.warn('[qvac] cancel failed:', err);
+            }
+        },
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/qvac/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/qvac/provider.ts"],"names":[],"mappings":"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"}

package/dist/qvac/stream.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Consume a QVAC `completion()` run: drain the event stream (forwarding visible
+ * + thinking tokens) and fold the `final` frame into a ParsedTurn.
+ *
+ * Defined over a structural `CompletionRunLike` (not the SDK type) so it stays
+ * SDK-free and unit-testable with a fake run — the real `CompletionRun` is
+ * assignable to it. The actual `@qvac/sdk` import lives in `provider.ts`.
+ */
+import { type ParsedTurn, type QvacFinalLike } from './parse.js';
+/** Minimal shape of a QVAC completion event we react to. */
+export interface CompletionEventLike {
+    type: string;
+    /** Present on `contentDelta` / `thinkingDelta` / `rawDelta`. */
+    text?: string;
+}
+/** Structural subset of `completion()`'s return we depend on. */
+export interface CompletionRunLike {
+    requestId: string;
+    events: AsyncIterable<CompletionEventLike>;
+    final: Promise<QvacFinalLike>;
+}
+export interface StreamHandlers {
+    /** Visible assistant tokens (excludes `<think>` reasoning). */
+    onToken?: (token: string) => void;
+    /** The model's `<think>` reasoning, streamed separately. */
+    onThinking?: (token: string) => void;
+}
+export interface ConsumedTurn extends ParsedTurn {
+    requestId: string;
+}
+/**
+ * Stream a run to completion. `contentDelta` → onToken (and the streamed
+ * fallback text), `thinkingDelta` → onThinking. Returns the parsed turn plus the
+ * run's `requestId` (for cancellation bookkeeping by the caller).
+ */
+export declare function consumeRun(run: CompletionRunLike, handlers?: StreamHandlers): Promise<ConsumedTurn>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/qvac/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/qvac/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAe,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9E,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAC3C,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,4DAA4D;IAC5D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,GAAE,cAAmB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAYvB"}

package/dist/qvac/stream.js

@@ -0,0 +1,29 @@
+/**
+ * Consume a QVAC `completion()` run: drain the event stream (forwarding visible
+ * + thinking tokens) and fold the `final` frame into a ParsedTurn.
+ *
+ * Defined over a structural `CompletionRunLike` (not the SDK type) so it stays
+ * SDK-free and unit-testable with a fake run — the real `CompletionRun` is
+ * assignable to it. The actual `@qvac/sdk` import lives in `provider.ts`.
+ */
+import { finalToTurn } from './parse.js';
+/**
+ * Stream a run to completion. `contentDelta` → onToken (and the streamed
+ * fallback text), `thinkingDelta` → onThinking. Returns the parsed turn plus the
+ * run's `requestId` (for cancellation bookkeeping by the caller).
+ */
+export async function consumeRun(run, handlers = {}) {
+    let streamed = '';
+    for await (const event of run.events) {
+        if (event.type === 'contentDelta' && typeof event.text === 'string') {
+            streamed += event.text;
+            handlers.onToken?.(event.text);
+        }
+        else if (event.type === 'thinkingDelta' && typeof event.text === 'string') {
+            handlers.onThinking?.(event.text);
+        }
+    }
+    const final = await run.final;
+    return { ...finalToTurn(final, streamed), requestId: run.requestId };
+}
+//# sourceMappingURL=stream.js.map

package/dist/qvac/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../../src/qvac/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAuC,MAAM,YAAY,CAAC;AA2B9E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAsB,EACtB,WAA2B,EAAE;IAE7B,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACrC,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpE,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC;YACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5E,QAAQ,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,KAAK,CAAC;IAC9B,OAAO,EAAE,GAAG,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;AACvE,CAAC"}

package/dist/qvac/text.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pure text helpers for QVAC output. No SDK, no platform — safe to run and test
+ * anywhere. Lifted verbatim from rate's QVACService so every host shares one
+ * implementation instead of drifting copies.
+ */
+/**
+ * Clean a raw assistant completion into user-visible text:
+ *  - drop `<think>…</think>` reasoning (small models leak it into content),
+ *  - drop a leading `{"name":…,"arguments":…}` tool-call object some tiny models
+ *    emit as plain text, keeping any natural-language sentence that follows.
+ */
+export declare function cleanAssistantVisibleText(text: string): string;
+/**
+ * Make text safe for the SUPERTONIC TTS model: redact payment strings (so they
+ * are never read aloud), strip markdown/code, normalize smart punctuation, and
+ * drop any non-ASCII or backtick (U+0060) the model can't synthesize.
+ */
+export declare function sanitizeForSupertonic(text: string): string;
+//# sourceMappingURL=text.d.ts.map

package/dist/qvac/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/qvac/text.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB9D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAsB1D"}

package/dist/qvac/text.js

@@ -0,0 +1,56 @@
+/**
+ * Pure text helpers for QVAC output. No SDK, no platform — safe to run and test
+ * anywhere. Lifted verbatim from rate's QVACService so every host shares one
+ * implementation instead of drifting copies.
+ */
+/**
+ * Clean a raw assistant completion into user-visible text:
+ *  - drop `<think>…</think>` reasoning (small models leak it into content),
+ *  - drop a leading `{"name":…,"arguments":…}` tool-call object some tiny models
+ *    emit as plain text, keeping any natural-language sentence that follows.
+ */
+export function cleanAssistantVisibleText(text) {
+    let cleaned = text
+        // Qwen-style reasoning sometimes arrives in contentText. Never show/speak it.
+        .replace(/<think\b[\s\S]*?<\/think>/gi, ' ')
+        .replace(/<think\b[\s\S]*$/gi, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    // Some small local models emit a tool-call object as plain text. Drop the
+    // leading fragment and keep any natural-language sentence that follows.
+    const toolPrefix = cleaned.match(/^\s*\{?\s*"name"\s*:\s*"[^"]+"\s*,\s*"arguments"\s*:\s*/i);
+    if (toolPrefix) {
+        cleaned = cleaned.slice(toolPrefix[0].length).replace(/^\s*\{?\s*/, '').trim();
+    }
+    return cleaned
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Make text safe for the SUPERTONIC TTS model: redact payment strings (so they
+ * are never read aloud), strip markdown/code, normalize smart punctuation, and
+ * drop any non-ASCII or backtick (U+0060) the model can't synthesize.
+ */
+export function sanitizeForSupertonic(text) {
+    const normalized = text
+        .replace(/\b(?:lightning:)?ln(?:bc|tb|bcrt)[a-z0-9]{40,}\b/gi, 'Lightning invoice')
+        .replace(/\blnurl[0-9a-z]{40,}\b/gi, 'Lightning payment link')
+        .replace(/```[\s\S]*?```/g, ' ')
+        .replace(/`([^`]*)`/g, '$1')
+        .replace(/[`´ˋ′*_~#<>|[\]{}]/g, ' ')
+        .replace(/[“”]/g, '"')
+        .replace(/[‘’]/g, "'")
+        .replace(/[•·]/g, '. ')
+        .replace(/[^\x09\x0A\x0D\x20-\x7E]/g, ' ')
+        .replace(/\s+/g, ' ');
+    return Array.from(normalized)
+        .filter((ch) => {
+        const code = ch.charCodeAt(0);
+        return (code === 0x09 || code === 0x0A || code === 0x0D || (code >= 0x20 && code <= 0x7E)) &&
+            code !== 0x60;
+    })
+        .join('')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+//# sourceMappingURL=text.js.map

package/dist/qvac/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../../src/qvac/text.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,IAAI,OAAO,GAAG,IAAI;QAChB,8EAA8E;SAC7E,OAAO,CAAC,6BAA6B,EAAE,GAAG,CAAC;SAC3C,OAAO,CAAC,oBAAoB,EAAE,GAAG,CAAC;SAClC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;IAEV,0EAA0E;IAC1E,wEAAwE;IACxE,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC7F,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjF,CAAC;IAED,OAAO,OAAO;SACX,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,MAAM,UAAU,GAAG,IAAI;SACpB,OAAO,CAAC,oDAAoD,EAAE,mBAAmB,CAAC;SAClF,OAAO,CAAC,0BAA0B,EAAE,wBAAwB,CAAC;SAC7D,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC;SAC/B,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC;SAC3B,OAAO,CAAC,qBAAqB,EAAE,GAAG,CAAC;SACnC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC;SACtB,OAAO,CAAC,2BAA2B,EAAE,GAAG,CAAC;SACzC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAExB,OAAO,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;SAC1B,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC9B,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC,CAAC;YACxF,IAAI,KAAK,IAAI,CAAC;IAClB,CAAC,CAAC;SACD,IAAI,CAAC,EAAE,CAAC;SACR,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC"}

package/dist/qvac/voice.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Voice runtime ops shared across hosts: one-shot transcription (Whisper) and
+ * speech synthesis (SUPERTONIC TTS). Like the provider, the SDK functions are
+ * injected (type-only `@qvac/sdk` import, erased at build) so this carries no
+ * runtime SDK dependency and is unit-testable with fakes.
+ *
+ * The host still owns model lifecycle (download, load, local-vs-delegated) and
+ * audio I/O (mic capture, playback). It passes the loaded model-id resolvers;
+ * this module does the SDK calls + the text gating that must be identical
+ * everywhere (payment-string redaction, U+0060 refusal, file:// stripping).
+ *
+ * The streaming voice-assistant loop (transcribeStream + VAD) builds on top of
+ * these in a later pass.
+ */
+import type * as QvacSdk from '@qvac/sdk';
+import type { VoiceTranscriptEvent } from './assistant.js';
+type TranscribeFn = typeof QvacSdk.transcribe;
+type TextToSpeechFn = typeof QvacSdk.textToSpeech;
+type TranscribeStreamFn = typeof QvacSdk.transcribeStream;
+/** 16-bit PCM samples plus their sample rate, ready for the host to play. */
+export interface PcmAudio {
+    pcm: number[];
+    sampleRate: number;
+}
+/**
+ * A live VAD transcription session: feed mic audio with `write()`, iterate to
+ * receive `text`/`vad`/`endOfTurn` events, `end()` when audio stops. Pass it
+ * straight to `runVoiceAssistant`.
+ */
+export interface VoiceSession {
+    write(audioChunk: Uint8Array): void;
+    end(): void;
+    destroy(): void;
+    [Symbol.asyncIterator](): AsyncIterator<VoiceTranscriptEvent>;
+}
+export interface QvacVoiceOptions {
+    /** The SDK's `transcribe` (injected). */
+    transcribe: TranscribeFn;
+    /** The SDK's `textToSpeech` (injected). */
+    textToSpeech: TextToSpeechFn;
+    /** The SDK's `transcribeStream` (injected) — only needed for `openVoiceSession`. */
+    transcribeStream?: TranscribeStreamFn;
+    /** Resolve the loaded Whisper model id (null ⇒ not loaded → throws). */
+    getWhisperModelId: () => string | null;
+    /** Resolve the loaded TTS model id (null ⇒ not loaded → returns null). */
+    getTtsModelId: () => string | null;
+    /** TTS output sample rate; defaults to SUPERTONIC-2's 44.1 kHz. */
+    ttsSampleRate?: number;
+}
+export interface QvacVoice {
+    /** Transcribe an audio file (path or `file://` URI) to text. */
+    transcribeAudio(audioUri: string): Promise<string>;
+    /**
+     * Synthesize speech for `text`. Returns PCM + sample rate, or `null` when TTS
+     * is unavailable or the text is empty after sanitization (host falls back to
+     * the system voice). Payment strings are redacted so they're never read aloud.
+     */
+    synthesizeSpeech(text: string): Promise<PcmAudio | null>;
+    /**
+     * Open a hands-free VAD transcription session (continuous voice). Requires
+     * `transcribeStream` to have been provided. Merge in `paramsOverride` to tune
+     * the defaults ({@link DEFAULT_VOICE_STREAM_PARAMS}). Feed the returned session
+     * to `runVoiceAssistant`.
+     */
+    openVoiceSession(paramsOverride?: Record<string, unknown>): Promise<VoiceSession>;
+}
+export declare function createQvacVoice(options: QvacVoiceOptions): QvacVoice;
+export {};
+//# sourceMappingURL=voice.d.ts.map

package/dist/qvac/voice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.d.ts","sourceRoot":"","sources":["../../src/qvac/voice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,KAAK,OAAO,MAAM,WAAW,CAAC;AAG1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,KAAK,YAAY,GAAG,OAAO,OAAO,CAAC,UAAU,CAAC;AAC9C,KAAK,cAAc,GAAG,OAAO,OAAO,CAAC,YAAY,CAAC;AAClD,KAAK,kBAAkB,GAAG,OAAO,OAAO,CAAC,gBAAgB,CAAC;AAE1D,6EAA6E;AAC7E,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACpC,GAAG,IAAI,IAAI,CAAC;IACZ,OAAO,IAAI,IAAI,CAAC;IAChB,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,oBAAoB,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,UAAU,EAAE,YAAY,CAAC;IACzB,2CAA2C;IAC3C,YAAY,EAAE,cAAc,CAAC;IAC7B,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,kBAAkB,CAAC;IACtC,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvC,0EAA0E;IAC1E,aAAa,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACnC,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,gEAAgE;IAChE,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACzD;;;;;OAKG;IACH,gBAAgB,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACnF;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA+CpE"}

package/dist/qvac/voice.js

@@ -0,0 +1,51 @@
+import { sanitizeForSupertonic } from './text.js';
+import { TTS_SAMPLE_RATE, DEFAULT_VOICE_STREAM_PARAMS } from './config.js';
+export function createQvacVoice(options) {
+    const sampleRate = options.ttsSampleRate ?? TTS_SAMPLE_RATE;
+    return {
+        async transcribeAudio(audioUri) {
+            const modelId = options.getWhisperModelId();
+            if (!modelId)
+                throw new Error('Whisper model not loaded');
+            // The SDK's native file reader wants a plain filesystem path, not a
+            // `file://` URI — the URI raises AUDIO_FILE_NOT_FOUND even when present.
+            const audioChunk = audioUri.replace('file://', '');
+            return await options.transcribe({ modelId, audioChunk });
+        },
+        async synthesizeSpeech(text) {
+            const modelId = options.getTtsModelId();
+            if (!modelId)
+                return null;
+            const trimmed = sanitizeForSupertonic(text);
+            if (!trimmed)
+                return null;
+            // Belt-and-suspenders: SUPERTONIC chokes on U+0060; sanitize already
+            // strips it, so refuse if any slipped through rather than crash the voice.
+            if (Array.from(trimmed).some((ch) => ch.charCodeAt(0) === 0x60))
+                return null;
+            const result = options.textToSpeech({
+                modelId,
+                text: trimmed,
+                inputType: 'text',
+                stream: false,
+            });
+            const pcm = await result.buffer;
+            return { pcm, sampleRate };
+        },
+        async openVoiceSession(paramsOverride = {}) {
+            if (!options.transcribeStream) {
+                throw new Error('transcribeStream not provided — pass it in QvacVoiceOptions for voice sessions');
+            }
+            const modelId = options.getWhisperModelId();
+            if (!modelId)
+                throw new Error('Whisper model not loaded');
+            const session = await options.transcribeStream({
+                modelId,
+                ...DEFAULT_VOICE_STREAM_PARAMS,
+                ...paramsOverride,
+            });
+            return session;
+        },
+    };
+}
+//# sourceMappingURL=voice.js.map

package/dist/qvac/voice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.js","sourceRoot":"","sources":["../../src/qvac/voice.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AA0D3E,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,MAAM,UAAU,GAAG,OAAO,CAAC,aAAa,IAAI,eAAe,CAAC;IAE5D,OAAO;QACL,KAAK,CAAC,eAAe,CAAC,QAAgB;YACpC,MAAM,OAAO,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAC5C,IAAI,CAAC,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;YAC1D,oEAAoE;YACpE,yEAAyE;YACzE,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YACnD,OAAO,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,UAAU,EAAiC,CAAC,CAAC;QAC1F,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,IAAY;YACjC,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;YACxC,IAAI,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAE1B,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAC1B,qEAAqE;YACrE,2EAA2E;YAC3E,IAAI,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YAE7E,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;gBAClC,OAAO;gBACP,IAAI,EAAE,OAAO;gBACb,SAAS,EAAE,MAAM;gBACjB,MAAM,EAAE,KAAK;aACmB,CAAC,CAAC;YACpC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC;YAChC,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC;QAC7B,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,iBAA0C,EAAE;YACjE,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,gFAAgF,CAAC,CAAC;YACpG,CAAC;YACD,MAAM,OAAO,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAC5C,IAAI,CAAC,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;YAC1D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,gBAAgB,CAAC;gBAC7C,OAAO;gBACP,GAAG,2BAA2B;gBAC9B,GAAG,cAAc;aACmB,CAAC,CAAC;YACxC,OAAO,OAAkC,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaleidorg/mind",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Local-first reasoning + function-calling engine for KaleidoSwap. QVAC-powered.",
   "license": "Apache-2.0",
   "type": "module",
@@ -34,6 +34,11 @@
       "types": "./dist/logger.d.ts",
       "import": "./dist/logger.js",
       "default": "./dist/logger.js"
+    },
+    "./qvac": {
+      "types": "./dist/qvac/index.d.ts",
+      "import": "./dist/qvac/index.js",
+      "default": "./dist/qvac/index.js"
     }
   },
   "files": [
@@ -51,7 +56,16 @@
     "lint": "eslint src",
     "bundle-skills": "node scripts/bundle-skills.mjs"
   },
+  "peerDependencies": {
+    "@qvac/sdk": ">=0.12.2"
+  },
+  "peerDependenciesMeta": {
+    "@qvac/sdk": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@qvac/sdk": "^0.13.1",
     "@types/node": "^20.0.0",
     "vitest": "^1.6.0"
   }

package/src/qvac/assistant.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+  shouldHandleUtterance,
+  runVoiceAssistant,
+  type VoiceTranscriptEvent,
+} from './assistant.js';
+
+const immediateSleep = async () => {};
+
+function sessionOf(events: VoiceTranscriptEvent[]): AsyncIterable<VoiceTranscriptEvent> {
+  return {
+    async *[Symbol.asyncIterator]() {
+      for (const e of events) yield e;
+    },
+  };
+}
+
+describe('shouldHandleUtterance', () => {
+  it('drops utterances shorter than minChars', () => {
+    expect(shouldHandleUtterance('hi')).toBe(false);
+    expect(shouldHandleUtterance('go!', { minChars: 5 })).toBe(false);
+  });
+
+  it('drops known Whisper hallucinations regardless of trailing punctuation/case', () => {
+    expect(shouldHandleUtterance('you')).toBe(false);
+    expect(shouldHandleUtterance('Thanks.')).toBe(false);
+    expect(shouldHandleUtterance('Thank you')).toBe(false);
+    expect(shouldHandleUtterance('.')).toBe(false);
+  });
+
+  it('keeps a real request', () => {
+    expect(shouldHandleUtterance('what is my balance')).toBe(true);
+  });
+
+  it('honours a custom ignore list', () => {
+    expect(shouldHandleUtterance('computer', { ignoredUtterances: ['computer'] })).toBe(false);
+  });
+});
+
+describe('runVoiceAssistant', () => {
+  it('handles only real utterances and ignores vad/short/hallucination events', async () => {
+    const respond = vi.fn(async (t: string) => `reply to ${t}`);
+    const speak = vi.fn(async () => {});
+    const session = sessionOf([
+      { type: 'vad', text: undefined },
+      { type: 'text', text: 'you' },                 // hallucination → skipped
+      { type: 'text', text: 'what is my balance' },  // handled
+      { type: 'endOfTurn' },
+    ]);
+
+    await runVoiceAssistant(session, { respond, speak }, { sleep: immediateSleep });
+
+    expect(respond).toHaveBeenCalledTimes(1);
+    expect(respond).toHaveBeenCalledWith('what is my balance');
+    expect(speak).toHaveBeenCalledWith('reply to what is my balance');
+  });
+
+  it('gates the mic around playback and ends un-gated', async () => {
+    const gates: boolean[] = [];
+    const session = sessionOf([{ type: 'text', text: 'tell me a joke' }]);
+    await runVoiceAssistant(
+      session,
+      {
+        respond: async () => 'here is a joke',
+        speak: async () => {},
+        setMicGated: (g) => gates.push(g),
+      },
+      { sleep: immediateSleep },
+    );
+    // gated true before speaking, false after cooldown, false again on loop exit.
+    expect(gates).toEqual([true, false, false]);
+  });
+
+  it('emits listening → thinking → speaking → listening states', async () => {
+    const states: string[] = [];
+    const session = sessionOf([{ type: 'text', text: 'what time is it' }]);
+    await runVoiceAssistant(
+      session,
+      { respond: async () => 'noon', speak: async () => {}, onState: (s) => states.push(s) },
+      { sleep: immediateSleep },
+    );
+    expect(states).toEqual(['listening', 'thinking', 'speaking', 'listening']);
+  });
+
+  it('does not speak an empty reply', async () => {
+    const speak = vi.fn(async () => {});
+    const session = sessionOf([{ type: 'text', text: 'a vague mumble here' }]);
+    await runVoiceAssistant(
+      session,
+      { respond: async () => '   ', speak },
+      { sleep: immediateSleep },
+    );
+    expect(speak).not.toHaveBeenCalled();
+  });
+
+  it('survives a respond() error and keeps listening', async () => {
+    const speak = vi.fn(async () => {});
+    const session = sessionOf([
+      { type: 'text', text: 'first thing fails' },
+      { type: 'text', text: 'second thing works' },
+    ]);
+    const respond = vi
+      .fn<[string], Promise<string>>()
+      .mockRejectedValueOnce(new Error('boom'))
+      .mockResolvedValueOnce('ok');
+    await runVoiceAssistant(session, { respond, speak }, { sleep: immediateSleep });
+    expect(respond).toHaveBeenCalledTimes(2);
+    expect(speak).toHaveBeenCalledTimes(1);
+    expect(speak).toHaveBeenCalledWith('ok');
+  });
+
+  it('stops early when the signal is aborted', async () => {
+    const controller = new AbortController();
+    const respond = vi.fn(async (t: string) => {
+      controller.abort();
+      return `reply ${t}`;
+    });
+    const speak = vi.fn(async () => {});
+    const session = sessionOf([
+      { type: 'text', text: 'first utterance here' },
+      { type: 'text', text: 'second utterance here' },
+    ]);
+    await runVoiceAssistant(
+      session,
+      { respond, speak },
+      { sleep: immediateSleep, signal: controller.signal },
+    );
+    // Aborted during the first respond ⇒ never speaks, never handles the second.
+    expect(respond).toHaveBeenCalledTimes(1);
+    expect(speak).not.toHaveBeenCalled();
+  });
+});