mu-coding 0.5.0 → 0.9.0

package/src/runtime/codingTools/index.ts

@@ -0,0 +1,39 @@
+/**
+ * mu-coding's filesystem + shell tools, packaged as a plugin. Replaces the
+ * legacy `createBuiltinPlugin` that lived in mu-core. Tools declare a
+ * `permission.matchKey` so agent definitions can authorise them via globs.
+ */
+
+import type { Plugin } from 'mu-core';
+import { createBashTool } from './bash';
+import { createEditFileTool } from './edit-file';
+import { createReadFileTool } from './read-file';
+import { createWriteFileTool } from './write-file';
+
+export function createCodingToolsPlugin(): Plugin {
+  let pluginCwd: string | undefined;
+  const getCwd = (): string => pluginCwd ?? process.cwd();
+
+  return {
+    name: 'mu-coding-tools',
+    version: '0.5.0',
+    tools: [
+      createReadFileTool(getCwd),
+      createWriteFileTool(getCwd),
+      createEditFileTool(getCwd),
+      createBashTool(getCwd),
+    ],
+    systemPrompt: [
+      'File & shell tools:',
+      '- Prefer `read` over `cat`/`sed`; pass `start`/`end` for large files.',
+      '- Use `edit` for surgical changes; include enough context in `from` to be unique. One `edit` call per change site.',
+      '- Use `write` only for new files or full rewrites.',
+      '- Use `bash` for ops without a dedicated tool (ls, rg, build, tests). Avoid using it to read or rewrite files.',
+    ].join('\n'),
+    activate(ctx) {
+      pluginCwd = ctx.cwd;
+    },
+  };
+}
+
+export { createBashTool, createEditFileTool, createReadFileTool, createWriteFileTool };

package/src/runtime/codingTools/read-file.ts

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from 'node:fs';
+import type { PluginTool } from 'mu-core';
+import { sanitizePath } from './utils';
+
+function executeReadFileSingle(rawPath: string, cwd: string, start?: number, end?: number): string {
+  const path = sanitizePath(rawPath, cwd);
+  if (!existsSync(path)) {
+    return `Error: File not found: ${path}`;
+  }
+  try {
+    const content = readFileSync(path, 'utf-8');
+    const allLines = content.split('\n');
+    const totalLines = allLines.length;
+
+    const startLine = Math.max(1, start ?? 1);
+    const endLine = end ?? totalLines;
+    const clampedStart = Math.min(startLine, totalLines);
+    const clampedEnd = Math.min(endLine, totalLines);
+
+    if (clampedStart > clampedEnd) {
+      return `Error: start (${startLine}) > end (${endLine})`;
+    }
+
+    const lines = allLines.slice(clampedStart - 1, clampedEnd);
+    const numbered = lines.map((line, i) => `${String(clampedStart + i).padStart(4)} │ ${line}`).join('\n');
+    const rangeLabel = start ? ` (lines ${clampedStart}-${clampedEnd})` : '';
+    const header = `── ${path}${rangeLabel} (${lines.length} lines) ──`;
+    return `${header}\n${numbered}`;
+  } catch (err) {
+    return `Error: ${err instanceof Error ? err.message : 'Unknown error'}`;
+  }
+}
+
+export function createReadFileTool(getCwd: () => string): PluginTool {
+  return {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'read',
+        description: 'Read text file(s) with line numbers. `path` may be a single path or array.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: ['string', 'array'], items: { type: 'string' } },
+            start: { type: 'integer', description: '1-indexed first line, inclusive.' },
+            end: { type: 'integer', description: '1-indexed last line, inclusive.' },
+          },
+          required: ['path'],
+          additionalProperties: false,
+        },
+      },
+    },
+    display: {
+      verb: 'reading',
+      kind: 'file-read',
+      fields: { path: 'path', start: 'start', end: 'end' },
+    },
+    permission: {
+      matchKey: (args) => {
+        const p = args.path;
+        if (typeof p === 'string') return p;
+        if (Array.isArray(p)) return p[0] as string | undefined;
+        return undefined;
+      },
+    },
+    execute(args) {
+      const paths = Array.isArray(args.path) ? (args.path as string[]) : [args.path as string];
+      const start = args.start as number | undefined;
+      const end = args.end as number | undefined;
+      const cwd = getCwd();
+
+      if (paths.length === 1) {
+        return executeReadFileSingle(paths[0], cwd, start, end);
+      }
+
+      const results: string[] = [];
+      for (const path of paths) {
+        results.push(executeReadFileSingle(path, cwd, start, end));
+      }
+      return results.join('\n\n');
+    },
+  };
+}

package/src/runtime/codingTools/utils.ts

@@ -0,0 +1,21 @@
+import { isAbsolute, resolve } from 'node:path';
+
+/**
+ * Sanitize a file path from LLM arguments.
+ * Local models often wrap paths in extra quotes or add whitespace.
+ *
+ * When `cwd` is supplied, relative paths are resolved against it instead of
+ * `process.cwd()` — this lets the agent operate on a different working
+ * directory than the host process (the host passes its `PluginContext.cwd`
+ * into the builtin plugin factory at activation time).
+ */
+export function sanitizePath(raw: string, cwd?: string): string {
+  let p = raw.trim();
+  if ((p.startsWith('"') && p.endsWith('"')) || (p.startsWith("'") && p.endsWith("'"))) {
+    p = p.slice(1, -1).trim();
+  }
+  if (cwd && !isAbsolute(p)) {
+    return resolve(cwd, p);
+  }
+  return p;
+}

package/src/runtime/codingTools/write-file.ts

@@ -0,0 +1,42 @@
+import { writeFileSync } from 'node:fs';
+import type { PluginTool } from 'mu-core';
+import { sanitizePath } from './utils';
+
+export function createWriteFileTool(getCwd: () => string): PluginTool {
+  return {
+    definition: {
+      type: 'function',
+      function: {
+        name: 'write',
+        description: 'Create or overwrite a file. Use `edit` for partial changes to existing files.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            content: { type: 'string' },
+          },
+          required: ['path', 'content'],
+          additionalProperties: false,
+        },
+      },
+    },
+    display: {
+      verb: 'writing',
+      kind: 'file-write',
+      fields: { path: 'path', content: 'content' },
+    },
+    permission: {
+      matchKey: (args) => args.path as string | undefined,
+    },
+    execute(args) {
+      const path = sanitizePath(args.path as string, getCwd());
+      const content = args.content as string;
+      try {
+        writeFileSync(path, content, 'utf-8');
+        return { content: `File written: ${path}` };
+      } catch (err) {
+        return { content: `Error: ${err instanceof Error ? err.message : 'Unknown error'}`, error: true };
+      }
+    },
+  };
+}

package/src/runtime/createRegistry.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it, mock } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { PluginRegistry } from 'mu-core';
+import type { AppConfig } from '../config/index';
+import { InkUIService } from '../tui/plugins/InkUIService';
+import { createRegistry } from './createRegistry';
+
+// ─── renderApp mock ───────────────────────────────────────────────────────────
+// Captures the options renderApp is called with so tests can assert what the
+// TUI actually receives — specifically, that the concrete PluginRegistry (with
+// subscription methods) is passed rather than the narrow PluginRegistryView.
+// This mock must be declared before any test imports createRegistry so Bun's
+// module mock intercepts the import in the plugin chain.
+
+const capturedRenderArgs: Array<{ registry: PluginRegistry }> = [];
+const noop = (): void => {
+  /* stub */
+};
+mock.module('../tui/renderApp', () => ({
+  renderApp: (opts: { registry: PluginRegistry }) => {
+    capturedRenderArgs.push(opts);
+    return {
+      unmount: noop,
+      waitUntilExit: async (): Promise<void> => {
+        /* stub */
+      },
+      rerender: noop,
+      cleanup: noop,
+      clear: noop,
+    };
+  },
+}));
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function fakeConfig(): AppConfig {
+  return {
+    baseUrl: 'http://localhost:0',
+    model: 'test-model',
+    maxTokens: 1024,
+    temperature: 0.7,
+    streamTimeoutMs: 10_000,
+  };
+}
+
+/** Methods the TUI subscribes to at runtime (not part of PluginRegistryView). */
+const TUI_REGISTRY_METHODS = [
+  'onStatusChange',
+  'getStatusSegments',
+  'onRenderersChange',
+  'getRenderers',
+  'onShortcutsChange',
+  'getShortcuts',
+  'getCommands',
+] as const;
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('createRegistry — activation order + plugin propagation', () => {
+  it('registers builtins so coding-agents see ctx.agents', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'mu-cr-'));
+    try {
+      const ui = new InkUIService();
+      const { registry, channels, providers } = await createRegistry({
+        cwd,
+        config: fakeConfig(),
+        uiService: ui,
+      });
+
+      // Provider registered.
+      expect(providers.list().some((p) => p.id === 'openai')).toBe(true);
+
+      // All builtin plugins loaded in the correct order.
+      const names = registry.getPlugins().map((p) => p.name);
+      expect(names).toContain('mu-openai-provider');
+      expect(names).toContain('mu-agents');
+      expect(names).toContain('mu-coding');
+      // mu-coding-agents is opt-in via `config.plugins`, not auto-registered.
+      expect(names).not.toContain('mu-coding-agents');
+
+      // TUI channel registered.
+      expect(channels.list().map((c) => c.id)).toContain('tui');
+
+      // mu-agents exposes its approval gateway publicly.
+      interface GatewayBearer {
+        approvalGateway?: { registerChannel: unknown };
+      }
+      const agent = registry.getPlugin<GatewayBearer & { name: string; [k: string]: unknown }>('mu-agents');
+      expect(agent?.approvalGateway).toBeDefined();
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it('TUI channel receives concrete PluginRegistry (not the narrow View)', async () => {
+    // This test is the REAL regression guard: it calls channels.startAll()
+    // which invokes tuiChannel.start() → renderApp(opts). The mock above
+    // captures `opts.registry`. If createCodingPlugin ever reverts to passing
+    // `ctx.registry` (the narrow View), the TUI methods below will be absent
+    // and the test fails — exactly mirroring the runtime crash that would occur.
+    const cwd = mkdtempSync(join(tmpdir(), 'mu-cr-'));
+    try {
+      const ui = new InkUIService();
+      capturedRenderArgs.length = 0;
+      const { channels } = await createRegistry({
+        cwd,
+        config: fakeConfig(),
+        uiService: ui,
+      });
+
+      await channels.startAll();
+      await channels.stopAll();
+
+      expect(capturedRenderArgs).toHaveLength(1);
+      const reg = capturedRenderArgs[0].registry as unknown as Record<string, unknown>;
+      for (const method of TUI_REGISTRY_METHODS) {
+        expect(typeof reg[method], `registry.${method} should be a function`).toBe('function');
+      }
+    } finally {
+      capturedRenderArgs.length = 0;
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+
+  it('mu-agents contributes per-primary-agent slash commands but no generic /agent', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'mu-cr-'));
+    try {
+      const ui = new InkUIService();
+      const { registry } = await createRegistry({
+        cwd,
+        config: fakeConfig(),
+        uiService: ui,
+      });
+
+      const commandNames = registry.getCommands().map((c) => c.name);
+      // The generic `/agent` command was removed; discoverability is via
+      // the per-agent switch commands and the Tab shortcut.
+      expect(commandNames).not.toContain('agent');
+      // `explore` originates from mu-coding-agents, which is no longer auto-loaded.
+      expect(commandNames).not.toContain('explore');
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+    }
+  });
+});

package/src/runtime/createRegistry.ts

@@ -1,58 +1,195 @@
-import { createBuiltinPlugin, PluginRegistry } from 'mu-agents';
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createAgentsPlugin } from 'mu-agents';
+import type { ChatMessage } from 'mu-core';
+import {
+  type ActivityBus,
+  type ChannelRegistry,
+  createActivityBus,
+  createChannelRegistry,
+  createProviderRegistry,
+  PluginRegistry,
+  type ProviderRegistry,
+} from 'mu-core';
+import { createOpenAIProviderPlugin } from 'mu-openai-provider';
 import type { ShutdownFn } from '../app/shutdown';
 import type { AppConfig } from '../config/index';
+import { createCodingPlugin } from '../plugin';
+import { saveSession } from '../sessions/index';
 import type { InkUIService } from '../tui/plugins/InkUIService';
+import { createMessageBus, type HostMessageBus } from './messageBus';
 import { discoverPluginFiles, loadConfiguredPlugin } from './pluginLoader';
 
+/**
+ * Tiny mutable holder used to bridge the React-owned current session path
+ * (`useSessionPersistence`) with plugins that need it at construction time
+ * (here, mu-agents — to derive a sibling directory for subagent runs).
+ *
+ * The holder is created up-front and passed both to `mu-agents` (read via
+ * `getParentSessionPath`) and to the TUI channel (which forwards it into
+ * the React tree where `useSessionPersistence` keeps it in sync).
+ */
+export interface SessionPathHolder {
+  current: string | undefined;
+}
+
+function createSessionPathHolder(): SessionPathHolder {
+  return { current: undefined };
+}
+
 interface CreateRegistryOptions {
   cwd: string;
   config: AppConfig;
   uiService: InkUIService;
   /**
-   * Host shutdown is forwarded to plugins via PluginContext so a plugin (or
-   * Pi extension via mu-pi-compat) calling shutdown gets the same graceful
-   * path as Ctrl+C — terminal restored, plugins deactivated.
+   * Initial transcript injected into the TUI's session (e.g. resumed from
+   * disk via `mu -c`). Threaded through to the coding plugin's TUI channel.
+   */
+  initialMessages?: ChatMessage[];
+  /**
+   * Host shutdown is forwarded to plugins via PluginContext so a plugin
+   * calling shutdown gets the same graceful path as Ctrl+C — terminal
+   * restored, plugins deactivated.
    *
    * Optional because some callers (tests, single-shot) don't have one.
    */
   shutdown?: ShutdownFn;
 }
 
+interface RegistryBundle {
+  registry: PluginRegistry;
+  messageBus: HostMessageBus;
+  providers: ProviderRegistry;
+  channels: ChannelRegistry;
+  activity: ActivityBus;
+  sessionPathHolder: SessionPathHolder;
+}
+
+interface PluginConfigInputs {
+  uiService: InkUIService;
+  shutdown: ShutdownFn | undefined;
+  appConfig: AppConfig;
+}
+
 /**
  * Build the plugin config object passed into a plugin's factory.
- * Every plugin (configured or locally discovered) gets the UI service and
- * (when available) the host shutdown so tools can prompt, toast, set status
- * segments, or trigger graceful exit without extra plumbing.
+ * Every plugin (configured or locally discovered) receives:
+ *  - `ui` — UIService for dialogs/toasts/status
+ *  - `shutdown` — graceful shutdown hook (when available)
+ *  - `config` — the host's ProviderConfig snapshot (baseUrl, model, …) so
+ *    plugins that need to call the LLM (e.g. subagents) don't have to be
+ *    re-configured manually
+ *  - `model` — the host's currently configured model id
  */
-function buildPluginConfig(
-  uiService: InkUIService,
-  shutdown: ShutdownFn | undefined,
-  base?: Record<string, unknown>,
-): Record<string, unknown> {
+function buildPluginConfig(inputs: PluginConfigInputs, base?: Record<string, unknown>): Record<string, unknown> {
   const merged: Record<string, unknown> = base ? { ...base } : {};
-  merged.ui = uiService;
-  if (shutdown) merged.shutdown = shutdown;
+  merged.ui = inputs.uiService;
+  if (inputs.shutdown) merged.shutdown = inputs.shutdown;
+  // Forward provider info so plugins can re-issue LLM calls (e.g. subagents)
+  // without forcing users to duplicate `baseUrl`/`model` in plugin config.
+  if (!('config' in merged)) merged.config = inputs.appConfig;
+  if (!('model' in merged) && inputs.appConfig.model) merged.model = inputs.appConfig.model;
   return merged;
 }
 
-export async function createRegistry(options: CreateRegistryOptions): Promise<PluginRegistry> {
+/**
+ * Fallback shutdown used when the host (typically tests) doesn't supply one.
+ * Logs a warning when a plugin actually invokes it: production hosts always
+ * pass the real `registerShutdown(...)` handle, so an invocation here means
+ * either the test setup forgot to mock the plugin's shutdown call or a
+ * plugin is reaching for `ctx.shutdown()` in an environment that can't honour
+ * it. Resolves cleanly so the calling plugin sees no behavioural change.
+ */
+async function noopShutdown(code?: number): Promise<void> {
+  console.warn(`[mu-coding] noopShutdown invoked (code=${code ?? 0}); host did not register a real shutdown handler.`);
+}
+
+/**
+ * Wire mu-coding's standard plugin set:
+ *  1. mu-openai-provider — registers the OpenAI streaming provider
+ *  2. mu-agents          — agent switcher + permissions + approval gateway
+ *  3. mu-coding          — coding tools + TUI channel + Ink approval channel
+ *                          (registered against mu-agents' gateway)
+ *
+ * Order matters: mu-coding must activate *after* mu-agents so the approval
+ * channel finds the gateway via `ctx.getPlugin('mu-agents')`.
+ *
+ * Optional plugins (mu-coding-agents, mu-repomap, …) are opt-in via
+ * `config.plugins` and loaded below by `loadConfiguredPlugin`.
+ */
+async function registerBuiltins(
+  registry: PluginRegistry,
+  options: CreateRegistryOptions,
+  inputs: PluginConfigInputs,
+  messageBus: HostMessageBus,
+  sessionPathHolder: SessionPathHolder,
+): Promise<void> {
+  await registry.register(createOpenAIProviderPlugin());
+  await registry.register(
+    createAgentsPlugin({
+      config: options.config,
+      model: options.config.model,
+      approvalChannelId: 'tui',
+      // The chat session updates this holder once `useSessionPersistence`
+      // mounts; mu-agents reads it lazily so subagent runs always land
+      // beside the *current* parent transcript file (survives /new + load).
+      getParentSessionPath: () => sessionPathHolder.current,
+      sessionWriter: async (path, messages) => {
+        await mkdir(dirname(path), { recursive: true });
+        await saveSession(path, messages);
+      },
+    }),
+  );
+  await registry.register(
+    createCodingPlugin({
+      appConfig: options.config,
+      initialMessages: options.initialMessages,
+      messageBus,
+      uiService: options.uiService,
+      shutdown: options.shutdown ?? noopShutdown,
+      sessionPathHolder,
+      // Pass the concrete registry: the TUI subscribes to renderer / shortcut
+      // / status streams that are not part of the narrow `PluginRegistryView`
+      // exposed via `ctx.registry`.
+      registry,
+    }),
+  );
+  // Silence unused-input warning when no configured/local plugins exist.
+  void inputs;
+}
+
+export async function createRegistry(options: CreateRegistryOptions): Promise<RegistryBundle> {
   const { cwd, config, uiService, shutdown } = options;
-  const registry = new PluginRegistry({ cwd, config: {}, ui: uiService, shutdown });
+  const messageBus = createMessageBus();
+  const providers = createProviderRegistry();
+  const channels = createChannelRegistry();
+  const activity = createActivityBus();
+  const sessionPathHolder = createSessionPathHolder();
+  const registry = new PluginRegistry({
+    cwd,
+    config: {},
+    ui: uiService,
+    shutdown,
+    messages: messageBus,
+    providers,
+    channels,
+    activity,
+  });
+
+  const inputs: PluginConfigInputs = { uiService, shutdown, appConfig: config };
 
-  await registry.register(createBuiltinPlugin());
+  await registerBuiltins(registry, options, inputs, messageBus, sessionPathHolder);
 
-  // Locally dropped plugins (~/.config/mu/plugins/*.ts) go through the same
-  // loader as configured ones so they receive `{ ui, shutdown }` and get
-  // consistent error reporting.
+  // User-extension plugins ride on top of the builtins.
   for (const filePath of discoverPluginFiles()) {
-    await loadConfiguredPlugin(registry, filePath, buildPluginConfig(uiService, shutdown), uiService);
+    await loadConfiguredPlugin(registry, filePath, buildPluginConfig(inputs), uiService);
   }
 
   for (const entry of config.plugins ?? []) {
     const name = typeof entry === 'string' ? entry : entry.name;
     const pluginConfig = typeof entry === 'string' ? undefined : entry.config;
-    await loadConfiguredPlugin(registry, name, buildPluginConfig(uiService, shutdown, pluginConfig), uiService);
+    await loadConfiguredPlugin(registry, name, buildPluginConfig(inputs, pluginConfig), uiService);
   }
 
-  return registry;
+  return { registry, messageBus, providers, channels, activity, sessionPathHolder };
 }

package/src/runtime/fileMentionProvider.ts

@@ -0,0 +1,116 @@
+import { execFileSync } from 'node:child_process';
+import { type Dirent, readdirSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import type { MentionCompletion, MentionProvider } from 'mu-core';
+
+const CACHE_TTL_MS = 5_000;
+const MAX_FILES = 5_000;
+const MAX_RESULTS = 12;
+const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'out', '.next', '.turbo', 'coverage']);
+
+interface FileCache {
+  files: string[];
+  builtAt: number;
+}
+
+let cache: FileCache | null = null;
+let cacheCwd = '';
+
+function listGitFiles(cwd: string): string[] | null {
+  try {
+    const stdout = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], {
+      cwd,
+      encoding: 'utf8',
+      maxBuffer: 8 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const files = stdout.split('\n').filter((line) => line.length > 0);
+    return files.slice(0, MAX_FILES);
+  } catch {
+    return null;
+  }
+}
+
+function walkFs(root: string): string[] {
+  const out: string[] = [];
+  const stack: string[] = [root];
+  while (stack.length > 0 && out.length < MAX_FILES) {
+    const dir = stack.pop();
+    if (!dir) break;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true }) as Dirent[];
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') && entry.name !== '.env.example') continue;
+      if (IGNORE_DIRS.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile()) {
+        out.push(relative(root, full).split(sep).join('/'));
+        if (out.length >= MAX_FILES) break;
+      }
+    }
+  }
+  return out;
+}
+
+function refreshCache(cwd: string): string[] {
+  if (cache && cacheCwd === cwd && Date.now() - cache.builtAt < CACHE_TTL_MS) {
+    return cache.files;
+  }
+  const files = listGitFiles(cwd) ?? walkFs(cwd);
+  cache = { files, builtAt: Date.now() };
+  cacheCwd = cwd;
+  return files;
+}
+
+/**
+ * Score a file path against `partial` for ranking.
+ *  - exact basename match → 0 (best)
+ *  - basename starts with partial → 1
+ *  - basename contains partial → 2
+ *  - path contains partial → 3
+ *  - otherwise → Infinity (filtered out)
+ */
+function scorePath(path: string, partial: string): number {
+  if (!partial) return path.length; // empty partial → shorter paths first
+  const lower = path.toLowerCase();
+  const base = lower.slice(lower.lastIndexOf('/') + 1);
+  const p = partial.toLowerCase();
+  if (base === p) return 0;
+  if (base.startsWith(p)) return 1;
+  if (base.includes(p)) return 2;
+  if (lower.includes(p)) return 3;
+  return Number.POSITIVE_INFINITY;
+}
+
+/**
+ * Build the file mention provider bound to `cwd`. Suggests up to
+ * `MAX_RESULTS` files matched against the partial, ranked by basename
+ * proximity. Cached for {@link CACHE_TTL_MS} so rapid keystrokes don't
+ * re-walk the tree.
+ */
+export function createFileMentionProvider(cwd: string): MentionProvider {
+  return (partial: string): MentionCompletion[] => {
+    const files = refreshCache(cwd);
+    if (files.length === 0) return [];
+    const scored: { path: string; score: number }[] = [];
+    for (const f of files) {
+      const score = scorePath(f, partial);
+      if (score < Number.POSITIVE_INFINITY) scored.push({ path: f, score });
+    }
+    scored.sort((a, b) => a.score - b.score || a.path.length - b.path.length || a.path.localeCompare(b.path));
+    return scored.slice(0, MAX_RESULTS).map(({ path }) => ({
+      value: path,
+      // Show the full path so the basename sits at the end of the line —
+      // the picker truncates the prefix when needed (`wrap="truncate-start"`)
+      // so the filename stays visible.
+      label: path,
+      category: 'files',
+    }));
+  };
+}