@kaleidorg/mind 0.3.0 → 0.5.0

package/src/lsps1/contract.ts

@@ -50,31 +50,49 @@ export const LSPS1_TOOLS: Lsps1ToolDef[] = [
     "Get the LSP's Lightning network info: pubkey, host, port, connect URI. Useful to display the counterparty or pre-connect a peer. No args."),
 
   t('lsp_estimate_fees',
-    "Estimate the fee for a channel order BEFORE committing. Returns the total cost in sats plus any LSP routing fee. Re-estimate rather than reusing a stale value.",
+    "Estimate the channel-order fee BEFORE committing. Returns setup_fee, capacity_fee, duration_fee, total_fee (all in sats). Re-estimate rather than reusing a stale value.",
     {
-      lsp_balance_sat:    { type: 'number', description: "Sats the LSP commits on their side (inbound capacity for the user)." },
-      client_balance_sat: { type: 'number', description: "Sats the user pre-funds into the channel (push amount). Often 0." },
-      channel_expiry_blocks: { type: 'number', description: 'Optional minimum lease in blocks. Defaults to the LSP minimum.' },
+      lsp_balance_sat:       { type: 'number', description: "Sats the LSP commits on their side (inbound capacity for the user)." },
+      client_balance_sat:    { type: 'number', description: "Sats the user pre-funds into the channel (push amount). Default 0." },
+      channel_expiry_blocks: { type: 'number', description: 'Lease duration in blocks. Default 4320 (~30 days). Maker maximum is typically 20160 (~140 days).' },
+      // RGB asset channels (optional):
+      asset_id:              { type: 'string', description: 'For RGB asset channels — the asset to provision liquidity for.' },
+      lsp_asset_amount:      { type: 'number', description: 'Asset units the LSP commits (RGB channels only).' },
+      client_asset_amount:   { type: 'number', description: 'Asset units the user pre-funds (RGB channels only). Requires rfq_id.' },
+      rfq_id:                { type: 'string', description: 'Quote id from kaleidoswap_get_quote — required when client_asset_amount > 0.' },
+      token:                 { type: 'string', description: 'Optional discount/affiliate token.' },
     },
-    ['lsp_balance_sat']),
+    ['lsp_balance_sat', 'client_balance_sat', 'channel_expiry_blocks']),
 
   t('lsp_create_order',
-    "Create a channel order. SPEND: confirmation-gated. Returns an order id + a Lightning invoice the user pays to lock the order. The channel opens only after payment.",
+    "Create a channel order. SPEND: confirmation-gated. Returns order_id + access_token + a payment.bolt11.invoice the user pays to lock the order. The channel opens only after payment.",
     {
-      lsp_balance_sat:    { type: 'number', description: "Sats the LSP commits on their side (inbound capacity for the user)." },
-      client_balance_sat: { type: 'number', description: 'Sats the user pre-funds. Often 0.' },
-      channel_expiry_blocks: { type: 'number', description: 'Minimum lease in blocks. Defaults to LSP minimum from lsp_get_info.' },
-      refund_onchain_address: { type: 'string', description: 'Optional on-chain refund address if the LSP cannot open the channel.' },
+      client_pubkey:                  { type: 'string', description: "User's Lightning node pubkey — the LSP opens the channel TO this node. Get it from rln_get_node_info." },
+      lsp_balance_sat:                { type: 'number', description: "Sats the LSP commits on their side (inbound capacity for the user)." },
+      client_balance_sat:             { type: 'number', description: "Sats the user pre-funds. Default 0." },
+      required_channel_confirmations: { type: 'number', description: 'Number of confs the user wants before considering the channel usable. Default 1.' },
+      funding_confirms_within_blocks: { type: 'number', description: 'Max blocks within which funding must confirm. Default 6.' },
+      channel_expiry_blocks:          { type: 'number', description: 'Lease duration in blocks. Default 4320 (~30 days).' },
+      announce_channel:               { type: 'boolean', description: 'Public (true) or unannounced (false). Default true.' },
+      refund_onchain_address:         { type: 'string', description: 'Optional on-chain refund address if the LSP cannot open the channel.' },
+      // RGB asset channels (optional):
+      asset_id:                       { type: 'string', description: 'For RGB asset channels.' },
+      lsp_asset_amount:               { type: 'number', description: 'Asset units the LSP commits.' },
+      client_asset_amount:            { type: 'number', description: 'Asset units the user pre-funds.' },
+      rfq_id:                         { type: 'string', description: 'Required when client_asset_amount > 0.' },
+      token:                          { type: 'string', description: 'Optional discount/affiliate token.' },
+      email:                          { type: 'string', description: 'Optional contact for order updates.' },
     },
-    ['lsp_balance_sat'],
+    ['client_pubkey', 'lsp_balance_sat'],
     /* spend */ true),
 
   t('lsp_get_order',
-    'Check the status of an LSPS1 order — pending / paid / opening / completed / failed. Poll after creating an order until the channel opens.',
+    'Check the status of an LSPS1 order. order_state progresses CREATED → CHANNEL_OPENING → COMPLETED (or FAILED). ALWAYS pass BOTH the order_id and the access_token from lsp_create_order (the access_token is required for order status).',
     {
-      order_id: { type: 'string', description: 'The order id from lsp_create_order.' },
+      order_id:     { type: 'string', description: 'The order id from lsp_create_order.' },
+      access_token: { type: 'string', description: 'The per-order access token returned by lsp_create_order. Required for non-admin reads.' },
     },
-    ['order_id']),
+    ['order_id', 'access_token']),
 ];
 
 /** All LSPS1 tool names that move funds (confirmation-gated). */

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();
+  });
+});

package/src/qvac/assistant.ts

@@ -0,0 +1,146 @@
+/**
+ * Hands-free voice-assistant loop — the transcribe → reason → speak cycle that
+ * QVAC's `transcribeStream()` makes possible, lifted into shared code so mobile
+ * and desktop run the same orchestration.
+ *
+ * The host owns the I/O: it opens the SDK session (`transcribeStream` with
+ * `DEFAULT_VOICE_STREAM_PARAMS`), feeds mic audio via `session.write()`, and
+ * supplies `respond` (LLM/funnel turn → reply text) + `speak` (synth + play).
+ * This loop does the parts that must be identical everywhere: filter Whisper's
+ * silence hallucinations, and gate the mic during playback so the assistant
+ * never transcribes its own voice (QVAC's reference uses a mic-gate, not
+ * barge-in — we mirror that).
+ */
+
+/** A transcript event from a `transcribeStream` conversation session. */
+export interface VoiceTranscriptEvent {
+  type: string;
+  /** Present on `text` events — a committed utterance. */
+  text?: string;
+}
+
+/** The host's transcription session (the SDK's conversation session fits). */
+export type VoiceAssistantSession = AsyncIterable<VoiceTranscriptEvent>;
+
+export type VoiceAssistantState = 'listening' | 'thinking' | 'speaking';
+
+export interface VoiceAssistantHandlers {
+  /** Produce an assistant reply for a user utterance (wraps the LLM/funnel). */
+  respond: (transcript: string) => Promise<string>;
+  /** Speak the reply: synth + playback. Resolves when playback finishes. */
+  speak: (text: string) => Promise<void>;
+  /**
+   * Gate mic capture so the assistant doesn't hear itself. The host should drop
+   * (not buffer) audio while gated. Called `true` before speaking, `false` after
+   * the post-playback cooldown.
+   */
+  setMicGated?: (gated: boolean) => void;
+  /** A user utterance passed the filter and is about to be handled. */
+  onUserText?: (text: string) => void;
+  /** The assistant's reply, before it is spoken. */
+  onReply?: (text: string) => void;
+  /** UI state transitions. */
+  onState?: (state: VoiceAssistantState) => void;
+}
+
+export interface VoiceAssistantOptions {
+  /** Minimum utterance length to handle (drops "you", ".", etc.). Default 3. */
+  minChars?: number;
+  /** Utterances to ignore (case-insensitive, trailing punctuation stripped). */
+  ignoredUtterances?: Iterable<string>;
+  /** Pause after playback so speaker reverb settles before listening. Default 300ms. */
+  postPlaybackCooldownMs?: number;
+  /** Injected for tests; defaults to setTimeout. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Stop the loop early. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Whisper frequently hallucinates these from silence — drop them so the
+ * assistant doesn't answer phantom turns. (QVAC docs cite "you", ".", "Thanks.")
+ */
+export const DEFAULT_IGNORED_UTTERANCES: readonly string[] = [
+  'you', 'thank you', 'thanks', 'bye', 'okay', '.',
+];
+
+/**
+ * Should this utterance be handled? False for too-short text or a known Whisper
+ * hallucination. Pure + exported so it's directly testable.
+ */
+export function shouldHandleUtterance(
+  text: string,
+  options: { minChars?: number; ignoredUtterances?: Iterable<string> } = {},
+): boolean {
+  const trimmed = text.trim();
+  if (trimmed.length < (options.minChars ?? 3)) return false;
+  const norm = trimmed.toLowerCase().replace(/[.!?,]+$/, '').trim();
+  if (!norm) return false;
+  const ignored = new Set(
+    [...(options.ignoredUtterances ?? DEFAULT_IGNORED_UTTERANCES)].map((s) => s.toLowerCase()),
+  );
+  return !ignored.has(norm);
+}
+
+/**
+ * Run the hands-free loop until the session ends or `signal` aborts. Only `text`
+ * events drive a turn; `vad`/`segment`/`endOfTurn` events are ignored here (the
+ * host can read them off the session separately for UI). Always leaves the mic
+ * un-gated on exit.
+ */
+export async function runVoiceAssistant(
+  session: VoiceAssistantSession,
+  handlers: VoiceAssistantHandlers,
+  options: VoiceAssistantOptions = {},
+): Promise<void> {
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const cooldown = options.postPlaybackCooldownMs ?? 300;
+  let speaking = false;
+
+  handlers.onState?.('listening');
+  try {
+    for await (const event of session) {
+      if (options.signal?.aborted) break;
+      if (event.type !== 'text' || typeof event.text !== 'string') continue;
+      // Defensive: ignore anything heard mid-playback (host also gates the mic).
+      if (speaking) continue;
+
+      const transcript = event.text.trim();
+      if (!shouldHandleUtterance(transcript, options)) continue;
+
+      handlers.onUserText?.(transcript);
+      handlers.onState?.('thinking');
+
+      let reply: string;
+      try {
+        reply = await handlers.respond(transcript);
+      } catch {
+        handlers.onState?.('listening');
+        continue;
+      }
+      if (options.signal?.aborted) break;
+      if (!reply || !reply.trim()) {
+        handlers.onState?.('listening');
+        continue;
+      }
+
+      handlers.onReply?.(reply);
+      speaking = true;
+      handlers.setMicGated?.(true);
+      handlers.onState?.('speaking');
+      try {
+        await handlers.speak(reply);
+      } catch {
+        /* keep the loop alive on a playback error */
+      } finally {
+        await sleep(cooldown);
+        speaking = false;
+        handlers.setMicGated?.(false);
+        handlers.onState?.('listening');
+      }
+    }
+  } finally {
+    // Never leave the mic gated if the loop exits mid-turn.
+    handlers.setMicGated?.(false);
+  }
+}

package/src/qvac/config.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import {
+  LOCAL_LLM_CONFIG,
+  LOCAL_LLM_CONFIG_GPU,
+  DELEGATE_LLM_CONFIG,
+  TTS_SAMPLE_RATE,
+  normalizeWhisperLang,
+} from './config.js';
+
+describe('model configs', () => {
+  it('CPU baseline runs on cpu with tools enabled', () => {
+    expect(LOCAL_LLM_CONFIG.device).toBe('cpu');
+    expect(LOCAL_LLM_CONFIG.tools).toBe(true);
+  });
+
+  it('GPU config offloads layers and grows the context', () => {
+    expect(LOCAL_LLM_CONFIG_GPU.device).toBe('gpu');
+    expect(LOCAL_LLM_CONFIG_GPU.gpu_layers).toBe(99);
+    expect(LOCAL_LLM_CONFIG_GPU.ctx_size).toBeGreaterThan(LOCAL_LLM_CONFIG.ctx_size);
+  });
+
+  it('delegate config gives the desktop the largest context', () => {
+    expect(DELEGATE_LLM_CONFIG.ctx_size).toBe(16384);
+    expect(DELEGATE_LLM_CONFIG.device).toBe('gpu');
+  });
+
+  it('TTS sample rate matches SUPERTONIC-2 output', () => {
+    expect(TTS_SAMPLE_RATE).toBe(44100);
+  });
+});
+
+describe('normalizeWhisperLang', () => {
+  it('extracts a supported 2-letter code from a locale', () => {
+    expect(normalizeWhisperLang('it-IT')).toBe('it');
+    expect(normalizeWhisperLang('en_US')).toBe('en');
+  });
+
+  it('falls back to en for unsupported or missing locales', () => {
+    expect(normalizeWhisperLang('xx-YY')).toBe('en');
+    expect(normalizeWhisperLang('')).toBe('en');
+    expect(normalizeWhisperLang(null)).toBe('en');
+    expect(normalizeWhisperLang(undefined)).toBe('en');
+  });
+});

package/src/qvac/config.ts

@@ -0,0 +1,76 @@
+/**
+ * QVAC model-load configs and constants, shared across every host. These are
+ * plain data (no SDK import) so they stay portable and testable; callers merge
+ * in SDK-specific bits like `verbosity: VERBOSITY.ERROR` at load time.
+ */
+
+/**
+ * CPU baseline for the local llamacpp model. Used as the GPU fallback and as the
+ * base the GPU attempt overrides (device + gpu_layers).
+ */
+export const LOCAL_LLM_CONFIG = {
+  device: 'cpu',
+  gpu_layers: 0,
+  ctx_size: 2048,
+  tools: true,
+} as const;
+
+/**
+ * GPU (Metal on iPhone) offload — far faster than CPU when llamacpp can init the
+ * Metal context in the worklet. Fall back to {@link LOCAL_LLM_CONFIG} if the GPU
+ * load throws. ctx 4096 fits the agentic prompt (system + tools + skills + a
+ * little history); 2048 overflowed immediately ("prompt exceeds context").
+ */
+export const LOCAL_LLM_CONFIG_GPU = {
+  ...LOCAL_LLM_CONFIG,
+  device: 'gpu',
+  gpu_layers: 99, // offload all layers; llamacpp clamps to the model's count
+  ctx_size: 4096,
+} as const;
+
+/**
+ * Delegated to a desktop provider — it has the RAM to run a big context, so give
+ * the agentic prompt plenty of room (Qwen3-600M supports up to 32k). 2048
+ * overflowed with the system prompt + tool/skill definitions alone.
+ */
+export const DELEGATE_LLM_CONFIG = {
+  ...LOCAL_LLM_CONFIG_GPU,
+  ctx_size: 16384,
+} as const;
+
+/** SUPERTONIC-2 TTS output sample rate (Hz). Used to build the WAV for playback. */
+export const TTS_SAMPLE_RATE = 44100;
+
+/**
+ * Default params for a hands-free `transcribeStream()` voice session (Whisper).
+ * `emitVadEvents` turns the session into a conversation stream (text + vad +
+ * endOfTurn events); `endOfTurnSilenceMs` is how long a pause must last before
+ * an utterance is committed — conservative so it doesn't cut speakers off mid
+ * sentence or trigger on TTS reverb. Hosts merge in `modelId` + spread these.
+ */
+export const DEFAULT_VOICE_STREAM_PARAMS = {
+  emitVadEvents: true,
+  endOfTurnSilenceMs: 700,
+} as const;
+
+/**
+ * Whisper languages we request directly from the device locale. whisper.cpp
+ * supports more, but the QVAC handler rejects "auto"/detect_language for these
+ * tiny models, so we pass a concrete code (and fall back to 'en').
+ */
+export const WHISPER_LANGS: ReadonlySet<string> = new Set([
+  'en', 'it', 'es', 'fr', 'de', 'pt', 'nl', 'ru', 'pl', 'uk', 'tr', 'ar',
+  'zh', 'ja', 'ko', 'hi', 'id', 'sv', 'no', 'da', 'fi', 'cs', 'ro', 'el',
+  'he', 'th', 'vi', 'hu', 'ca',
+]);
+
+/**
+ * Best-effort 2-letter Whisper language code from an OS locale string
+ * (e.g. "it-IT" → "it"), restricted to codes Whisper handles well. Falls back to
+ * 'en'. Pure: the host reads the locale (NativeModules etc.) and passes it here.
+ */
+export function normalizeWhisperLang(locale: string | null | undefined): string {
+  if (!locale) return 'en';
+  const code = String(locale).split(/[-_]/)[0]?.toLowerCase() ?? 'en';
+  return WHISPER_LANGS.has(code) ? code : 'en';
+}

package/src/qvac/delegate.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import {
+  allowListFirewall,
+  denyListFirewall,
+  firewallFromKeyList,
+  buildDelegateConfig,
+} from './delegate.js';
+
+describe('allowListFirewall', () => {
+  it('builds an allow-list, trimming + de-duping keys', () => {
+    expect(allowListFirewall([' k1 ', 'k2', 'k1', ''])).toEqual({
+      mode: 'allow',
+      publicKeys: ['k1', 'k2'],
+    });
+  });
+
+  it('is empty for no keys (caller must decide: open vs refuse)', () => {
+    expect(allowListFirewall([])).toEqual({ mode: 'allow', publicKeys: [] });
+  });
+});
+
+describe('denyListFirewall', () => {
+  it('builds a deny-list', () => {
+    expect(denyListFirewall(['bad'])).toEqual({ mode: 'deny', publicKeys: ['bad'] });
+  });
+});
+
+describe('firewallFromKeyList', () => {
+  it('parses comma/space/newline-separated keys into an allow-list', () => {
+    expect(firewallFromKeyList('k1, k2\nk3 k4')).toEqual({
+      mode: 'allow',
+      publicKeys: ['k1', 'k2', 'k3', 'k4'],
+    });
+  });
+
+  it('returns undefined for empty/missing input (advertise openly)', () => {
+    expect(firewallFromKeyList('')).toBeUndefined();
+    expect(firewallFromKeyList('   ')).toBeUndefined();
+    expect(firewallFromKeyList(null)).toBeUndefined();
+    expect(firewallFromKeyList(undefined)).toBeUndefined();
+  });
+});
+
+describe('buildDelegateConfig', () => {
+  it('defaults fallbackToLocal to false and trims the key', () => {
+    expect(buildDelegateConfig('  pk  ')).toEqual({
+      providerPublicKey: 'pk',
+      fallbackToLocal: false,
+    });
+  });
+
+  it('passes through fallbackToLocal, timeout, forceNewConnection when set', () => {
+    expect(
+      buildDelegateConfig('pk', { fallbackToLocal: true, timeout: 60000, forceNewConnection: true }),
+    ).toEqual({
+      providerPublicKey: 'pk',
+      fallbackToLocal: true,
+      timeout: 60000,
+      forceNewConnection: true,
+    });
+  });
+
+  it('omits optional fields that are not set', () => {
+    const cfg = buildDelegateConfig('pk', { fallbackToLocal: false });
+    expect('timeout' in cfg).toBe(false);
+    expect('forceNewConnection' in cfg).toBe(false);
+  });
+});

package/src/qvac/delegate.ts

@@ -0,0 +1,71 @@
+/**
+ * Delegation helpers — the provider firewall (who may connect) and the
+ * consumer-side delegate config. Pure data builders (no `@qvac/sdk` import) so
+ * they stay shared + testable; the host passes the result to
+ * `startQVACProvider({ firewall })` / `loadModel({ delegate })`.
+ *
+ * Security note: a QVAC provider is reachable by anyone who learns its
+ * Hyperswarm public key. Advertising with no firewall means any such peer can
+ * run inference on your machine. Use {@link allowListFirewall} so a desktop
+ * provider serves ONLY its paired phone(s).
+ */
+
+/** Firewall for `startQVACProvider` — restrict who may delegate to this provider. */
+export interface ProviderFirewall {
+  mode: 'allow' | 'deny';
+  publicKeys: string[];
+}
+
+function normalizeKeys(keys: Iterable<string>): string[] {
+  return [...new Set([...keys].map((k) => k.trim()).filter(Boolean))];
+}
+
+/**
+ * Allow ONLY these consumer public keys to delegate (zero-trust). Pass the
+ * paired phone(s)' public keys so no one else can use the desktop brain even if
+ * they learn its public key.
+ */
+export function allowListFirewall(consumerPublicKeys: Iterable<string>): ProviderFirewall {
+  return { mode: 'allow', publicKeys: normalizeKeys(consumerPublicKeys) };
+}
+
+/** Deny these consumer public keys; everyone else may connect. */
+export function denyListFirewall(consumerPublicKeys: Iterable<string>): ProviderFirewall {
+  return { mode: 'deny', publicKeys: normalizeKeys(consumerPublicKeys) };
+}
+
+/**
+ * Parse a comma/space/newline-separated key list (e.g. from an env var or a
+ * pairing store) into an allow-list firewall, or `undefined` when none are
+ * configured — the caller then advertises openly and should warn.
+ */
+export function firewallFromKeyList(raw: string | null | undefined): ProviderFirewall | undefined {
+  if (!raw) return undefined;
+  const keys = raw.split(/[\s,]+/).map((k) => k.trim()).filter(Boolean);
+  return keys.length ? allowListFirewall(keys) : undefined;
+}
+
+/** Consumer-side config for `loadModel({ delegate })`. */
+export interface DelegateConfig {
+  providerPublicKey: string;
+  fallbackToLocal: boolean;
+  timeout?: number;
+  forceNewConnection?: boolean;
+}
+
+/**
+ * Build the `delegate` config for a delegated `loadModel`. `fallbackToLocal`
+ * defaults to false (the host owns recovery), matching rate's existing
+ * LLM/Whisper/TTS delegated loads.
+ */
+export function buildDelegateConfig(
+  providerPublicKey: string,
+  opts: { fallbackToLocal?: boolean; timeout?: number; forceNewConnection?: boolean } = {},
+): DelegateConfig {
+  return {
+    providerPublicKey: providerPublicKey.trim(),
+    fallbackToLocal: opts.fallbackToLocal ?? false,
+    ...(opts.timeout != null ? { timeout: opts.timeout } : {}),
+    ...(opts.forceNewConnection != null ? { forceNewConnection: opts.forceNewConnection } : {}),
+  };
+}

package/src/qvac/index.ts

@@ -0,0 +1,72 @@
+/**
+ * @kaleidorg/mind-qvac — the single home for all @qvac/sdk logic behind
+ * @kaleidorg/mind. Hosts (rate mobile, desktop provider, cli) supply @qvac/sdk
+ * as a peer dependency; this package owns the orchestration so the logic lives
+ * in one place instead of drifting copies per host.
+ *
+ * This first slice exports the platform-agnostic core (pure text helpers, model
+ * configs, completion parsing). The QVAC-calling provider/voice/host wrappers
+ * land next, on top of these.
+ */
+export {
+  cleanAssistantVisibleText,
+  sanitizeForSupertonic,
+} from './text.js';
+
+export {
+  LOCAL_LLM_CONFIG,
+  LOCAL_LLM_CONFIG_GPU,
+  DELEGATE_LLM_CONFIG,
+  TTS_SAMPLE_RATE,
+  DEFAULT_VOICE_STREAM_PARAMS,
+  WHISPER_LANGS,
+  normalizeWhisperLang,
+} from './config.js';
+
+export {
+  finalToTurn,
+  type QvacFinalLike,
+  type ParsedTurn,
+} from './parse.js';
+
+export {
+  consumeRun,
+  type CompletionEventLike,
+  type CompletionRunLike,
+  type StreamHandlers,
+  type ConsumedTurn,
+} from './stream.js';
+
+export {
+  createQvacProvider,
+  type QvacProviderOptions,
+  type QvacTurnInput,
+} from './provider.js';
+
+export {
+  createQvacVoice,
+  type QvacVoice,
+  type QvacVoiceOptions,
+  type VoiceSession,
+  type PcmAudio,
+} from './voice.js';
+
+export {
+  runVoiceAssistant,
+  shouldHandleUtterance,
+  DEFAULT_IGNORED_UTTERANCES,
+  type VoiceAssistantSession,
+  type VoiceAssistantHandlers,
+  type VoiceAssistantOptions,
+  type VoiceAssistantState,
+  type VoiceTranscriptEvent,
+} from './assistant.js';
+
+export {
+  allowListFirewall,
+  denyListFirewall,
+  firewallFromKeyList,
+  buildDelegateConfig,
+  type ProviderFirewall,
+  type DelegateConfig,
+} from './delegate.js';