@kaleidorg/mind 0.3.0 → 0.5.0

package/src/qvac/parse.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { finalToTurn } from './parse.js';
+
+describe('finalToTurn', () => {
+  it('uses contentText for visible text and strips reasoning', () => {
+    const out = finalToTurn({ contentText: '<think>x</think>Hello' });
+    expect(out.text).toBe('Hello');
+  });
+
+  it('falls back to the streamed text when contentText is empty', () => {
+    const out = finalToTurn({ contentText: '' }, 'streamed answer');
+    expect(out.text).toBe('streamed answer');
+  });
+
+  it('prefers raw.fullText for rawContent (history push-back)', () => {
+    const out = finalToTurn({ contentText: 'Hi', raw: { fullText: 'FRAMED<tool/>Hi' } });
+    expect(out.rawContent).toBe('FRAMED<tool/>Hi');
+    expect(out.text).toBe('Hi');
+  });
+
+  it('falls back to the raw text for rawContent when no framed form', () => {
+    const out = finalToTurn({ contentText: 'Hi' });
+    expect(out.rawContent).toBe('Hi');
+  });
+
+  it('maps tool calls and defaults missing arguments to {}', () => {
+    const out = finalToTurn({
+      contentText: '',
+      toolCalls: [{ id: 'a', name: 'get_balance' }, { name: 'send', arguments: { sats: 5000 } }],
+    });
+    expect(out.toolCalls).toEqual([
+      { id: 'a', name: 'get_balance', arguments: {} },
+      { id: undefined, name: 'send', arguments: { sats: 5000 } },
+    ]);
+  });
+
+  it('flags truncation when the SDK stops on length', () => {
+    const out = finalToTurn({ contentText: 'partial', stopReason: 'length' });
+    expect(out.truncated).toBe(true);
+    expect(out.stopReason).toBe('length');
+  });
+
+  it('does not flag truncation on a natural stop', () => {
+    const out = finalToTurn({ contentText: 'done' });
+    expect(out.truncated).toBe(false);
+  });
+
+  it('handles an empty final without throwing', () => {
+    const out = finalToTurn({});
+    expect(out).toEqual({ text: '', rawContent: '', toolCalls: [], truncated: false, stopReason: undefined });
+  });
+});

package/src/qvac/parse.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure mapping from a QVAC completion `final` frame to the shape the shared
+ * @kaleidorg/mind Engine consumes. Kept SDK-free (structural input type) so it
+ * is testable without loading a model, and so the same mapping runs on mobile,
+ * desktop, and the eval harness.
+ */
+import { cleanAssistantVisibleText } from './text.js';
+
+/** Structural subset of a QVAC `completion().final` we depend on. */
+export interface QvacFinalLike {
+  /** Visible assistant text (excludes `<think>` reasoning). */
+  contentText?: string;
+  /** Raw assistant frame, incl. tool-call framing, for history push-back. */
+  raw?: { fullText?: string };
+  /** Tool calls the model requested this turn (empty ⇒ final answer). */
+  toolCalls?: Array<{ id?: string; name: string; arguments?: Record<string, unknown> }>;
+  /**
+   * Why generation stopped. QVAC 0.13 emits `"length"` when the token budget is
+   * exhausted, `"cancelled"` on abort, `undefined` on a natural stop. We surface
+   * it so the funnel can tell a truncated tool-call from a complete one.
+   */
+  stopReason?: 'length' | 'cancelled' | string;
+}
+
+export interface ParsedTurn {
+  /** Cleaned assistant content for display. */
+  text: string;
+  /** Raw assistant frame to push back into history for the next turn. */
+  rawContent: string;
+  /** Tool calls the model requested (arguments defaulted to `{}`). */
+  toolCalls: Array<{ id?: string; name: string; arguments: Record<string, unknown> }>;
+  /** True when generation was cut off by the token budget (incomplete output). */
+  truncated: boolean;
+  /** Raw stop reason from the SDK, when provided. */
+  stopReason?: string;
+}
+
+/**
+ * Map a completion `final` (plus the streamed fallback text) into a ParsedTurn.
+ * `rawContent` prefers the SDK's framed `raw.fullText` so the Engine can anchor
+ * the next turn; falls back to the visible text when a provider has no raw form.
+ */
+export function finalToTurn(final: QvacFinalLike, streamed = ''): ParsedTurn {
+  const rawText = final.contentText || streamed;
+  const text = cleanAssistantVisibleText(rawText);
+  return {
+    text,
+    rawContent: final.raw?.fullText ?? rawText,
+    toolCalls: (final.toolCalls ?? []).map((c) => ({
+      id: c.id,
+      name: c.name,
+      arguments: c.arguments ?? {},
+    })),
+    truncated: final.stopReason === 'length',
+    stopReason: final.stopReason,
+  };
+}

package/src/qvac/provider.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createQvacProvider } from './provider.js';
+
+/** A fake `completion` that records its params and replays scripted events. */
+function fakeCompletion(
+  final: Record<string, unknown>,
+  events: Array<{ type: string; text?: string }> = [],
+) {
+  const calls: any[] = [];
+  const fn = (params: any) => {
+    calls.push(params);
+    return {
+      requestId: 'req-1',
+      events: (async function* () {
+        for (const e of events) yield e;
+      })(),
+      final: Promise.resolve(final),
+    };
+  };
+  return { fn, calls };
+}
+
+const noopCancel = (async () => {}) as any;
+
+describe('createQvacProvider.runTurn', () => {
+  it('throws when no model is loaded', async () => {
+    const p = createQvacProvider({
+      completion: (() => { throw new Error('should not be called'); }) as any,
+      cancel: noopCancel,
+      getModelId: () => null,
+    });
+    await expect(p.runTurn({ messages: [{ role: 'user', content: 'hi' }], tools: [] }))
+      .rejects.toThrow(/not loaded/);
+  });
+
+  it('prepends the system message and sets generationParams + captureThinking', async () => {
+    const { fn, calls } = fakeCompletion({ contentText: 'Hello', toolCalls: [], raw: { fullText: 'Hello' } });
+    const p = createQvacProvider({
+      completion: fn as any,
+      cancel: noopCancel,
+      getModelId: () => 'm1',
+      defaultTemperature: 0.5,
+      defaultMaxTokens: 256,
+    });
+    const out = await p.runTurn({ system: 'You are X', messages: [{ role: 'user', content: 'hi' }], tools: [] });
+    expect(out.text).toBe('Hello');
+
+    const params = calls[0];
+    expect(params.modelId).toBe('m1');
+    expect(params.history).toEqual([
+      { role: 'system', content: 'You are X' },
+      { role: 'user', content: 'hi' },
+    ]);
+    expect(params.stream).toBe(true);
+    expect(params.captureThinking).toBe(true);
+    expect(params.generationParams).toEqual({ temp: 0.5, predict: 256 });
+    expect(params.tools).toBeUndefined();
+  });
+
+  it('maps tools by schema and honours per-call temperature/maxTokens', async () => {
+    const { fn, calls } = fakeCompletion({
+      contentText: '',
+      toolCalls: [{ id: 'a', name: 'get_balance', arguments: {} }],
+      raw: { fullText: '' },
+    });
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1' });
+    const out = await p.runTurn({
+      messages: [{ role: 'user', content: 'balance?' }],
+      tools: [{ name: 'get_balance', description: 'balance', parameters: { shape: true } }],
+      temperature: 0.9,
+      maxTokens: 99,
+    } as any);
+
+    expect(out.toolCalls).toEqual([{ id: 'a', name: 'get_balance', arguments: {} }]);
+    const params = calls[0];
+    expect(params.tools).toEqual([{ name: 'get_balance', description: 'balance', parameters: { shape: true } }]);
+    expect(params.generationParams).toEqual({ temp: 0.9, predict: 99 });
+  });
+
+  it('omits generationParams when no temperature/maxTokens is set (keeps SDK defaults)', async () => {
+    const { fn, calls } = fakeCompletion({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } });
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1' });
+    await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [] });
+    expect(calls[0].generationParams).toBeUndefined();
+  });
+
+  it('streams visible content tokens to onToken', async () => {
+    const { fn } = fakeCompletion(
+      { contentText: 'Hi there', toolCalls: [], raw: { fullText: 'Hi there' } },
+      [{ type: 'contentDelta', text: 'Hi ' }, { type: 'contentDelta', text: 'there' }],
+    );
+    const tokens: string[] = [];
+    const p = createQvacProvider({ completion: fn as any, cancel: noopCancel, getModelId: () => 'm1' });
+    await p.runTurn({ messages: [{ role: 'user', content: 'x' }], tools: [], onToken: (t) => tokens.push(t) });
+    expect(tokens).toEqual(['Hi ', 'there']);
+  });
+});
+
+describe('createQvacProvider.cancel', () => {
+  it('forwards the requestId to the SDK cancel', async () => {
+    const cancel = vi.fn(async () => {});
+    const { fn } = fakeCompletion({ contentText: 'ok', toolCalls: [], raw: { fullText: 'ok' } });
+    const p = createQvacProvider({ completion: fn as any, cancel: cancel as any, getModelId: () => 'm1' });
+    await p.cancel!('req-9');
+    expect(cancel).toHaveBeenCalledWith({ requestId: 'req-9' });
+  });
+});

package/src/qvac/provider.ts

@@ -0,0 +1,124 @@
+/**
+ * createQvacProvider — turns `@qvac/sdk` `completion()` into the shared
+ * `@kaleidorg/mind` `LLMProvider` the Engine/Funnel consumes. This is the one
+ * place the SDK is called for inference; every host (rate, desktop provider,
+ * cli) uses it instead of hand-rolling its own completion wrapper.
+ *
+ * The SDK functions are *injected*, not imported, so this package carries no
+ * runtime dependency on `@qvac/sdk` (the import below is type-only and erased).
+ * Hosts pass their own `completion`/`cancel` — rate the static RN import, the
+ * desktop sidecar its lazily-loaded SDK facade — which also makes this provider
+ * unit-testable with a fake completion.
+ *
+ * The host owns model lifecycle (load/unload, local-vs-delegated) and passes
+ * `getModelId()` so a turn always runs against the currently-loaded model.
+ * Tools are forwarded by schema only; the Engine executes them via its
+ * ToolSources, so signing/spending stays on the host even when inference is
+ * delegated to a desktop peer.
+ */
+import type * as QvacSdk from '@qvac/sdk';
+import type { LLMProvider, TurnInput, TurnOutput } from '../providers/types.js';
+import { consumeRun } from './stream.js';
+
+type CompletionFn = typeof QvacSdk.completion;
+type CancelFn = typeof QvacSdk.cancel;
+
+export interface QvacProviderOptions {
+  /** The SDK's `completion` (injected — see module docs). */
+  completion: CompletionFn;
+  /** The SDK's `cancel` (injected). */
+  cancel: CancelFn;
+  /** Resolve the loaded model id for this turn (null ⇒ not loaded → throws). */
+  getModelId: () => string | null;
+  /**
+   * Default sampling temperature. Omit to leave it to the SDK/model default —
+   * `generationParams` is only sent when a temperature or max-tokens is set, so
+   * a host that passes neither preserves the SDK's own defaults.
+   */
+  defaultTemperature?: number;
+  /** Default max output tokens — caps a turn so it can't ramble. Omit for uncapped. */
+  defaultMaxTokens?: number;
+  /** Stream the model's `<think>` reasoning, when a host wants to surface it. */
+  onThinking?: (token: string) => void;
+}
+
+/** TurnInput plus the per-call knobs the funnel/voice paths pass through. */
+export interface QvacTurnInput extends TurnInput {
+  temperature?: number;
+  maxTokens?: number;
+  onThinking?: (token: string) => void;
+}
+
+export function createQvacProvider(options: QvacProviderOptions): LLMProvider {
+  return {
+    name: 'qvac',
+
+    async runTurn(input: QvacTurnInput): Promise<TurnOutput> {
+      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 } : {}),
+      } as unknown as Parameters<CompletionFn>[0]);
+
+      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: string): Promise<void> {
+      // 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);
+      }
+    },
+  };
+}

package/src/qvac/stream.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect } from 'vitest';
+import { consumeRun, type CompletionEventLike, type CompletionRunLike } from './stream.js';
+import type { QvacFinalLike } from './parse.js';
+
+function fakeRun(
+  events: CompletionEventLike[],
+  final: QvacFinalLike,
+  requestId = 'req-1',
+): CompletionRunLike {
+  return {
+    requestId,
+    events: (async function* () {
+      for (const e of events) yield e;
+    })(),
+    final: Promise.resolve(final),
+  };
+}
+
+describe('consumeRun', () => {
+  it('forwards visible content tokens and accumulates the streamed fallback', async () => {
+    const tokens: string[] = [];
+    const run = fakeRun(
+      [
+        { type: 'contentDelta', text: 'Hel' },
+        { type: 'contentDelta', text: 'lo' },
+      ],
+      { contentText: '', toolCalls: [], raw: { fullText: '' } },
+    );
+    const out = await consumeRun(run, { onToken: (t) => tokens.push(t) });
+    expect(tokens).toEqual(['Hel', 'lo']);
+    // contentText empty ⇒ falls back to the streamed accumulation.
+    expect(out.text).toBe('Hello');
+  });
+
+  it('routes thinkingDelta to onThinking, not onToken', async () => {
+    const visible: string[] = [];
+    const thinking: string[] = [];
+    const run = fakeRun(
+      [
+        { type: 'thinkingDelta', text: 'plan…' },
+        { type: 'contentDelta', text: 'Answer' },
+      ],
+      { contentText: 'Answer', toolCalls: [], raw: { fullText: 'Answer' } },
+    );
+    await consumeRun(run, {
+      onToken: (t) => visible.push(t),
+      onThinking: (t) => thinking.push(t),
+    });
+    expect(visible).toEqual(['Answer']);
+    expect(thinking).toEqual(['plan…']);
+  });
+
+  it('returns parsed tool calls + requestId and flags truncation from stopReason', async () => {
+    const run = fakeRun(
+      [],
+      {
+        contentText: 'partial',
+        toolCalls: [{ id: 't1', name: 'get_balance', arguments: {} }],
+        raw: { fullText: 'partial' },
+        stopReason: 'length',
+      },
+      'req-xyz',
+    );
+    const out = await consumeRun(run);
+    expect(out.requestId).toBe('req-xyz');
+    expect(out.toolCalls).toEqual([{ id: 't1', name: 'get_balance', arguments: {} }]);
+    expect(out.truncated).toBe(true);
+  });
+
+  it('ignores delta events with no text', async () => {
+    const tokens: string[] = [];
+    const run = fakeRun(
+      [{ type: 'contentDelta' }, { type: 'toolCall' }, { type: 'contentDelta', text: 'hi' }],
+      { contentText: 'hi', toolCalls: [], raw: { fullText: 'hi' } },
+    );
+    await consumeRun(run, { onToken: (t) => tokens.push(t) });
+    expect(tokens).toEqual(['hi']);
+  });
+});

package/src/qvac/stream.ts

@@ -0,0 +1,56 @@
+/**
+ * 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, 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 async function consumeRun(
+  run: CompletionRunLike,
+  handlers: StreamHandlers = {},
+): Promise<ConsumedTurn> {
+  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 };
+}

package/src/qvac/text.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { cleanAssistantVisibleText, sanitizeForSupertonic } from './text.js';
+
+describe('cleanAssistantVisibleText', () => {
+  it('strips a closed <think> block', () => {
+    expect(cleanAssistantVisibleText('<think>plan the answer</think>Your balance is 5k sats.'))
+      .toBe('Your balance is 5k sats.');
+  });
+
+  it('strips an unclosed <think> tail', () => {
+    expect(cleanAssistantVisibleText('Done.<think>still reasoning'))
+      .toBe('Done.');
+  });
+
+  it('drops a leading tool-call prefix and keeps the sentence after it', () => {
+    // The heuristic strips up to `"arguments":` then one `{`. Cleanly recovers
+    // the tail when the model emits the framing without real JSON args.
+    const raw = '{"name":"get_balance","arguments": You have 5,000 sats.';
+    expect(cleanAssistantVisibleText(raw)).toBe('You have 5,000 sats.');
+  });
+
+  it('is lossy when real JSON args follow (known heuristic limit, stray braces remain)', () => {
+    // Documents current behaviour verbatim from rate; a candidate for a future
+    // balanced-brace fix once it can be re-verified on device.
+    const raw = '{"name":"get_balance","arguments":{}} You have 5,000 sats.';
+    expect(cleanAssistantVisibleText(raw)).toBe('}} You have 5,000 sats.');
+  });
+
+  it('collapses whitespace and trims', () => {
+    expect(cleanAssistantVisibleText('  hello   world  ')).toBe('hello world');
+  });
+
+  it('leaves plain text untouched', () => {
+    expect(cleanAssistantVisibleText('Sent 3 EUR to bob.')).toBe('Sent 3 EUR to bob.');
+  });
+});
+
+describe('sanitizeForSupertonic', () => {
+  it('redacts a bolt11 lightning invoice', () => {
+    const out = sanitizeForSupertonic('Pay lnbc1' + 'q'.repeat(60) + ' now');
+    expect(out).toContain('Lightning invoice');
+    expect(out).not.toMatch(/lnbc1q/i);
+  });
+
+  it('redacts an lnurl string', () => {
+    const out = sanitizeForSupertonic('Use lnurl1' + 'a'.repeat(50));
+    expect(out).toContain('Lightning payment link');
+    expect(out).not.toMatch(/lnurl1a/i);
+  });
+
+  it('strips fenced code blocks and inline backticks', () => {
+    const out = sanitizeForSupertonic('Run ```rm -rf``` or `ls` here');
+    expect(out).not.toContain('`');
+    expect(out).toContain('ls');
+  });
+
+  it('removes the backtick character (U+0060) entirely', () => {
+    const out = sanitizeForSupertonic('a`b`c');
+    expect(Array.from(out).some((ch) => ch.charCodeAt(0) === 0x60)).toBe(false);
+  });
+
+  it('normalizes smart quotes to ASCII', () => {
+    const out = sanitizeForSupertonic('“hello” ‘world’');
+    expect(out).toBe('"hello" \'world\'');
+  });
+
+  it('drops non-ASCII and collapses whitespace', () => {
+    expect(sanitizeForSupertonic('café   ✨ ok')).toBe('caf ok');
+  });
+});

package/src/qvac/text.ts

@@ -0,0 +1,60 @@
+/**
+ * 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: string): string {
+  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: string): string {
+  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();
+}