@moxxy/core 0.3.0

package/src/preferences.test.ts

@@ -0,0 +1,105 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { loadPreferences, preferencesPath, savePreferences } from './preferences.js';
+
+// preferencesPath() resolves ~/.moxxy/preferences.json via os.homedir(), which
+// derives from HOME (POSIX) / USERPROFILE (Windows). Point both at a tmpdir per
+// test so the suite never touches the developer's real preferences file.
+let tmpHome: string;
+let savedHome: string | undefined;
+let savedUserProfile: string | undefined;
+
+beforeEach(async () => {
+  tmpHome = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-prefs-'));
+  savedHome = process.env.HOME;
+  savedUserProfile = process.env.USERPROFILE;
+  process.env.HOME = tmpHome;
+  process.env.USERPROFILE = tmpHome;
+  await fs.mkdir(path.join(tmpHome, '.moxxy'), { recursive: true });
+});
+
+afterEach(async () => {
+  if (savedHome === undefined) delete process.env.HOME;
+  else process.env.HOME = savedHome;
+  if (savedUserProfile === undefined) delete process.env.USERPROFILE;
+  else process.env.USERPROFILE = savedUserProfile;
+  await fs.rm(tmpHome, { recursive: true, force: true });
+});
+
+const readRaw = async (): Promise<unknown> =>
+  JSON.parse(await fs.readFile(preferencesPath(), 'utf8'));
+
+describe('preferences store', () => {
+  it('resolves the path under the (overridden) home dir', () => {
+    expect(preferencesPath()).toBe(path.join(tmpHome, '.moxxy', 'preferences.json'));
+  });
+
+  it('returns an empty object when the file is missing', async () => {
+    expect(await loadPreferences()).toEqual({});
+  });
+
+  it('returns an empty object when the file is corrupt', async () => {
+    await fs.writeFile(preferencesPath(), '{ not json', 'utf8');
+    expect(await loadPreferences()).toEqual({});
+  });
+
+  it('round-trips a patch through disk', async () => {
+    await savePreferences({ model: 'gpt-5.4-mini', providerName: 'openai' });
+    const loaded = await loadPreferences();
+    expect(loaded.model).toBe('gpt-5.4-mini');
+    expect(loaded.providerName).toBe('openai');
+  });
+
+  it('merges a second patch without clobbering unrelated fields', async () => {
+    await savePreferences({ providerName: 'openai' });
+    await savePreferences({ model: 'gpt-5.4-mini' });
+    const loaded = await loadPreferences();
+    expect(loaded.providerName).toBe('openai');
+    expect(loaded.model).toBe('gpt-5.4-mini');
+  });
+
+  it('migrates legacy mode names on load', async () => {
+    // "tool-use" is the legacy id that migrateModeName maps to "default".
+    await fs.writeFile(
+      preferencesPath(),
+      JSON.stringify({ mode: 'tool-use' }) + '\n',
+      'utf8',
+    );
+    const loaded = await loadPreferences();
+    expect(loaded.mode).toBe('default');
+  });
+
+  it('writes a trailing newline atomically (no partial file)', async () => {
+    await savePreferences({ model: 'm1' });
+    const raw = await fs.readFile(preferencesPath(), 'utf8');
+    expect(raw.endsWith('\n')).toBe(true);
+    expect(JSON.parse(raw)).toEqual({ model: 'm1' });
+  });
+
+  it('serializes overlapping saves so no update is lost (invariant #5)', async () => {
+    // Two patches firing concurrently each read-merge-write the same file.
+    // Without the mutex the later writer clobbers the earlier writer's field.
+    await Promise.all([
+      savePreferences({ model: 'a' }),
+      savePreferences({ mode: 'goal' }),
+    ]);
+    const loaded = await loadPreferences();
+    expect(loaded.model).toBe('a');
+    expect(loaded.mode).toBe('goal');
+  });
+
+  it('keeps ALL distinct keys present under many overlapping writers', async () => {
+    const patches: Array<Partial<Record<`k${number}`, string>>> = [];
+    for (let i = 0; i < 25; i++) patches.push({ [`k${i}`]: `v${i}` });
+    // Fire all saves at once; each merges a distinct key.
+    await Promise.all(
+      patches.map((p) => savePreferences(p as Record<string, string>)),
+    );
+    const loaded = (await readRaw()) as Record<string, string>;
+    for (let i = 0; i < 25; i++) {
+      expect(loaded[`k${i}`]).toBe(`v${i}`);
+    }
+  });
+});

package/src/preferences.ts

@@ -0,0 +1,84 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { createMutex, migrateModeName } from '@moxxy/sdk';
+import { writeFileAtomic } from '@moxxy/sdk/server';
+
+/**
+ * User-level runtime preferences persisted at ~/.moxxy/preferences.json.
+ * Distinct from `~/.moxxy/config.yaml` (user-edited, source of truth for
+ * provider/plugin wiring) — this file is mutated by the TUI as the user
+ * picks a model / loop strategy via slash commands, so it survives across
+ * CLI invocations. A missing file or unreadable contents is a no-op:
+ * preferences are best-effort, never load-blocking.
+ */
+export interface MoxxyPreferences {
+  /** Active provider name (e.g. "openai", "anthropic"). */
+  readonly providerName?: string;
+  /** Active model id under that provider (e.g. "gpt-5.4-mini"). */
+  readonly model?: string;
+  /** Active loop strategy name (e.g. "default", "research", "goal"). */
+  readonly mode?: string;
+  /**
+   * Providers the user disabled (desktop Settings → Providers toggle).
+   * Seeded into the ProviderRegistry at boot; a listed provider stays
+   * registered but can't be activated until re-enabled.
+   */
+  readonly disabledProviders?: ReadonlyArray<string>;
+}
+
+export function preferencesPath(): string {
+  return path.join(os.homedir(), '.moxxy', 'preferences.json');
+}
+
+/**
+ * Read preferences from disk. Returns an empty object when the file
+ * doesn't exist or fails to parse — preferences are an optional layer,
+ * never a hard dependency of session bootstrap.
+ */
+export async function loadPreferences(): Promise<MoxxyPreferences> {
+  try {
+    const raw = await fs.readFile(preferencesPath(), 'utf8');
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed && typeof parsed === 'object') {
+      const prefs = parsed as MoxxyPreferences;
+      return prefs.mode ? { ...prefs, mode: migrateModeName(prefs.mode) } : prefs;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+// Serializes the read-modify-write in `savePreferences` so two concurrent
+// saves (e.g. a /model pick and a provider-disable toggle firing close
+// together) can't both read the same snapshot and have the second write
+// clobber the first's field. This is the single write path for the file —
+// other packages (CLI, runner, channels) route their fire-and-forget saves
+// through it, and any load-modify-save must go through it too.
+const writeMutex = createMutex();
+
+/**
+ * Merge-and-write preferences. Reads the current file (if any), merges
+ * the patch on top so we don't blow away unrelated fields, and writes
+ * the result back atomically. The whole read-merge-write runs inside a
+ * module-level mutex so overlapping saves serialize (invariant #5) and
+ * never lose an update. Best-effort: a write failure logs to stderr but
+ * does not throw — the user's pick still takes effect in this session,
+ * just won't persist across invocations.
+ */
+export async function savePreferences(patch: Partial<MoxxyPreferences>): Promise<void> {
+  return writeMutex.run(async () => {
+    const current = await loadPreferences();
+    const next: MoxxyPreferences = { ...current, ...patch };
+    const target = preferencesPath();
+    try {
+      await writeFileAtomic(target, JSON.stringify(next, null, 2) + '\n');
+    } catch (err) {
+      process.stderr.write(
+        `moxxy: failed to persist preferences to ${target}: ` +
+          `${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    }
+  });
+}

package/src/registries/active-backend-registry.ts

@@ -0,0 +1,142 @@
+/**
+ * Shared base for the "single active backend" registries (speech-to-text,
+ * text-to-speech, embeddings). Each one is a Map of named defs with at most one
+ * *active* at a time:
+ *   - plugins call `register(def)` at load time
+ *   - the host / CLI / agent calls `setActive(name, config)` to pick one
+ *   - call sites read `getActive()` / `tryGetActive()` to use it (degrading
+ *     gracefully when none is active)
+ *
+ * The three concrete registries differ only along a few axes, expressed via
+ * {@link BackendRegistryOptions}:
+ *   - how a def becomes an instance (`build`) — `createClient(config)` for
+ *     STT/embeddings, `create({ config, getSecret })` for TTS
+ *   - whether the first registered def auto-becomes active (`autoAdoptFirst`,
+ *     TTS only — STT/embeddings require an explicit `setActive`)
+ *   - whether the active instance is (re)built lazily on read (`buildOnRead`,
+ *     TTS only — needed because `autoAdoptFirst` can set `active` without ever
+ *     building an instance; it also makes `setActive` rebuild when handed a
+ *     fresh config)
+ *
+ * `ProviderRegistry` deliberately stays separate: it is the core LLM path and
+ * carries its own ready-state semantics.
+ */
+export interface BackendRegistryOptions<TDef extends { name: string }, TInstance> {
+  /** Capitalised singular noun for error messages, e.g. `'Synthesizer'`. */
+  readonly noun: string;
+  /** Turn a def + (possibly empty) config into a runtime instance. */
+  readonly build: (def: TDef, config: Record<string, unknown>) => TInstance;
+  /** Adopt the first registered def as active when nothing is active yet. */
+  readonly autoAdoptFirst?: boolean;
+  /** (Re)build the active instance lazily on read rather than requiring it to
+   *  have been built at `setActive` time. Also makes `setActive` rebuild when a
+   *  config is supplied. Pair with {@link autoAdoptFirst}. */
+  readonly buildOnRead?: boolean;
+}
+
+export class ActiveBackendRegistry<TDef extends { name: string }, TInstance> {
+  private readonly defs = new Map<string, TDef>();
+  private readonly instances = new Map<string, TInstance>();
+  private active: string | null = null;
+
+  constructor(private readonly opts: BackendRegistryOptions<TDef, TInstance>) {}
+
+  register(def: TDef, instance?: TInstance): void {
+    if (this.defs.has(def.name)) {
+      throw new Error(`${this.opts.noun} already registered: ${def.name}`);
+    }
+    this.defs.set(def.name, def);
+    if (instance) this.instances.set(def.name, instance);
+    if (this.opts.autoAdoptFirst && this.active === null) this.active = def.name;
+  }
+
+  /** Overwrite an existing def, dropping the cached instance so the next build
+   *  uses the new def. */
+  replace(def: TDef, instance?: TInstance): void {
+    this.defs.set(def.name, def);
+    this.instances.delete(def.name);
+    if (instance) this.instances.set(def.name, instance);
+  }
+
+  unregister(name: string): void {
+    this.defs.delete(name);
+    this.instances.delete(name);
+    if (this.active === name) this.active = null;
+  }
+
+  list(): ReadonlyArray<TDef> {
+    return [...this.defs.values()];
+  }
+
+  has(name: string): boolean {
+    return this.defs.has(name);
+  }
+
+  setActive(name: string, config?: Record<string, unknown>): TInstance {
+    if (!this.defs.has(name)) throw new Error(`${this.opts.noun} not registered: ${name}`);
+    if (this.opts.buildOnRead) {
+      // Supplying a config (re)builds with it; otherwise reuse / lazily build.
+      if (config) this.instances.set(name, this.buildInstance(name, config));
+      this.active = name;
+      return this.instantiate(name);
+    }
+    // Build once, on first activation; later activations reuse the cache and
+    // ignore `config`.
+    let instance = this.instances.get(name);
+    if (!instance) {
+      instance = this.buildInstance(name, config);
+      this.instances.set(name, instance);
+    }
+    this.active = name;
+    return instance;
+  }
+
+  /** Deactivate the current backend (callers fall back to their default). */
+  clearActive(): void {
+    this.active = null;
+  }
+
+  getActive(): TInstance {
+    if (!this.active) {
+      throw new Error(`No active ${this.opts.noun.toLowerCase()}. Call setActive(name) first.`);
+    }
+    if (this.opts.buildOnRead) return this.instantiate(this.active);
+    const inst = this.instances.get(this.active);
+    if (!inst) throw new Error(`Active ${this.opts.noun.toLowerCase()} has no instance: ${this.active}`);
+    return inst;
+  }
+
+  /** Active backend, or null when none is configured. Lets call sites degrade
+   *  gracefully (keyword recall, the OS voice, "no transcriber configured"). */
+  tryGetActive(): TInstance | null {
+    if (!this.active) return null;
+    if (this.opts.buildOnRead) {
+      try {
+        return this.instantiate(this.active);
+      } catch {
+        return null;
+      }
+    }
+    return this.instances.get(this.active) ?? null;
+  }
+
+  getActiveName(): string | null {
+    return this.active;
+  }
+
+  /** Cached instance for `name`, building it from its def on first use. */
+  private instantiate(name: string): TInstance {
+    let inst = this.instances.get(name);
+    if (!inst) {
+      inst = this.buildInstance(name);
+      this.instances.set(name, inst);
+    }
+    return inst;
+  }
+
+  private buildInstance(name: string, config?: Record<string, unknown>): TInstance {
+    const def = this.defs.get(name);
+    if (!def) throw new Error(`${this.opts.noun} not registered: ${name}`);
+    return this.opts.build(def, config ?? {});
+  }
+}

package/src/registries/active-def-registry.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { ActiveDefRegistry } from './active-def-registry.js';
+
+/**
+ * Contract test for the shared base behind compactors, cache-strategies,
+ * view-renderers, tunnel-providers and workflow-executors. The five concrete
+ * subclasses keep thin sanity tests; the invariants live here once.
+ */
+
+interface Thing {
+  name: string;
+  v?: number;
+}
+const mk = (name: string, v?: number): Thing => ({ name, v });
+
+describe('ActiveDefRegistry (shared base)', () => {
+  it('getActive() is null when empty', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing' });
+    expect(r.getActive()).toBeNull();
+    expect(r.getActiveName()).toBeNull();
+    expect(r.list()).toEqual([]);
+  });
+
+  it('auto-activates the first registered def and keeps it on later registers', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing' });
+    r.register(mk('a'));
+    expect(r.getActive()?.name).toBe('a');
+    expect(r.getActiveName()).toBe('a');
+    r.register(mk('b'));
+    expect(r.getActive()?.name).toBe('a'); // still the first
+  });
+
+  it('throws the exact noun-prefixed message on duplicate register', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing' });
+    r.register(mk('a'));
+    expect(() => r.register(mk('a'))).toThrow('Thing already registered: a');
+  });
+
+  it('replace overwrites without throwing and keeps active', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing' });
+    r.register(mk('a', 1));
+    const replacement = mk('a', 2);
+    r.replace(replacement);
+    expect(r.getActive()).toBe(replacement);
+    expect(r.getActive()?.v).toBe(2);
+    expect(r.list()).toHaveLength(1);
+  });
+
+  it('replace on empty registry auto-activates', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing' });
+    r.replace(mk('a'));
+    expect(r.getActive()?.name).toBe('a');
+  });
+
+  it('setActive switches; throws the exact noun-prefixed message for unknown', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing' });
+    r.register(mk('a'));
+    r.register(mk('b'));
+    r.setActive('b');
+    expect(r.getActive()?.name).toBe('b');
+    expect(() => r.setActive('nope')).toThrow('Thing not registered: nope');
+  });
+
+  it('unregister clears the active slot rather than picking a successor', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing' });
+    r.register(mk('a'));
+    r.register(mk('b'));
+    r.unregister('a');
+    expect(r.getActive()).toBeNull();
+    expect(r.getActiveName()).toBeNull();
+    expect(r.list().map((x) => x.name)).toEqual(['b']);
+  });
+
+  it('unregistering a non-active def leaves active intact', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing' });
+    r.register(mk('a'));
+    r.register(mk('b'));
+    r.unregister('b');
+    expect(r.getActive()?.name).toBe('a');
+  });
+
+  it('has() reflects membership; clearActive() deactivates without removing', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing' });
+    r.register(mk('a'));
+    expect(r.has('a')).toBe(true);
+    expect(r.has('z')).toBe(false);
+    r.clearActive();
+    expect(r.getActive()).toBeNull();
+    expect(r.getActiveName()).toBeNull();
+    expect(r.has('a')).toBe(true); // still registered, just not active
+    r.setActive('a');
+    expect(r.getActive()?.name).toBe('a');
+  });
+
+  it('autoAdoptFirst:false leaves nothing active until setActive', () => {
+    const r = new ActiveDefRegistry<Thing>({ noun: 'Thing', autoAdoptFirst: false });
+    r.register(mk('a'));
+    r.replace(mk('b'));
+    expect(r.getActive()).toBeNull();
+    r.setActive('a');
+    expect(r.getActive()?.name).toBe('a');
+  });
+});

package/src/registries/active-def-registry.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared base for the "single active def, no built instance" registries
+ * (compactors, cache strategies, view renderers, tunnel providers, workflow
+ * executors). Each is a `Map<name, def>` with at most one *active* def at a
+ * time:
+ *   - plugins call `register(def)` at load time (throws on duplicate)
+ *   - the first registration auto-activates (when `autoAdoptFirst`, the
+ *     default), so a session always has a default once a plugin loads one
+ *   - the host / agent calls `setActive(name)` to switch
+ *   - call sites read `getActive()` (returns null when nothing is active)
+ *   - `unregister` clears the active slot rather than silently picking an
+ *     arbitrary successor — callers must `setActive()` again
+ *
+ * This is the def-only sibling of {@link ActiveBackendRegistry} (which also
+ * builds runtime *instances* for STT/TTS/embeddings). The two families share
+ * the same surface (register/replace/unregister/list/has/setActive/getActive/
+ * getActiveName/clearActive) so they stay consistent.
+ *
+ * `ModeRegistry` (change-listeners + legacy-name migration) and
+ * `ProviderRegistry` (disabled-set + built instances) deliberately stay
+ * bespoke rather than extend this base.
+ */
+export interface ActiveDefRegistryOptions {
+  /** Capitalised singular noun for error messages, e.g. `'Compactor'`. */
+  readonly noun: string;
+  /** Adopt the first registered def as active when nothing is active yet.
+   *  Defaults to `true`. */
+  readonly autoAdoptFirst?: boolean;
+}
+
+export class ActiveDefRegistry<TDef extends { name: string }> {
+  private readonly defs = new Map<string, TDef>();
+  private active: string | null = null;
+  private readonly noun: string;
+  private readonly autoAdoptFirst: boolean;
+
+  constructor(opts: ActiveDefRegistryOptions) {
+    this.noun = opts.noun;
+    this.autoAdoptFirst = opts.autoAdoptFirst ?? true;
+  }
+
+  /**
+   * Register a def. Throws on duplicate — use `replace()` to overwrite.
+   * Auto-activates the first registration (when `autoAdoptFirst`).
+   */
+  register(def: TDef): void {
+    if (this.defs.has(def.name)) {
+      throw new Error(`${this.noun} already registered: ${def.name}`);
+    }
+    this.defs.set(def.name, def);
+    if (this.autoAdoptFirst && !this.active) this.active = def.name;
+  }
+
+  /** Overwrite an existing def (or add a new one) without throwing.
+   *  Auto-activates when nothing is active yet (mirrors `register`). */
+  replace(def: TDef): void {
+    this.defs.set(def.name, def);
+    if (this.autoAdoptFirst && !this.active) this.active = def.name;
+  }
+
+  /**
+   * Remove a def. If it was active, the active slot is cleared (callers must
+   * `setActive()` rather than getting an arbitrary "next").
+   */
+  unregister(name: string): void {
+    this.defs.delete(name);
+    if (this.active === name) this.active = null;
+  }
+
+  list(): ReadonlyArray<TDef> {
+    return [...this.defs.values()];
+  }
+
+  has(name: string): boolean {
+    return this.defs.has(name);
+  }
+
+  setActive(name: string): void {
+    const def = this.defs.get(name);
+    if (!def) throw new Error(`${this.noun} not registered: ${name}`);
+    this.active = def.name;
+  }
+
+  /** Deactivate the current def (callers fall back to their default). */
+  clearActive(): void {
+    this.active = null;
+  }
+
+  getActive(): TDef | null {
+    if (!this.active) return null;
+    return this.defs.get(this.active) ?? null;
+  }
+
+  getActiveName(): string | null {
+    return this.active;
+  }
+}

package/src/registries/agents.ts

@@ -0,0 +1,18 @@
+import type { AgentDef } from '@moxxy/sdk';
+import { DefMapRegistry } from './def-map-registry.js';
+
+/**
+ * Registry of named subagent kinds contributed by plugins. The
+ * `dispatch_agent` tool looks definitions up here by `agentType` and
+ * uses them as templates (systemPrompt, allowedTools, mode, …)
+ * for the spawned child.
+ *
+ * A flat name→def map ({@link DefMapRegistry}): register throws on
+ * duplicate so two plugins can't silently shadow each other — use
+ * `replace()` when you really want to override (e.g. user-config overrides).
+ */
+export class AgentRegistry extends DefMapRegistry<AgentDef> {
+  constructor() {
+    super({ noun: 'Agent', keyOf: (def) => def.name });
+  }
+}

package/src/registries/cache-strategies.ts

@@ -0,0 +1,14 @@
+import type { CacheStrategyDef } from '@moxxy/sdk';
+import { ActiveDefRegistry } from './active-def-registry.js';
+
+/**
+ * One active prompt-caching strategy per session. Register throws on
+ * duplicate, auto-activates the first, and `unregister` clears the active
+ * slot rather than picking an arbitrary successor. See
+ * {@link ActiveDefRegistry}.
+ */
+export class CacheStrategyRegistry extends ActiveDefRegistry<CacheStrategyDef> {
+  constructor() {
+    super({ noun: 'Cache strategy' });
+  }
+}

package/src/registries/channels.ts

@@ -0,0 +1,42 @@
+import type {
+  ChannelAvailability,
+  ChannelDef,
+  ChannelFactoryDeps,
+  ChannelRegistry,
+} from '@moxxy/sdk';
+import { DefMapRegistry } from './def-map-registry.js';
+
+/**
+ * Flat name→def registry of channels ({@link DefMapRegistry}) plus
+ * `listWithAvailability`, which pairs each channel with its current
+ * availability (treating channels without an `isAvailable` hook as
+ * `{ ok: true }` and mapping a thrown probe to `{ ok: false }`).
+ */
+export class ChannelRegistryImpl extends DefMapRegistry<ChannelDef> implements ChannelRegistry {
+  constructor() {
+    super({ noun: 'Channel', keyOf: (def) => def.name });
+  }
+
+  async listWithAvailability(
+    deps: ChannelFactoryDeps,
+  ): Promise<ReadonlyArray<{ def: ChannelDef; availability: ChannelAvailability }>> {
+    const out: Array<{ def: ChannelDef; availability: ChannelAvailability }> = [];
+    for (const def of this.defs.values()) {
+      let availability: ChannelAvailability;
+      if (def.isAvailable) {
+        try {
+          availability = await def.isAvailable(deps);
+        } catch (err) {
+          availability = {
+            ok: false,
+            reason: err instanceof Error ? err.message : String(err),
+          };
+        }
+      } else {
+        availability = { ok: true };
+      }
+      out.push({ def, availability });
+    }
+    return out;
+  }
+}

package/src/registries/commands.test.ts

@@ -0,0 +1,71 @@
+import type { CommandDef } from '@moxxy/sdk';
+import { describe, expect, it } from 'vitest';
+import { CommandRegistry } from './commands.js';
+
+function fakeCommand(name: string, extra: Partial<CommandDef> = {}): CommandDef {
+  return {
+    name,
+    description: `cmd ${name}`,
+    handler: () => ({ kind: 'text', text: name }),
+    ...extra,
+  } as CommandDef;
+}
+
+describe('CommandRegistry', () => {
+  it('registers, looks up by name and alias, lists, and unregisters', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('help', { aliases: ['h', '?'] }));
+    expect(reg.has('help')).toBe(true);
+    expect(reg.get('help')?.name).toBe('help');
+    expect(reg.get('h')?.name).toBe('help');
+    expect(reg.get('?')?.name).toBe('help');
+    expect(reg.list().map((c) => c.name)).toEqual(['help']);
+    reg.unregister('help');
+    expect(reg.has('help')).toBe(false);
+    expect(reg.get('h')).toBeUndefined();
+  });
+
+  it('throws on a duplicate primary name', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('new'));
+    expect(() => reg.register(fakeCommand('new'))).toThrow(/already registered/);
+  });
+
+  it('throws on an alias already claimed by another command (as alias or name)', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('compact', { aliases: ['c'] }));
+    expect(() => reg.register(fakeCommand('clear', { aliases: ['c'] }))).toThrow(
+      /alias already in use/,
+    );
+    expect(() => reg.register(fakeCommand('compact'))).toThrow(/already registered/);
+  });
+
+  it('throws when a new primary name collides with an existing alias', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('compact', { aliases: ['c'] }));
+    // 'c' is already an alias of /compact; registering a command literally
+    // named 'c' must NOT silently shadow it via direct-lookup precedence.
+    expect(() => reg.register(fakeCommand('c'))).toThrow(/already in use as an alias/);
+  });
+
+  it('replace() upserts and cleans up the prior definition aliases', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('mode', { aliases: ['m'] }));
+    reg.replace(fakeCommand('mode', { aliases: ['md'], description: 'updated' }));
+    expect(reg.get('mode')?.description).toBe('updated');
+    expect(reg.get('md')?.name).toBe('mode');
+    // Old alias is cleaned up.
+    expect(reg.get('m')).toBeUndefined();
+  });
+
+  it('listForChannel filters channel-scoped commands', () => {
+    const reg = new CommandRegistry();
+    reg.register(fakeCommand('everywhere'));
+    reg.register(fakeCommand('tuionly', { channels: ['tui'] }));
+    expect(reg.listForChannel('tui').map((c) => c.name).sort()).toEqual([
+      'everywhere',
+      'tuionly',
+    ]);
+    expect(reg.listForChannel('telegram').map((c) => c.name)).toEqual(['everywhere']);
+  });
+});