@kaleidorg/mind 0.2.0 → 0.4.0

package/src/memory/memory.test.ts

@@ -61,6 +61,61 @@ describe('InMemoryMemoryStore', () => {
     const hits = await store.search({ text: 'how many sats do I have', limit: 1 });
     expect(hits[0].text).toMatch(/wallet balance/);
   });
+
+  // Embedding-only dedup: same vector → near-dup → newer supersedes older. No LLM.
+  it('consolidate (dedup): near-duplicates supersede instead of appending', async () => {
+    const embed = async (text: string): Promise<number[]> =>
+      /eur/i.test(text) ? [1, 0] : [0, 1];
+    let t = 0;
+    const store = new InMemoryMemoryStore({
+      embed,
+      consolidate: { threshold: 0.9 },
+      now: () => ++t,
+    });
+    await store.add({ text: 'user prefers EUR', kind: 'preference' });
+    await store.add({ text: 'user prefers EUR for fiat display', kind: 'preference' });
+
+    const all = await store.all();
+    expect(all).toHaveLength(1); // folded, not appended
+    expect(all[0].text).toBe('user prefers EUR for fiat display'); // newer wins
+  });
+
+  it('consolidate (dedup): distinct facts are kept separate', async () => {
+    const embed = async (text: string): Promise<number[]> =>
+      /eur/i.test(text) ? [1, 0] : [0, 1];
+    const store = new InMemoryMemoryStore({ embed, consolidate: { threshold: 0.9 }, now: () => 1 });
+    await store.add({ text: 'user prefers EUR', kind: 'preference' });
+    await store.add({ text: 'it is sunny today', kind: 'note' });
+    expect(await store.all()).toHaveLength(2);
+  });
+
+  it('consolidate (dedup): different kinds are never merged', async () => {
+    const embed = async (): Promise<number[]> => [1, 0]; // identical vectors
+    const store = new InMemoryMemoryStore({ embed, consolidate: { threshold: 0.9 }, now: () => 1 });
+    await store.add({ text: 'EUR', kind: 'preference' });
+    await store.add({ text: 'EUR', kind: 'fact' });
+    expect(await store.all()).toHaveLength(2);
+  });
+
+  // LLM merge: injected merger rewrites old + new into one consolidated item, with unioned tags.
+  it('consolidate (merge): injected merger folds near-dups into one item', async () => {
+    const embed = async (): Promise<number[]> => [1, 0];
+    const merge = vi.fn(async (existing: string, incoming: string) => `${existing}; ${incoming}`);
+    let t = 0;
+    const store = new InMemoryMemoryStore({
+      embed,
+      consolidate: { threshold: 0.9, merge },
+      now: () => ++t,
+    });
+    await store.add({ text: 'likes EUR', kind: 'preference', tags: ['fiat'] });
+    await store.add({ text: 'and CHF', kind: 'preference', tags: ['currency'] });
+
+    expect(merge).toHaveBeenCalledWith('likes EUR', 'and CHF');
+    const all = await store.all();
+    expect(all).toHaveLength(1);
+    expect(all[0].text).toBe('likes EUR; and CHF');
+    expect(all[0].tags).toEqual(['fiat', 'currency']); // unioned
+  });
 });
 
 describe('memory tool source', () => {

package/src/memory/store.ts

@@ -9,6 +9,7 @@
 
 import { cosineSimilarity } from '../rag/vector-store.js';
 import type {
+  MemoryConsolidation,
   MemoryIO,
   MemoryItem,
   MemoryQuery,
@@ -16,11 +17,18 @@ import type {
   NewMemory,
 } from './types.js';
 
+const DEFAULT_DEDUP_THRESHOLD = 0.92;
+
 export interface MemoryStoreOptions {
   /** Persistence (load on first use, save on writes). Omit for ephemeral memory. */
   io?: MemoryIO;
   /** Embed text for semantic recall. Omit to fall back to substring matching. */
   embed?: (text: string) => Promise<number[]>;
+  /**
+   * Fold near-duplicate writes into one item instead of appending. Needs `embed`.
+   * Omit for append-only. See {@link MemoryConsolidation}.
+   */
+  consolidate?: MemoryConsolidation;
   /** Clock — injectable for deterministic tests. */
   now?: () => number;
 }
@@ -31,11 +39,13 @@ export class InMemoryMemoryStore implements MemoryStore {
   private counter = 0;
   private readonly io?: MemoryIO;
   private readonly embed?: (text: string) => Promise<number[]>;
+  private readonly consolidate?: MemoryConsolidation;
   private readonly now: () => number;
 
   constructor(opts: MemoryStoreOptions = {}) {
     this.io = opts.io;
     this.embed = opts.embed;
+    this.consolidate = opts.consolidate;
     this.now = opts.now ?? (() => Date.now());
   }
 
@@ -58,16 +68,45 @@ export class InMemoryMemoryStore implements MemoryStore {
 
   async add(item: NewMemory): Promise<MemoryItem> {
     await this.hydrate();
-    const embedding =
-      item.embedding ?? (this.embed ? await this.embed(item.text).catch(() => undefined) : undefined);
+    let text = item.text;
+    let embedding =
+      item.embedding ?? (this.embed ? await this.embed(text).catch(() => undefined) : undefined);
+    let tags = item.tags;
+    let supersedeId: string | undefined;
+
+    // Consolidation: fold a same-kind near-duplicate into this write instead of
+    // appending — embedding-only by default, LLM rewrite when `merge` is set.
+    if (this.consolidate && embedding) {
+      const threshold = this.consolidate.threshold ?? DEFAULT_DEDUP_THRESHOLD;
+      let best: { item: MemoryItem; score: number } | undefined;
+      for (const m of this.items) {
+        if (m.kind !== item.kind || !m.embedding) continue;
+        const score = cosineSimilarity(embedding, m.embedding);
+        if (!best || score > best.score) best = { item: m, score };
+      }
+      if (best && best.score >= threshold) {
+        supersedeId = best.item.id;
+        tags = unionTags(best.item.tags, item.tags);
+        if (this.consolidate.merge) {
+          const merged = await this.consolidate.merge(best.item.text, text).catch(() => null);
+          if (merged && merged.trim()) {
+            text = merged.trim();
+            if (this.embed) embedding = await this.embed(text).catch(() => embedding);
+          }
+        }
+        // No merger → the incoming (newer) text supersedes the older item as-is.
+      }
+    }
+
     const full: MemoryItem = {
       id: item.id ?? `mem_${this.now()}_${++this.counter}`,
-      text: item.text,
+      text,
       kind: item.kind,
-      tags: item.tags,
+      tags,
       createdAt: item.createdAt ?? this.now(),
       ...(embedding ? { embedding } : {}),
     };
+    if (supersedeId) this.items = this.items.filter((m) => m.id !== supersedeId);
     this.items.push(full);
     await this.persist();
     return full;
@@ -127,3 +166,9 @@ export class InMemoryMemoryStore implements MemoryStore {
     await this.persist();
   }
 }
+
+/** Merge two optional tag lists, de-duplicated. Returns undefined when both empty. */
+function unionTags(a?: string[], b?: string[]): string[] | undefined {
+  if (!a?.length && !b?.length) return undefined;
+  return [...new Set([...(a ?? []), ...(b ?? [])])];
+}

package/src/memory/types.ts

@@ -61,3 +61,16 @@ export interface MemoryIO {
   load(): Promise<MemoryItem[]>;
   save(items: MemoryItem[]): Promise<void>;
 }
+
+/**
+ * Consolidation — fold same-kind near-duplicate memories into one item instead
+ * of bloating with "user likes EUR" ×5. Needs embeddings (the dup check is
+ * cosine). Omit for append-only. Two tiers: embedding-only dedup (zero
+ * inference, mobile-safe) and, when `merge` is set, an LLM rewrite.
+ */
+export interface MemoryConsolidation {
+  /** Cosine threshold above which two same-kind memories are "the same". Default 0.92. */
+  threshold?: number;
+  /** Optional LLM merger; without it the newer item simply supersedes the older. */
+  merge?: (existing: string, incoming: string) => Promise<string>;
+}

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