mixdog 0.9.2 → 0.9.4

package/src/session-runtime/model-recency.mjs

@@ -0,0 +1,111 @@
+// Provider-model version parsing, recency comparison, sorting, and cache-row
+// construction. Extracted from mixdog-session-runtime.mjs. Pure except for the
+// injected route provider (for sort priority) and searchCapableFor predicate.
+import { clean } from './session-text.mjs';
+
+export function parsedProviderModelVersion(id) {
+  const text = clean(id).toLowerCase();
+  const claude = text.match(/^claude-[a-z]+-(\d+)(?:[-.](\d+))?/);
+  if (claude) return [Number(claude[1]) || 0, Number(claude[2]) || 0];
+  const compact = text.match(/(?:^|[-_])(?:o|gpt|grok|qwen|llama|mistral|gemma|phi|glm)(\d+)(?:\.(\d+))?(?:\.(\d{1,3}))?/);
+  if (compact) return compact.slice(1).filter((v) => v != null).map((v) => Number(v) || 0);
+  const generic = text.match(/(?:^|[-_v])(\d+)(?:\.(\d+))?(?:\.(\d{1,3}))?/);
+  return generic ? generic.slice(1).filter((v) => v != null).map((v) => Number(v) || 0) : [];
+}
+
+export function compareProviderModelVersion(a, b) {
+  const va = parsedProviderModelVersion(a.id || a.display || a.name);
+  const vb = parsedProviderModelVersion(b.id || b.display || b.name);
+  if (va.length === 0 && vb.length === 0) return 0;
+  if (va.length === 0) return 1;
+  if (vb.length === 0) return -1;
+  for (let i = 0; i < Math.max(va.length, vb.length); i += 1) {
+    const delta = (vb[i] || 0) - (va[i] || 0);
+    if (delta) return delta;
+  }
+  return 0;
+}
+
+export function providerModelReleaseTime(model) {
+  if (model?.releaseDate) {
+    const t = Date.parse(model.releaseDate);
+    if (Number.isFinite(t)) return t;
+  }
+  const created = Number(model?.created);
+  if (Number.isFinite(created) && created > 0) {
+    return created < 1_000_000_000_000 ? created * 1000 : created;
+  }
+  const dated = clean(model?.id).match(/(?:^|-)(\d{4})(\d{2})(\d{2})(?:$|-)/);
+  return dated ? (Date.parse(`${dated[1]}-${dated[2]}-${dated[3]}`) || 0) : 0;
+}
+
+export function isClaudeProviderModel(model) {
+  return clean(model?.provider).toLowerCase().includes('anthropic')
+    && /^claude-[a-z]+-/.test(clean(model?.id).toLowerCase());
+}
+
+export function compareProviderModelRecency(a, b) {
+  if (isClaudeProviderModel(a) && isClaudeProviderModel(b)) {
+    if (a.latest !== b.latest) return a.latest ? -1 : 1;
+    const versionDelta = compareProviderModelVersion(a, b);
+    if (versionDelta) return versionDelta;
+    const ta = providerModelReleaseTime(a);
+    const tb = providerModelReleaseTime(b);
+    if (ta !== tb) return tb - ta;
+    return clean(a.display || a.id).localeCompare(clean(b.display || b.id));
+  }
+  const ta = providerModelReleaseTime(a);
+  const tb = providerModelReleaseTime(b);
+  if (ta !== tb) return tb - ta;
+  if (a.latest !== b.latest) return a.latest ? -1 : 1;
+  const versionDelta = compareProviderModelVersion(a, b);
+  if (versionDelta) return versionDelta;
+  return clean(a.display || a.id).localeCompare(clean(b.display || b.id));
+}
+
+export function sortProviderModels(models, primaryProvider = '') {
+  return (models || []).sort((a, b) => {
+    const ar = a.provider === primaryProvider ? 0 : 1;
+    const br = b.provider === primaryProvider ? 0 : 1;
+    if (ar !== br) return ar - br;
+    if (a.provider !== b.provider) return a.provider.localeCompare(b.provider);
+    return compareProviderModelRecency(a, b);
+  });
+}
+
+export function isSelectableLlmModel(model) {
+  const id = clean(model?.id).toLowerCase();
+  const display = clean(model?.display || model?.name).toLowerCase();
+  const mode = clean(model?.mode).toLowerCase();
+  const text = `${id} ${display}`;
+  if (!id) return false;
+  if (mode && !['chat', 'completion', 'responses', 'messages'].includes(mode)) return false;
+  if (/(^|[-_\s])(image|images|video|videos|audio|tts|stt|speech|embed|embedding|embeddings|rerank|reranker|realtime|moderation|imagine)([-_\s]|$)/i.test(text)) return false;
+  if (/(^|[-_\s])(dall[-_\s]?e|sora|imagen)([-_\s]|$)/i.test(text)) return false;
+  return true;
+}
+
+export function providerModelCacheRow(name, m, searchCapableFor) {
+  return {
+    id: m.id,
+    provider: name,
+    display: m.display || m.name || m.id,
+    created: typeof m.created === 'number' ? m.created : null,
+    releaseDate: m.releaseDate || null,
+    contextWindow: m.contextWindow,
+    outputTokens: m.outputTokens || null,
+    family: m.family || null,
+    tier: m.tier || null,
+    latest: m.latest === true,
+    description: m.description || '',
+    supportsVision: m.supportsVision === true,
+    supportsFunctionCalling: m.supportsFunctionCalling === true,
+    supportsWebSearch: searchCapableFor(name, m),
+    supportsPromptCaching: m.supportsPromptCaching === true,
+    supportsReasoning: m.supportsReasoning === true,
+    reasoningLevels: Array.isArray(m.reasoningLevels) ? m.reasoningLevels : undefined,
+    reasoningOptions: Array.isArray(m.reasoningOptions) ? m.reasoningOptions : [],
+    reasoningContentField: m.reasoningContentField || null,
+    mode: m.mode || null,
+  };
+}

package/src/session-runtime/native-search.mjs

@@ -0,0 +1,247 @@
+// Native (provider-hosted) web-search runtime, extracted from
+// mixdog-session-runtime.mjs. Dependency-injected factory pattern: closes over
+// route/searchRoute/config/reg/session accessors supplied by the facade.
+import { clean } from './session-text.mjs';
+
+export function createNativeSearch({
+  getRoute,
+  getSearchRoute,
+  setSearchRoute,
+  getConfig,
+  getSession,
+  getReg,
+  ensureFullConfig,
+  ensureProvidersReady,
+  ensureProviderEnabled,
+  normalizeSearchProviderId,
+  normalizeSearchRouteConfig,
+  isDefaultSearchRouteConfig,
+  isSearchCapableProvider,
+  searchCapableFor,
+}) {
+  function normalizeSearchAllowedDomain(site) {
+    const raw = clean(site);
+    if (!raw) return '';
+    try {
+      return new URL(/^https?:\/\//i.test(raw) ? raw : `https://${raw}`).hostname.toLowerCase();
+    } catch {
+      return raw.replace(/^https?:\/\//i, '').split('/')[0].toLowerCase();
+    }
+  }
+
+  function nativeSearchUserLocation(locale) {
+    if (!locale || typeof locale !== 'object' || Array.isArray(locale)) return null;
+    const location = { type: 'approximate' };
+    for (const key of ['country', 'region', 'city', 'timezone']) {
+      const value = clean(locale[key]);
+      if (value) location[key] = value;
+    }
+    return Object.keys(location).length > 1 ? location : null;
+  }
+
+  function nativeSearchTool(args = {}, toolType = 'web_search', providerId = '') {
+    const providerName = normalizeSearchProviderId(providerId);
+    const domain = normalizeSearchAllowedDomain(args.site);
+    const type = clean(toolType) || 'web_search';
+    const location = nativeSearchUserLocation(args.locale);
+    if (providerName === 'gemini') {
+      return { type: type || 'google_search' };
+    }
+    if (providerName === 'anthropic' || providerName === 'anthropic-oauth') {
+      const tool = {
+        type: 'web_search_20250305',
+        name: 'web_search',
+        max_uses: Math.max(1, Math.min(10, Number(args.maxResults) || 5)),
+      };
+      if (domain) tool.allowed_domains = [domain];
+      if (location) tool.user_location = location;
+      return tool;
+    }
+    if (providerName === 'grok-oauth' || providerName === 'xai') {
+      const tool = { type };
+      if (domain) tool.filters = { allowed_domains: [domain] };
+      return tool;
+    }
+    const tool = {
+      type,
+    };
+    if (type === 'web_search') {
+      tool.search_context_size = clean(args.contextSize) || 'low';
+      if (domain) tool.filters = { allowed_domains: [domain] };
+      if (location) tool.user_location = location;
+    }
+    return tool;
+  }
+
+  function nativeSearchToolTypes(routeLike = {}) {
+    const envToolType = clean(process.env.MIXDOG_NATIVE_SEARCH_TOOL_TYPE);
+    if (envToolType) return [envToolType];
+    const configured = clean(routeLike.toolType);
+    if (configured) return [configured];
+    const providerName = normalizeSearchProviderId(routeLike.provider);
+    if (providerName === 'gemini') return ['google_search'];
+    if (providerName === 'anthropic' || providerName === 'anthropic-oauth') return ['web_search'];
+    if (providerName === 'grok-oauth' || providerName === 'xai') return ['web_search'];
+    return ['web_search', 'web_search_preview'];
+  }
+
+  function currentMainSearchModelMeta() {
+    const route = getRoute();
+    if (!route?.provider || !route?.model) return null;
+    return { ...route, id: route.model, display: route.model, name: route.model };
+  }
+
+  function nativeSearchRoutes() {
+    const route = getRoute();
+    const cfg = ensureFullConfig();
+    const searchRoute = normalizeSearchRouteConfig(cfg.searchRoute) || normalizeSearchRouteConfig(getSearchRoute());
+    setSearchRoute(searchRoute);
+    if (!searchRoute) return [];
+    if (isDefaultSearchRouteConfig(searchRoute)) {
+      const mainModel = currentMainSearchModelMeta();
+      if (!mainModel || !searchCapableFor(route.provider, mainModel)) return [];
+      return [{
+        key: `default\n${route.provider}\n${route.model}`,
+        provider: normalizeSearchProviderId(route.provider),
+        model: route.model,
+        source: 'default-search-route',
+        effort: route.effectiveEffort || route.effort || null,
+        fast: route.fast === true,
+        toolType: searchRoute.toolType || null,
+      }];
+    }
+    const providerName = normalizeSearchProviderId(searchRoute.provider);
+    if (!isSearchCapableProvider(providerName)) return [];
+    return [{
+      key: `${providerName}\n${searchRoute.model}`,
+      provider: providerName,
+      model: searchRoute.model,
+      source: 'search-route',
+      effort: searchRoute.effort || null,
+      fast: searchRoute.fast === true,
+      toolType: searchRoute.toolType || null,
+    }];
+  }
+
+  function nativeSearchMessages(searchArgs = {}) {
+    const prompt = searchArgs.prompt || '';
+    return [
+      {
+        role: 'system',
+        content: [
+          'You are Mixdog native web search.',
+          'Use the hosted web_search tool for current or external facts.',
+          'Answer concisely, cite source URLs, and do not request local tools or file edits.',
+        ].join('\n'),
+      },
+      { role: 'user', content: prompt },
+    ];
+  }
+
+  function flattenNativeSearchSources(result = {}) {
+    const out = [];
+    const add = (source, fallbackTitle = '') => {
+      if (!source || typeof source !== 'object') return;
+      const url = clean(source.url || source.uri || source.href || source.source_url);
+      if (!url) return;
+      out.push({
+        title: clean(source.title || source.query || source.name || fallbackTitle || url),
+        url,
+        snippet: clean(source.snippet || source.text || source.description),
+        source: source.source || 'native-web-search',
+        provider: source.provider || 'native-web-search',
+      });
+    };
+    for (const citation of Array.isArray(result.citations) ? result.citations : []) add(citation);
+    for (const call of Array.isArray(result.webSearchCalls) ? result.webSearchCalls : []) {
+      const action = call?.action || {};
+      for (const source of Array.isArray(action.sources) ? action.sources : []) add(source, action.query || '');
+      if (action.url) add({ url: action.url, title: action.query || '' });
+      for (const url of Array.isArray(action.urls) ? action.urls : []) add({ url, title: action.query || '' });
+    }
+    const seen = new Set();
+    return out.filter((item) => {
+      const key = item.url || `${item.title}\n${item.snippet}`;
+      if (!key || seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+
+  async function runNativeWebSearch(searchArgs = {}, { signal } = {}) {
+    const route = getRoute();
+    const session = getSession();
+    const reg = getReg();
+    const candidates = nativeSearchRoutes();
+    if (!candidates.length) {
+      if (isDefaultSearchRouteConfig(getSearchRoute())) {
+        throw new Error(`default search route requires the current main model to support native web search (${route?.provider || 'unknown'}/${route?.model || 'unknown'})`);
+      }
+      throw new Error('search route is not configured; open /search to choose a search provider/model');
+    }
+    const errors = [];
+    for (const candidate of candidates) {
+      for (const toolType of nativeSearchToolTypes(candidate)) {
+        try {
+          // Read config lazily: nativeSearchRoutes() above may have run
+          // ensureFullConfig() and replaced the facade config with the
+          // secret-bearing one — an early snapshot would miss those secrets.
+          await ensureProvidersReady(ensureProviderEnabled(getConfig(), candidate.provider));
+          const providerImpl = reg.getProvider(candidate.provider);
+          if (!providerImpl || typeof providerImpl.send !== 'function') {
+            throw new Error(`provider "${candidate.provider}" is not ready`);
+          }
+          const model = candidate.model;
+          const searchTool = nativeSearchTool(searchArgs, toolType, candidate.provider);
+          const startedAt = Date.now();
+          const result = await providerImpl.send(
+            nativeSearchMessages(searchArgs),
+            model,
+            undefined,
+            {
+              signal,
+              role: 'web-search',
+              sessionId: `${session?.id || 'search'}:native-search:${Date.now().toString(36)}`,
+              sourceType: 'native-search',
+              sourceName: 'search',
+              nativeTools: [searchTool],
+              nativeInclude: candidate.provider === 'openai' || candidate.provider === 'openai-oauth'
+                ? ['web_search_call.action.sources']
+                : [],
+              toolChoice: candidate.provider === 'gemini' ? 'auto' : 'required',
+              ...(candidate.effort ? { effort: candidate.effort } : {}),
+              fast: candidate.fast === true,
+              onStageChange: () => {},
+              onStreamDelta: () => {},
+            },
+          );
+          const sources = flattenNativeSearchSources(result);
+          return {
+            content: String(result?.content || '').trim(),
+            provider: candidate.provider,
+            model: result?.model || candidate.model || null,
+            usage: result?.usage || null,
+            citations: sources,
+            webSearchCalls: result?.webSearchCalls || [],
+            durationMs: Date.now() - startedAt,
+          };
+        } catch (err) {
+          errors.push(`${candidate.provider}${candidate.model ? `/${candidate.model}` : ''}/${toolType}: ${err?.message || String(err)}`);
+        }
+      }
+    }
+    throw new Error(`native web search failed: ${errors.join(' | ')}`);
+  }
+
+  return {
+    normalizeSearchAllowedDomain,
+    nativeSearchUserLocation,
+    nativeSearchTool,
+    nativeSearchToolTypes,
+    currentMainSearchModelMeta,
+    nativeSearchRoutes,
+    nativeSearchMessages,
+    flattenNativeSearchSources,
+    runNativeWebSearch,
+  };
+}

package/src/session-runtime/output-styles.mjs

@@ -0,0 +1,126 @@
+// Output-style catalog + metadata parsing. Roots are injected so this module
+// stays free of the runtime's path constants.
+import { basename, join } from 'node:path';
+import { readFileSync, readdirSync } from 'node:fs';
+import { clean } from './session-text.mjs';
+import { readJsonSafe } from './fs-utils.mjs';
+
+const OUTPUT_STYLE_ORDER = ['default', 'simple', 'minimal', 'extreme-minimal'];
+const OUTPUT_STYLE_ALIASES = new Map([
+  ['compact', 'default'],
+  ['normal', 'default'],
+  ['extreme', 'extreme-minimal'],
+  ['extremesimple', 'extreme-minimal'],
+  ['extreme-simple', 'extreme-minimal'],
+  ['extreme_simple', 'extreme-minimal'],
+  ['extrememinimal', 'extreme-minimal'],
+  ['extreme_minimal', 'extreme-minimal'],
+  ['mono', 'extreme-minimal'],
+  ['oneline', 'extreme-minimal'],
+  ['one-line', 'extreme-minimal'],
+  ['one_line', 'extreme-minimal'],
+]);
+
+export function normalizeOutputStyleId(value) {
+  const raw = clean(value).toLowerCase();
+  if (!raw) return '';
+  const slug = raw.replace(/[_\s]+/g, '-').replace(/^-+|-+$/g, '');
+  const compact = slug.replace(/[_.-]+/g, '');
+  if (OUTPUT_STYLE_ALIASES.has(slug)) return OUTPUT_STYLE_ALIASES.get(slug);
+  if (OUTPUT_STYLE_ALIASES.has(compact)) return OUTPUT_STYLE_ALIASES.get(compact);
+  return /^[a-z0-9.-]+$/.test(slug) ? slug : '';
+}
+
+function outputStyleCompactKey(value) {
+  return normalizeOutputStyleId(value).replace(/[_.-]+/g, '');
+}
+
+function titleCaseOutputStyle(id) {
+  return clean(id)
+    .split(/[_.-]+/)
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join(' ') || 'Default';
+}
+
+function parseOutputStyleFrontmatter(markdown) {
+  const match = String(markdown || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const meta = {};
+  if (!match) return meta;
+  for (const line of match[1].split(/\r?\n/)) {
+    const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
+    if (!kv) continue;
+    meta[kv[1]] = kv[2].replace(/^['"]|['"]$/g, '').trim();
+  }
+  return meta;
+}
+
+function readOutputStyleMetadata(filePath, source) {
+  let raw = '';
+  try { raw = readFileSync(filePath, 'utf8'); } catch { return null; }
+  const meta = parseOutputStyleFrontmatter(raw);
+  const fileId = normalizeOutputStyleId(basename(filePath).replace(/\.md$/i, ''));
+  const id = normalizeOutputStyleId(meta.name) || fileId;
+  if (!id) return null;
+  const aliases = clean(meta.aliases)
+    .split(',')
+    .map((value) => normalizeOutputStyleId(value))
+    .filter(Boolean);
+  const label = clean(meta.title || meta.label) || titleCaseOutputStyle(id);
+  return {
+    id,
+    label,
+    description: clean(meta.description),
+    aliases,
+    source,
+  };
+}
+
+export function listOutputStyleCatalog(rootDir, dataDir) {
+  const byId = new Map();
+  const dirs = [
+    { dir: join(rootDir, 'output-styles'), source: 'builtin' },
+    { dir: join(dataDir, 'output-styles'), source: 'user' },
+  ];
+  for (const { dir, source } of dirs) {
+    let entries = [];
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.toLowerCase().endsWith('.md')) continue;
+      const style = readOutputStyleMetadata(join(dir, entry.name), source);
+      if (style) byId.set(style.id, style);
+    }
+  }
+  return [...byId.values()].sort((a, b) => {
+    const ai = OUTPUT_STYLE_ORDER.indexOf(a.id);
+    const bi = OUTPUT_STYLE_ORDER.indexOf(b.id);
+    if (ai !== bi) return (ai < 0 ? 999 : ai) - (bi < 0 ? 999 : bi);
+    return a.label.localeCompare(b.label, 'en', { sensitivity: 'base' });
+  });
+}
+
+export function findOutputStyle(value, styles) {
+  const id = normalizeOutputStyleId(value);
+  const compact = outputStyleCompactKey(value);
+  if (!id && !compact) return null;
+  return (styles || []).find((style) => {
+    if (style.id === id || outputStyleCompactKey(style.id) === compact) return true;
+    if (outputStyleCompactKey(style.label) === compact) return true;
+    return (style.aliases || []).some((alias) => alias === id || outputStyleCompactKey(alias) === compact);
+  }) || null;
+}
+
+function configuredOutputStyleValue(dataDir) {
+  const unified = readJsonSafe(join(dataDir, 'mixdog-config.json')) || {};
+  return clean(unified.outputStyle || (unified.agent && unified.agent.outputStyle) || 'default') || 'default';
+}
+
+export function outputStyleStatus(rootDir, dataDir) {
+  const styles = listOutputStyleCatalog(rootDir, dataDir);
+  const configured = configuredOutputStyleValue(dataDir);
+  const current = findOutputStyle(configured, styles)
+    || findOutputStyle('default', styles)
+    || styles[0]
+    || { id: 'default', label: 'Default', description: '', aliases: [], source: 'builtin' };
+  return { configured, current, styles };
+}

package/src/session-runtime/plugin-mcp.mjs

@@ -0,0 +1,114 @@
+// Plugin/project MCP server discovery + normalization, and skill-file counting.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { clean } from './session-text.mjs';
+import { readJsonSafe } from './fs-utils.mjs';
+
+// Project-local MCP ingress: read `.mcp.json` from the project root and return
+// a cleaned { name: cfg } map. Best-effort — never throws. Accepts either the
+// standard `{ mcpServers: {...} }` shape or a bare name->cfg map. Self-ref
+// servers (`mixdog` / `trib-plugin`) are stripped for parity with loadConfig.
+// Inputs are not mutated.
+export function readProjectMcpServers(cwd) {
+  const path = join(cwd || '.', '.mcp.json');
+  if (!existsSync(path)) return {};
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    process.stderr.write(`[mcp-client] Ignoring unparseable .mcp.json at ${path}: ${error?.message || String(error)}\n`);
+    return {};
+  }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+  const map = raw.mcpServers && typeof raw.mcpServers === 'object' && !Array.isArray(raw.mcpServers)
+    ? raw.mcpServers
+    : raw;
+  if (!map || typeof map !== 'object' || Array.isArray(map)) return {};
+  const out = {};
+  for (const [name, cfg] of Object.entries(map)) {
+    const key = clean(name);
+    if (!key) continue;
+    const lower = key.toLowerCase();
+    if (lower === 'mixdog' || lower === 'trib-plugin') continue;
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg)) continue;
+    // stdio entries (command + no url) spawn relative to the process launch
+    // dir, but mixdog tracks the project dir in memory (no process.chdir).
+    // Anchor their cwd to the .mcp.json directory: default when absent, resolve
+    // relative values against it, keep absolute values as-is.
+    const isStdio = typeof cfg.command === 'string' && cfg.command !== '' && !cfg.url;
+    if (isStdio) {
+      out[key] = { ...cfg, cwd: typeof cfg.cwd === 'string' && cfg.cwd ? resolve(cwd, cfg.cwd) : resolve(cwd) };
+    } else {
+      out[key] = cfg;
+    }
+  }
+  return out;
+}
+
+export function countSkillFiles(root) {
+  const skillsDir = join(root, 'skills');
+  if (!existsSync(skillsDir)) return 0;
+  let count = 0;
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (/^(SKILL|skill)\.md$/i.test(entry.name) || entry.name.toLowerCase().endsWith('.md')) count += 1;
+    }
+  };
+  try { walk(skillsDir); } catch { return count; }
+  return count;
+}
+
+export function mcpScriptForPlugin(root) {
+  const candidates = [
+    '.mcp.json',
+    'scripts/run-mcp.mjs',
+    'mcp/server.mjs',
+    'server.mjs',
+  ];
+  return candidates.find((rel) => existsSync(join(root, rel))) || null;
+}
+
+function substitutePluginRootTokens(value, root) {
+  if (typeof value !== 'string') return value;
+  return value
+    .replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, root)
+    .replace(/\$\{CODEX_PLUGIN_ROOT\}/g, root);
+}
+
+function substitutePluginRootTokensDeep(value, root) {
+  if (typeof value === 'string') return substitutePluginRootTokens(value, root);
+  if (Array.isArray(value)) return value.map((v) => substitutePluginRootTokensDeep(v, root));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = substitutePluginRootTokensDeep(v, root);
+    return out;
+  }
+  return value;
+}
+
+export function normalizePluginMcpServerConfig(cfg, root) {
+  const substituted = substitutePluginRootTokensDeep(cfg, root) || {};
+  const out = { ...substituted };
+  if (typeof out.cwd === 'string' && out.cwd) {
+    out.cwd = isAbsolute(out.cwd) ? out.cwd : join(root, out.cwd);
+  } else {
+    out.cwd = root;
+  }
+  return out;
+}
+
+export function pluginManifest(root) {
+  return readJsonSafe(join(root, '.codex-plugin', 'plugin.json'))
+    || readJsonSafe(join(root, 'plugin.json'))
+    || {};
+}
+
+export function pluginMcpServerName(plugin = {}) {
+  const base = clean(plugin.name || plugin.title || 'plugin')
+    .toLowerCase()
+    .replace(/[^a-z0-9_.-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return base ? `plugin-${base}` : 'plugin-mcp';
+}