@moxxy/config 0.27.0

package/src/loader.yaml.test.ts

@@ -0,0 +1,149 @@
+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 { loadConfig } from './loader.js';
+
+let tmp: string;
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-yaml-cfg-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+describe('YAML config loading', () => {
+  it('loads a moxxy.config.yaml from cwd', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      `plugins:
+  provider:
+    default: anthropic
+    items:
+      anthropic:
+        model: claude-sonnet-4-6
+  mode:
+    default: default
+`,
+    );
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config.plugins?.provider?.default).toBe('anthropic');
+    expect(result.config.plugins?.provider?.items?.anthropic?.model).toBe('claude-sonnet-4-6');
+    expect(result.config.plugins?.mode?.default).toBe('default');
+    expect(result.sources[0]?.scope).toBe('project');
+  });
+
+  it('loads .yml extension too', async () => {
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yml'), `plugins:\n  mode:\n    default: research\n`);
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config.plugins?.mode?.default).toBe('research');
+  });
+
+  it('walks upward to find a yaml config', async () => {
+    const nested = path.join(tmp, 'a/b/c');
+    await fs.mkdir(nested, { recursive: true });
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), `plugins:\n  mode:\n    default: default\n`);
+    const result = await loadConfig({ cwd: nested, skipUser: true });
+    expect(result.config.plugins?.mode?.default).toBe('default');
+  });
+
+  it('rejects a yaml config whose schema is invalid', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      `plugins:
+  provider:
+    default: 42
+`,
+    );
+    await expect(loadConfig({ cwd: tmp, skipUser: true })).rejects.toThrow(/Invalid moxxy config/);
+  });
+
+  it('rejects an unknown key inside the closed plugins tree', async () => {
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), `plugins:\n  provdier:\n    default: anthropic\n`);
+    await expect(loadConfig({ cwd: tmp, skipUser: true })).rejects.toThrow(/Invalid moxxy config/);
+  });
+
+  it('accepts an empty yaml file', async () => {
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), '');
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config).toEqual({});
+  });
+
+  it('handles complex nested config (packages, channels, embedder)', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      `plugins:
+  provider:
+    default: anthropic
+    items:
+      anthropic:
+        model: claude-sonnet-4-6
+  embedder:
+    default: openai
+    items:
+      openai:
+        model: text-embedding-3-small
+  packages:
+    '@moxxy/plugin-browser':
+      enabled: false
+channels:
+  http:
+    port: 8080
+    allowedTools:
+      - Read
+      - Glob
+`,
+    );
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config.plugins?.embedder?.default).toBe('openai');
+    expect(result.config.plugins?.packages?.['@moxxy/plugin-browser']?.enabled).toBe(false);
+    expect(result.config.channels?.['http']).toEqual({
+      port: 8080,
+      allowedTools: ['Read', 'Glob'],
+    });
+  });
+
+  it('accepts a partial security block missing `enabled` (optional field)', async () => {
+    // A hand-written or config_set-built `security:` block with only `strict`
+    // must validate; `enabled` defaults to false at the consumer.
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), `security:\n  strict: true\n`);
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config.security?.strict).toBe(true);
+    expect(result.config.security?.enabled).toBeUndefined();
+  });
+
+  it('preserves security.strict instead of silently stripping it', async () => {
+    // Regression: `strict` is consumed by @moxxy/plugin-security
+    // (SecurityPluginConfig.strict). If it were absent from securityConfigSchema,
+    // zod would strip the unknown key on load and a user who set
+    // `security.strict: true` would silently lose the hardening.
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      `security:\n  enabled: true\n  strict: true\n`,
+    );
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config.security?.strict).toBe(true);
+  });
+
+  it('accepts an embedder slot with item options', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      `plugins:\n  embedder:\n    items:\n      openai:\n        model: text-embedding-3-small\n`,
+    );
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config.plugins?.embedder?.items?.openai?.model).toBe('text-embedding-3-small');
+    expect(result.config.plugins?.embedder?.default).toBeUndefined();
+  });
+
+  it('YAML at project level is overridden by .ts at same level (loader precedence)', async () => {
+    // Both exist; first match wins per CONFIG_NAMES order. YAML is listed first
+    // so it should take precedence over .ts. This codifies the order.
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), `plugins:\n  mode:\n    default: default\n`);
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.js'),
+      `export default { plugins: { mode: { default: 'research' } } };`,
+    );
+    const result = await loadConfig({ cwd: tmp, skipUser: true });
+    expect(result.config.plugins?.mode?.default).toBe('default');
+  });
+});

package/src/merge.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+import { mergeConfigs } from './merge.js';
+
+describe('mergeConfigs', () => {
+  it('returns empty for no inputs', () => {
+    expect(mergeConfigs()).toEqual({});
+  });
+
+  it('passes through a single config unchanged', () => {
+    const a = { provider: { name: 'anthropic', model: 'sonnet' } };
+    expect(mergeConfigs(a)).toEqual(a);
+  });
+
+  it('later wins on scalar fields', () => {
+    const a = { provider: { name: 'anthropic', model: 'haiku' } };
+    const b = { provider: { name: 'anthropic', model: 'sonnet' } };
+    expect(mergeConfigs(a, b).provider?.model).toBe('sonnet');
+  });
+
+  it('merges nested objects key-by-key', () => {
+    const a = { plugins: { 'a': { enabled: true } } };
+    const b = { plugins: { 'b': { enabled: false } } };
+    expect(mergeConfigs(a, b).plugins).toEqual({
+      a: { enabled: true },
+      b: { enabled: false },
+    });
+  });
+
+  it('skips undefined entries', () => {
+    expect(mergeConfigs(undefined, { provider: { name: 'x' } }, undefined)).toEqual({
+      provider: { name: 'x' },
+    });
+  });
+
+  it('concatenates arrays rather than replacing', () => {
+    const a = { permissions: { allow: [{ name: 'Read' }] } };
+    const b = { permissions: { allow: [{ name: 'Edit' }] } };
+    expect(mergeConfigs(a, b).permissions?.allow).toEqual([{ name: 'Read' }, { name: 'Edit' }]);
+  });
+
+  it('merges plugin-specific options deeply', () => {
+    const a = { plugins: { p: { options: { a: 1, deep: { x: 1 } } } } };
+    const b = { plugins: { p: { options: { b: 2, deep: { y: 2 } } } } };
+    expect(mergeConfigs(a, b).plugins?.p?.options).toEqual({
+      a: 1,
+      b: 2,
+      deep: { x: 1, y: 2 },
+    });
+  });
+
+  it('ignores a literal __proto__ key without corrupting the merged object', () => {
+    // A parsed config (JSON default-export / some YAML) can carry an own
+    // enumerable `__proto__`; assigning it would hit the prototype setter,
+    // silently drop the data AND replace the result's prototype.
+    const malicious = JSON.parse('{"mode":"goal","__proto__":{"polluted":true}}') as Record<
+      string,
+      unknown
+    >;
+    const out = mergeConfigs(malicious as never) as Record<string, unknown>;
+    expect(out.mode).toBe('goal');
+    // No prototype pollution leaked onto Object.prototype.
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+    // The merged object keeps a plain-object prototype (not corrupted).
+    expect(Object.getPrototypeOf(out)).toBe(Object.prototype);
+    expect('polluted' in out).toBe(false);
+  });
+
+  it('ignores literal constructor / prototype keys', () => {
+    const src = JSON.parse('{"mode":"x","constructor":{"bad":1},"prototype":{"bad":2}}') as Record<
+      string,
+      unknown
+    >;
+    const out = mergeConfigs(src as never) as Record<string, unknown>;
+    expect(out.mode).toBe('x');
+    expect(typeof out.constructor).toBe('function');
+    expect('prototype' in out).toBe(false);
+  });
+});

package/src/merge.ts

@@ -0,0 +1,44 @@
+import type { MoxxyConfig } from './schema.js';
+
+/**
+ * Deep-merge any number of configs in order. Later wins on scalars; arrays are concatenated;
+ * objects are merged key-by-key.
+ *
+ * Precedence (highest → lowest): CLI flags → project config → user config → defaults.
+ */
+export function mergeConfigs(...configs: ReadonlyArray<MoxxyConfig | undefined>): MoxxyConfig {
+  const out: MoxxyConfig = {};
+  for (const cfg of configs) {
+    if (!cfg) continue;
+    mergeInto(out, cfg);
+  }
+  return out;
+}
+
+// Keys that, when assigned via `target[key] = ...`, hit a prototype setter
+// instead of creating an own data property — silently dropping the data AND
+// replacing the merged object's prototype. A parsed config (JSON default-export
+// or some YAML inputs) can carry an own enumerable `__proto__`/`constructor`/
+// `prototype` key, so skip them defensively. Legitimate configs never use them.
+const FORBIDDEN_MERGE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+function mergeInto(target: Record<string, unknown>, source: Record<string, unknown>): void {
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+    if (FORBIDDEN_MERGE_KEYS.has(key)) continue;
+    const existing = target[key];
+    if (Array.isArray(value)) {
+      target[key] = Array.isArray(existing) ? [...existing, ...value] : [...value];
+    } else if (isPlainObject(value)) {
+      const base = isPlainObject(existing) ? { ...existing } : {};
+      mergeInto(base, value as Record<string, unknown>);
+      target[key] = base;
+    } else {
+      target[key] = value;
+    }
+  }
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/src/plugin-settings-schema.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+/** Per-package settings in the `plugins.packages` install/enable ledger. */
+export const pluginSettingsSchema = z
+  .object({
+    /** Plug/unplug the whole package (all its contributions). Default true. */
+    enabled: z.boolean().optional(),
+    /** Package-specific options passed to the plugin. */
+    options: z.record(z.string(), z.unknown()).optional(),
+    /**
+     * Optional per-contribution exclusions, e.g. `["tool:foo"]`, to suppress a
+     * single contribution of an otherwise-enabled package. Honored at
+     * registration time. Kept optional so the common case stays one line.
+     */
+    exclude: z.array(z.string()).optional(),
+  })
+  .strict();
+export type PluginSettings = z.infer<typeof pluginSettingsSchema>;

package/src/plugin.test.ts

@@ -0,0 +1,310 @@
+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 { asSessionId, asToolCallId, asTurnId, type ToolContext } from '@moxxy/sdk';
+import { buildConfigPlugin, type ConfigApplier, type ConfigApplyResult } from './plugin.js';
+
+let tmp: string;
+
+const ctx: ToolContext = {
+  sessionId: asSessionId('s'),
+  turnId: asTurnId('t'),
+  callId: asToolCallId('c'),
+  cwd: '/tmp',
+  signal: new AbortController().signal,
+  log: { length: 0, at: () => undefined, slice: () => [], ofType: () => [], byTurn: () => [], toJSON: () => [] },
+  logger: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+};
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-cfg-plug-'));
+});
+afterEach(async () => {
+  await fs.rm(tmp, { recursive: true, force: true });
+});
+
+function tool(name: string) {
+  const plugin = buildConfigPlugin({ cwd: tmp });
+  const t = plugin.tools?.find((x) => x.name === name);
+  if (!t) throw new Error(`tool not found: ${name}`);
+  return t;
+}
+
+describe('buildConfigPlugin tools', () => {
+  it('config_path returns null when no project file exists', async () => {
+    const out = (await tool('config_path').handler({ scope: 'project' }, ctx)) as {
+      scope: string;
+      path: string | null;
+    };
+    expect(out.scope).toBe('project');
+    expect(out.path).toBeNull();
+  });
+
+  it('config_path finds an existing moxxy.config.yaml in cwd', async () => {
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), 'mode: default\n');
+    const out = (await tool('config_path').handler({ scope: 'project' }, ctx)) as {
+      path: string;
+    };
+    expect(out.path).toContain('moxxy.config.yaml');
+  });
+
+  it('config_path walks upward to a project config in an ancestor dir', async () => {
+    // Shared upward-walk (loader.findUpward): a config in `tmp` must be found
+    // from a nested subdir, and ONLY the YAML names are matched (the editor
+    // can't safely mutate a .ts config, so it must not resolve one).
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), 'mode: default\n');
+    const nested = path.join(tmp, 'a', 'b', 'c');
+    await fs.mkdir(nested, { recursive: true });
+    const plugin = buildConfigPlugin({ cwd: nested });
+    const t = plugin.tools?.find((x) => x.name === 'config_path');
+    if (!t) throw new Error('config_path not found');
+    const out = (await t.handler({ scope: 'project' }, ctx)) as { path: string | null };
+    expect(out.path).toBe(path.join(tmp, 'moxxy.config.yaml'));
+  });
+
+  it('config_path does NOT resolve a .ts project config (editor only handles YAML)', async () => {
+    // loadConfig honors moxxy.config.ts, but the editor walk deliberately omits
+    // it — config_set can only YAML-edit, so resolving a .ts here would let it
+    // create a competing .yaml. The divergent name list is by design.
+    await fs.writeFile(path.join(tmp, 'moxxy.config.ts'), 'export default {}\n');
+    const out = (await tool('config_path').handler({ scope: 'project' }, ctx)) as {
+      path: string | null;
+    };
+    expect(out.path).toBeNull();
+  });
+
+  it('config_show returns the raw text', async () => {
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), 'mode: default\n');
+    const out = (await tool('config_show').handler({ scope: 'project' }, ctx)) as {
+      text: string;
+    };
+    expect(out.text).toContain('mode: default');
+  });
+
+  it('config_get reads a value at a dot-path', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      `provider:\n  model: sonnet\n  config:\n    apiKey: k\n`,
+    );
+    expect(await tool('config_get').handler({ scope: 'project', path: 'provider.model' }, ctx)).toBe('sonnet');
+    expect(await tool('config_get').handler({ scope: 'project', path: 'provider.config.apiKey' }, ctx)).toBe('k');
+  });
+
+  it('config_get preserves legitimate falsy values (false / 0 / "") and only nulls a missing key', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      `context:\n  caching: false\nmaxIterations: 0\nlabel: ""\n`,
+    );
+    // false / 0 / "" must round-trip as themselves; `cursor ?? null` used to
+    // collapse all three to null so the model couldn't tell "set to false"
+    // from "absent" when inspecting config.
+    expect(await tool('config_get').handler({ scope: 'project', path: 'context.caching' }, ctx)).toBe(false);
+    expect(await tool('config_get').handler({ scope: 'project', path: 'maxIterations' }, ctx)).toBe(0);
+    expect(await tool('config_get').handler({ scope: 'project', path: 'label' }, ctx)).toBe('');
+    // A genuinely absent key still returns null.
+    expect(await tool('config_get').handler({ scope: 'project', path: 'context.missing' }, ctx)).toBeNull();
+  });
+
+  it('config_get does not traverse into the prototype chain or index scalars', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      `provider:\n  model: sonnet\n`,
+    );
+    // Prototype-chain hops must return null, not built-in members.
+    expect(
+      await tool('config_get').handler(
+        { scope: 'project', path: 'constructor.prototype.toString' },
+        ctx,
+      ),
+    ).toBeNull();
+    expect(
+      await tool('config_get').handler({ scope: 'project', path: '__proto__.polluted' }, ctx),
+    ).toBeNull();
+    // Descending into a string value (char-by-index) must not leak characters.
+    expect(
+      await tool('config_get').handler({ scope: 'project', path: 'provider.model.0' }, ctx),
+    ).toBeNull();
+  });
+
+  it('config_set writes a value, preserving the rest of the file', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      `mode: default\nprovider:\n  name: anthropic\n  model: haiku\n`,
+    );
+    await tool('config_set').handler(
+      { scope: 'project', path: 'provider.model', value: '"sonnet"' },
+      ctx,
+    );
+    const text = await fs.readFile(path.join(tmp, 'moxxy.config.yaml'), 'utf8');
+    expect(text).toContain('mode: default');
+    expect(text).toContain('name: anthropic');
+    expect(text).toContain('model: sonnet');
+  });
+
+  it('config_set parses JSON values', async () => {
+    await tool('config_set').handler(
+      { scope: 'project', path: 'channels.http.allowedTools', value: '["Read","Glob"]' },
+      ctx,
+    );
+    const text = await fs.readFile(path.join(tmp, 'moxxy.config.yaml'), 'utf8');
+    expect(text).toMatch(/- Read/);
+    expect(text).toMatch(/- Glob/);
+  });
+
+  it('config_set rejects writes that would violate the schema', async () => {
+    await expect(
+      tool('config_set').handler(
+        { scope: 'project', path: 'plugins.provider.default', value: '42' },
+        ctx,
+      ),
+    ).rejects.toThrow(/invalid config/);
+  });
+
+  it('config_init creates a starter yaml when missing', async () => {
+    const out = (await tool('config_init').handler({ scope: 'project' }, ctx)) as {
+      created: boolean;
+      path: string;
+    };
+    expect(out.created).toBe(true);
+    const text = await fs.readFile(out.path, 'utf8');
+    expect(text).toContain('plugins:');
+    expect(text).toContain('default: anthropic');
+    expect(text).toContain('default: default');
+  });
+
+  it('config_init is a no-op when a file already exists', async () => {
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), 'mode: default\n');
+    const out = (await tool('config_init').handler({ scope: 'project' }, ctx)) as {
+      created: boolean;
+    };
+    expect(out.created).toBe(false);
+  });
+
+  // invariant 5: two concurrent config_set calls on the same plugin instance
+  // each apply only their own edit on top of the same stale doc; without the
+  // per-instance mutex the last atomic rename clobbers the other edit.
+  it('serializes concurrent config_set on one instance (no lost update)', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      'mode: default\nprovider:\n  name: anthropic\n  model: haiku\n',
+    );
+    const plugin = buildConfigPlugin({ cwd: tmp });
+    const setTool = plugin.tools?.find((x) => x.name === 'config_set');
+    if (!setTool) throw new Error('config_set not found');
+    await Promise.all([
+      setTool.handler({ scope: 'project', path: 'provider.model', value: '"sonnet"' }, ctx),
+      setTool.handler({ scope: 'project', path: 'mode', value: '"goal"' }, ctx),
+    ]);
+    const text = await fs.readFile(path.join(tmp, 'moxxy.config.yaml'), 'utf8');
+    const yamlMod = await import('yaml');
+    const parsed = yamlMod.parse(text) as { mode?: string; provider?: { model?: string } };
+    expect(parsed.mode).toBe('goal');
+    expect(parsed.provider?.model).toBe('sonnet');
+  });
+});
+
+describe('buildConfigPlugin runtime applier', () => {
+  // Isolate MOXXY_HOME so loadConfig (config_reload/config_validate) never
+  // merges the developer's real ~/.moxxy/config.yaml — keeps these tests
+  // deterministic regardless of the host machine's user config.
+  let prevHome: string | undefined;
+  beforeEach(async () => {
+    prevHome = process.env.MOXXY_HOME;
+    process.env.MOXXY_HOME = path.join(tmp, 'home');
+    await fs.mkdir(process.env.MOXXY_HOME, { recursive: true });
+  });
+  afterEach(() => {
+    if (prevHome === undefined) delete process.env.MOXXY_HOME;
+    else process.env.MOXXY_HOME = prevHome;
+  });
+
+  function pluginWith(applier?: ConfigApplier) {
+    return buildConfigPlugin({ cwd: tmp, applier });
+  }
+  function toolOf(plugin: ReturnType<typeof buildConfigPlugin>, name: string) {
+    const t = plugin.tools?.find((x) => x.name === name);
+    if (!t) throw new Error(`tool not found: ${name}`);
+    return t;
+  }
+
+  it('config_set surfaces the applier runtime result and passes the validated snapshot', async () => {
+    const seen: unknown[] = [];
+    const applier: ConfigApplier = async (snapshot) => {
+      seen.push(snapshot);
+      return { applied: ['mode'], pending: ['provider.name'] };
+    };
+    const out = (await toolOf(pluginWith(applier), 'config_set').handler(
+      { scope: 'project', path: 'plugins.mode.default', value: '"goal"' },
+      ctx,
+    )) as { runtime: ConfigApplyResult };
+    expect(out.runtime).toEqual({ applied: ['mode'], pending: ['provider.name'] });
+    expect(seen).toHaveLength(1);
+    expect((seen[0] as { plugins?: { mode?: { default?: string } } }).plugins?.mode?.default).toBe(
+      'goal',
+    );
+  });
+
+  it('config_set catches an applier throw and reports it as a reload-failed pending entry', async () => {
+    const applier: ConfigApplier = async () => {
+      throw new Error('boom');
+    };
+    const out = (await toolOf(pluginWith(applier), 'config_set').handler(
+      { scope: 'project', path: 'mode', value: '"goal"' },
+      ctx,
+    )) as { runtime: ConfigApplyResult };
+    expect(out.runtime.applied).toEqual([]);
+    expect(out.runtime.pending).toEqual(['reload-failed: boom']);
+    // The write still landed even though the live-apply failed.
+    const text = await fs.readFile(path.join(tmp, 'moxxy.config.yaml'), 'utf8');
+    expect(text).toContain('mode: goal');
+  });
+
+  it('config_set returns an empty runtime result when no applier is wired', async () => {
+    const out = (await toolOf(pluginWith(), 'config_set').handler(
+      { scope: 'project', path: 'mode', value: '"goal"' },
+      ctx,
+    )) as { runtime: ConfigApplyResult };
+    expect(out.runtime).toEqual({ applied: [], pending: [] });
+  });
+
+  it('config_reload returns the no-applier sentinel when applier omitted', async () => {
+    const out = (await toolOf(pluginWith(), 'config_reload').handler({}, ctx)) as ConfigApplyResult;
+    expect(out.applied).toEqual([]);
+    expect(out.pending).toEqual(['(no runtime applier configured)']);
+  });
+
+  it('config_reload loads fresh config from disk and forwards it to the applier', async () => {
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), 'plugins:\n  mode:\n    default: goal\n');
+    let received: { plugins?: { mode?: { default?: string } } } | undefined;
+    const applier: ConfigApplier = async (snapshot) => {
+      received = snapshot;
+      return { applied: ['mode'], pending: [] };
+    };
+    const out = (await toolOf(pluginWith(applier), 'config_reload').handler({}, ctx)) as ConfigApplyResult;
+    expect(received?.plugins?.mode?.default).toBe('goal');
+    expect(out).toEqual({ applied: ['mode'], pending: [] });
+  });
+
+  it('config_validate reports ok for a valid on-disk config', async () => {
+    await fs.writeFile(path.join(tmp, 'moxxy.config.yaml'), 'mode: default\n');
+    const out = (await toolOf(pluginWith(), 'config_validate').handler({}, ctx)) as {
+      ok: boolean;
+      error?: string;
+    };
+    expect(out.ok).toBe(true);
+  });
+
+  it('config_validate reports {ok:false,error} for an invalid on-disk config', async () => {
+    await fs.writeFile(
+      path.join(tmp, 'moxxy.config.yaml'),
+      'plugins:\n  provider:\n    default: 42\n',
+    );
+    const out = (await toolOf(pluginWith(), 'config_validate').handler({}, ctx)) as {
+      ok: boolean;
+      error?: string;
+    };
+    expect(out.ok).toBe(false);
+    expect(typeof out.error).toBe('string');
+  });
+});