@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/control-plane/scripts/sync-skills.mjs

@@ -0,0 +1,370 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { parseDocument } from 'yaml';
+
+import { assertSafeRelativePath, resolveSafeFile } from './skill-source-safety.mjs';
+import { createSkillRegistry } from './skills/index.mjs';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const skillsDirectory = path.join(scriptDirectory, 'skills');
+const manifestPath = path.join(skillsDirectory, 'sources.json');
+const lockPath = path.join(skillsDirectory, 'sources.lock.json');
+const licensesDirectoryName = '_upstream_licenses';
+const checkOnly = process.argv.includes('--check');
+const forbiddenExtensions = new Set(['.ttf', '.otf', '.woff', '.woff2', '.eot']);
+const maxFileBytes = 20 * 1024 * 1024;
+
+function readJson(filePath, fallback = null) {
+  if (!fs.existsSync(filePath)) return fallback;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJsonAtomic(filePath, value) {
+  const temporaryPath = `${filePath}.${process.pid}.tmp`;
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(temporaryPath, filePath);
+}
+
+function git(args, cwd) {
+  return execFileSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true
+  }).trim();
+}
+
+function assertSafeSegment(value, label) {
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(value) || value === '.' || value === '..') {
+    throw new Error(`Unsafe ${label}: ${value}`);
+  }
+}
+
+function assertSafeFile(filePath, label) {
+  if (!fs.existsSync(filePath)) throw new Error(`Missing ${label}: ${filePath}`);
+  const stat = fs.lstatSync(filePath);
+  if (stat.isSymbolicLink()) throw new Error(`Symlink is not allowed for ${label}: ${filePath}`);
+  if (!stat.isFile()) throw new Error(`Expected file for ${label}: ${filePath}`);
+  if (stat.size > maxFileBytes) throw new Error(`${label} exceeds ${maxFileBytes} bytes: ${filePath}`);
+  if (forbiddenExtensions.has(path.extname(filePath).toLowerCase())) {
+    throw new Error(`Font files are not vendored: ${filePath}`);
+  }
+}
+
+function assertSafeTree(root) {
+  const pending = [root];
+  while (pending.length) {
+    const current = pending.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.name === '.git') throw new Error(`Nested .git directory is not allowed: ${current}`);
+      const entryPath = path.join(current, entry.name);
+      const stat = fs.lstatSync(entryPath);
+      if (stat.isSymbolicLink()) throw new Error(`Symlink is not allowed in vendored skills: ${entryPath}`);
+      if (stat.isDirectory()) {
+        pending.push(entryPath);
+        continue;
+      }
+      assertSafeFile(entryPath, 'skill file');
+    }
+  }
+}
+
+function applyFrontmatterPatch(targetDirectory, patch, sourceId, folder) {
+  if (!patch || !Object.keys(patch).length) return;
+  const skillFile = path.join(targetDirectory, 'SKILL.md');
+  const raw = fs.readFileSync(skillFile, 'utf8');
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!match) throw new Error(`Missing YAML frontmatter for ${sourceId}/${folder}`);
+  const document = parseDocument(match[1]);
+  if (document.errors.length || !document.contents) {
+    throw new Error(`Invalid YAML frontmatter for ${sourceId}/${folder}`);
+  }
+  for (const [key, value] of Object.entries(patch)) document.set(key, value);
+  const frontmatter = document.toString({ lineWidth: 0 }).trimEnd();
+  const next = `---\n${frontmatter}\n---\n${raw.slice(match[0].length)}`;
+  fs.writeFileSync(skillFile, next);
+}
+
+function applyCompatibility(cloneDirectory, targetDirectory, compatibility, sourceId, folder) {
+  applyFrontmatterPatch(targetDirectory, compatibility.frontmatter, sourceId, folder);
+
+  for (const cleanup of compatibility.cleanup || []) {
+    const targetFile = resolveSafeFile(targetDirectory, cleanup.path, `compatibility cleanup file for ${sourceId}/${folder}`, {
+      maxFileBytes,
+      forbiddenExtensions
+    });
+    let text = fs.readFileSync(targetFile, 'utf8');
+    if (cleanup.trimTrailingWhitespace) text = text.replace(/[ \t]+(?=\r?$)/gm, '');
+    if (cleanup.trimTrailingBlankLines) text = text.replace(/(?:\r?\n)+$/, '\n');
+    if (!cleanup.trimTrailingWhitespace && !cleanup.trimTrailingBlankLines) {
+      throw new Error(`Compatibility cleanup requires an operation for ${sourceId}/${folder}`);
+    }
+    fs.writeFileSync(targetFile, text);
+  }
+
+  for (const file of compatibility.files || []) {
+    const sourceFile = resolveSafeFile(cloneDirectory, file.path, `compatibility file for ${sourceId}/${folder}`, {
+      maxFileBytes,
+      forbiddenExtensions
+    });
+    const targetFile = path.join(targetDirectory, assertSafeRelativePath(file.target, 'compatibility target path'));
+    if (fs.existsSync(targetFile)) throw new Error(`Compatibility target already exists: ${targetFile}`);
+    fs.mkdirSync(path.dirname(targetFile), { recursive: true });
+    fs.copyFileSync(sourceFile, targetFile);
+  }
+
+  for (const replacement of compatibility.replacements || []) {
+    const targetFile = resolveSafeFile(targetDirectory, replacement.path, `compatibility replacement file for ${sourceId}/${folder}`, {
+      maxFileBytes,
+      forbiddenExtensions
+    });
+    const search = typeof replacement.search === 'string'
+      ? replacement.search
+      : Array.isArray(replacement.searchParts) && replacement.searchParts.every(part => typeof part === 'string')
+        ? replacement.searchParts.join('')
+        : '';
+    if (!search) {
+      throw new Error(`Compatibility replacement search or searchParts is required for ${sourceId}/${folder}`);
+    }
+    if (typeof replacement.replace !== 'string') {
+      throw new Error(`Compatibility replacement value is required for ${sourceId}/${folder}`);
+    }
+    const text = fs.readFileSync(targetFile, 'utf8');
+    const occurrences = text.split(search).length - 1;
+    const expectedOccurrences = replacement.count ?? 1;
+    if (!Number.isInteger(expectedOccurrences) || expectedOccurrences < 1) {
+      throw new Error(`Compatibility replacement count must be a positive integer for ${sourceId}/${folder}`);
+    }
+    if (occurrences !== expectedOccurrences) {
+      throw new Error(`Expected ${expectedOccurrences} compatibility replacement matches in ${targetFile}, found ${occurrences}`);
+    }
+    fs.writeFileSync(targetFile, text.replaceAll(search, replacement.replace));
+  }
+
+  assertSafeTree(targetDirectory);
+}
+
+function renameWithRetry(source, target) {
+  let lastError;
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    try {
+      fs.renameSync(source, target);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (!['EPERM', 'EACCES', 'EBUSY'].includes(error.code) || attempt === 7) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50 * (attempt + 1));
+    }
+  }
+  throw lastError;
+}
+
+function directoryFingerprint(root) {
+  const hash = createHash('sha256');
+
+  function visit(directory, relative = '') {
+    const entries = fs.readdirSync(directory, { withFileTypes: true })
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const absolute = path.join(directory, entry.name);
+      const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
+      const stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) throw new Error(`Symlink is not allowed while fingerprinting: ${absolute}`);
+      if (stat.isDirectory()) {
+        hash.update(`d\0${childRelative}\0`);
+        visit(absolute, childRelative);
+        continue;
+      }
+      if (!stat.isFile()) throw new Error(`Only regular files are allowed while fingerprinting: ${absolute}`);
+      hash.update(`f\0${childRelative}\0${stat.size}\0`);
+      hash.update(fs.readFileSync(absolute));
+    }
+  }
+
+  visit(root);
+  return hash.digest('hex');
+}
+
+function replaceDirectory(target, staged) {
+  if (fs.existsSync(target) && directoryFingerprint(target) === directoryFingerprint(staged)) {
+    fs.rmSync(staged, { recursive: true, force: true });
+    return;
+  }
+
+  const backup = path.join(path.dirname(target), `.skill-backup-${process.pid}-${path.basename(target)}`);
+  fs.rmSync(backup, { recursive: true, force: true });
+  if (fs.existsSync(target)) renameWithRetry(target, backup);
+  try {
+    renameWithRetry(staged, target);
+    fs.rmSync(backup, { recursive: true, force: true });
+  } catch (error) {
+    fs.rmSync(target, { recursive: true, force: true });
+    if (fs.existsSync(backup)) renameWithRetry(backup, target);
+    throw error;
+  }
+}
+
+function sourceSummary(lock) {
+  return new Map((lock?.sources || []).map(source => [source.id, source.commit]));
+}
+
+const manifest = readJson(manifestPath);
+if (!manifest || manifest.version !== 1 || !Array.isArray(manifest.sources)) {
+  throw new Error(`Invalid skill source manifest: ${manifestPath}`);
+}
+
+fs.mkdirSync(skillsDirectory, { recursive: true });
+const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-mcp-skills-'));
+const preparedSkills = path.join(temporaryRoot, 'prepared');
+const preparedLicenses = path.join(preparedSkills, licensesDirectoryName);
+fs.mkdirSync(preparedLicenses, { recursive: true });
+
+try {
+  const targetOwners = new Map();
+  const sourceLocks = [];
+
+  for (const source of manifest.sources) {
+    assertSafeSegment(source.id, 'source id');
+    if (!source.repository || !source.ref || !source.skillRoot || !Array.isArray(source.include)) {
+      throw new Error(`Incomplete source configuration: ${source.id}`);
+    }
+
+    const cloneDirectory = path.join(temporaryRoot, `source-${source.id}`);
+    console.log(`[skills] fetching ${source.id} (${source.ref})`);
+    git(['clone', '--depth', '1', '--single-branch', '--branch', source.ref, source.repository, cloneDirectory]);
+    const commit = git(['rev-parse', 'HEAD'], cloneDirectory);
+    const installed = [];
+
+    if (source.requireRootLicense) {
+      const licensePath = resolveSafeFile(cloneDirectory, source.requireRootLicense.path, `root license for ${source.id}`, {
+        maxFileBytes,
+        forbiddenExtensions
+      });
+      const licenseText = fs.readFileSync(licensePath, 'utf8');
+      if (!licenseText.includes(source.requireRootLicense.contains)) {
+        throw new Error(`Unexpected root license for ${source.id}`);
+      }
+    }
+
+    for (const folder of source.include) {
+      assertSafeSegment(folder, `skill folder for ${source.id}`);
+      const owner = targetOwners.get(folder);
+      if (owner) throw new Error(`Skill folder collision: ${folder} (${owner}, ${source.id})`);
+      targetOwners.set(folder, source.id);
+
+      const skillFile = resolveSafeFile(
+        cloneDirectory,
+        path.join(source.skillRoot, folder, 'SKILL.md'),
+        `SKILL.md for ${source.id}/${folder}`,
+        { maxFileBytes, forbiddenExtensions }
+      );
+      const sourceDirectory = path.dirname(skillFile);
+      assertSafeTree(sourceDirectory);
+
+      if (source.requireSkillLicense) {
+        const licensePath = resolveSafeFile(sourceDirectory, source.requireSkillLicense.path, `required license for ${source.id}/${folder}`, {
+          maxFileBytes,
+          forbiddenExtensions
+        });
+        const licenseText = fs.readFileSync(licensePath, 'utf8');
+        if (!licenseText.includes(source.requireSkillLicense.contains)) {
+          throw new Error(`Unexpected license for ${source.id}/${folder}`);
+        }
+      }
+
+      const targetDirectory = path.join(preparedSkills, folder);
+      fs.cpSync(sourceDirectory, targetDirectory, { recursive: true, errorOnExist: true, force: false });
+      const compatibility = source.compatibility?.[folder] || {};
+      if (Object.keys(compatibility).length) {
+        applyCompatibility(cloneDirectory, targetDirectory, compatibility, source.id, folder);
+      }
+      installed.push({
+        target: folder,
+        path: `${source.skillRoot}/${folder}`,
+        ...(Object.keys(compatibility).length ? { compatibility } : {})
+      });
+    }
+
+    for (const rootFile of source.rootFiles || []) {
+      const sourceFile = resolveSafeFile(cloneDirectory, rootFile.path, `root notice for ${source.id}`, {
+        maxFileBytes,
+        forbiddenExtensions
+      });
+      assertSafeSegment(rootFile.target, 'root notice target');
+      fs.copyFileSync(sourceFile, path.join(preparedLicenses, rootFile.target));
+    }
+
+    sourceLocks.push({
+      id: source.id,
+      repository: source.repository,
+      ref: source.ref,
+      commit,
+      license: source.license,
+      skills: installed
+    });
+  }
+
+  const expectedCount = sourceLocks.reduce((total, source) => total + source.skills.length, 0);
+  const registry = createSkillRegistry({ directory: preparedSkills });
+  const discovered = registry.list();
+  if (discovered.length !== expectedCount) {
+    throw new Error(`Prepared catalog validation failed: expected ${expectedCount}, discovered ${discovered.length}`);
+  }
+
+  const nextLock = { version: 1, sources: sourceLocks };
+  const currentLock = readJson(lockPath, { version: 1, sources: [] });
+  const unchanged = JSON.stringify(currentLock) === JSON.stringify(nextLock);
+
+  if (checkOnly) {
+    if (unchanged) {
+      console.log('[skills] all managed sources are up to date');
+      process.exitCode = 0;
+    } else {
+      const current = sourceSummary(currentLock);
+      for (const source of sourceLocks) {
+        console.log(`[skills] update available ${source.id}: ${current.get(source.id) || '<not installed>'} -> ${source.commit}`);
+      }
+      process.exitCode = 1;
+    }
+  } else {
+    const oldManaged = new Set((currentLock.sources || []).flatMap(source => (source.skills || []).map(skill => skill.target)));
+    const newManaged = new Set(sourceLocks.flatMap(source => source.skills.map(skill => skill.target)));
+
+    for (const target of newManaged) {
+      const livePath = path.join(skillsDirectory, target);
+      if (fs.existsSync(livePath) && !oldManaged.has(target)) {
+        throw new Error(`Refusing to overwrite unmanaged skill directory: ${livePath}`);
+      }
+    }
+
+    const staged = new Map();
+    for (const target of newManaged) {
+      const stagedPath = path.join(skillsDirectory, `.skill-sync-${process.pid}-${target}`);
+      fs.rmSync(stagedPath, { recursive: true, force: true });
+      fs.cpSync(path.join(preparedSkills, target), stagedPath, { recursive: true });
+      staged.set(target, stagedPath);
+    }
+    const stagedLicenses = path.join(skillsDirectory, `.skill-sync-${process.pid}-${licensesDirectoryName}`);
+    fs.rmSync(stagedLicenses, { recursive: true, force: true });
+    fs.cpSync(preparedLicenses, stagedLicenses, { recursive: true });
+
+    for (const [target, stagedPath] of staged) {
+      replaceDirectory(path.join(skillsDirectory, target), stagedPath);
+    }
+    replaceDirectory(path.join(skillsDirectory, licensesDirectoryName), stagedLicenses);
+
+    for (const stale of oldManaged) {
+      if (!newManaged.has(stale)) fs.rmSync(path.join(skillsDirectory, stale), { recursive: true, force: true });
+    }
+
+    writeJsonAtomic(lockPath, nextLock);
+    console.log(`[skills] synchronized ${expectedCount} skills from ${sourceLocks.length} sources`);
+    for (const source of sourceLocks) console.log(`[skills] ${source.id}: ${source.commit} (${source.skills.length} skills)`);
+  }
+} finally {
+  fs.rmSync(temporaryRoot, { recursive: true, force: true });
+}

package/control-plane/scripts/tool-metrics.mjs

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function byteSize(value) {
+  const json = JSON.stringify(value ?? {});
+  return Buffer.byteLength(json || '', 'utf8');
+}
+
+export function buildToolMetric({
+  toolName,
+  args,
+  result,
+  durationMs,
+  callerCategory = null,
+  accountId = null,
+  activitySessionId = null,
+  deviceId = null,
+  skillName = null,
+  upstream = null,
+  error = null
+} = {}) {
+  const structured = result?.structuredContent || {};
+  const success = !error && result?.isError !== true;
+  return {
+    timestamp: new Date().toISOString(),
+    tool: String(toolName || 'unknown'),
+    durationMs: Math.max(0, Number(durationMs) || 0),
+    success,
+    error: error ? 'exception' : (result?.isError === true ? 'tool-error' : null),
+    inputBytes: byteSize(args),
+    outputBytes: byteSize(result),
+    truncated: Boolean(structured.stdoutTruncated || structured.stderrTruncated),
+    spill: Boolean(structured.stdoutSpillPath || structured.stderrSpillPath),
+    callerCategory: callerCategory ? String(callerCategory).slice(0, 32) : null,
+    accountId: accountId ? String(accountId).slice(0, 128) : null,
+    activitySessionId: activitySessionId ? String(activitySessionId).slice(0, 128) : null,
+    deviceId: deviceId ? String(deviceId).slice(0, 64) : null,
+    skillName: skillName ? String(skillName).slice(0, 128) : null,
+    errorCode: error ? String(error.code || 'EXCEPTION').slice(0, 64) : (result?.isError === true ? String(structured.code || 'TOOL_ERROR').slice(0, 64) : null),
+    upstream: upstream ? String(upstream).slice(0, 128) : null
+  };
+}
+
+export function createToolMetricsRecorder({ metricsPath, enabled = true } = {}) {
+  let fd = null;
+  let warned = false;
+
+  function ensureOpen() {
+    if (!enabled || fd !== null) return;
+    if (!metricsPath) throw new Error('metricsPath is required when metrics are enabled');
+    fs.mkdirSync(path.dirname(metricsPath), { recursive: true });
+    fd = fs.openSync(metricsPath, 'a');
+  }
+
+  return {
+    record(metric) {
+      if (!enabled) return;
+      try {
+        ensureOpen();
+        fs.writeSync(fd, `${JSON.stringify(metric)}\n`, null, 'utf8');
+      } catch (error) {
+        if (!warned) {
+          warned = true;
+          console.error(`[metrics] append failed: ${error.message}`);
+        }
+      }
+    },
+    close() {
+      if (fd === null) return;
+      fs.closeSync(fd);
+      fd = null;
+    }
+  };
+}

package/control-plane/scripts/tool-risk.mjs

@@ -0,0 +1,156 @@
+export const TOOL_CATEGORIES = {
+  filesystem: 'filesystem',
+  shell: 'shell',
+  platform: 'platform'
+};
+
+const READ_ONLY = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  destructiveHint: false,
+  openWorldHint: false,
+  riskLevel: 'low'
+};
+
+const MUTATING_FILE = {
+  readOnlyHint: false,
+  idempotentHint: false,
+  destructiveHint: true,
+  openWorldHint: false,
+  riskLevel: 'low',
+  category: TOOL_CATEGORIES.filesystem
+};
+
+const RISK_MAP = new Map(Object.entries({
+  read_text_file: { ...READ_ONLY, category: TOOL_CATEGORIES.filesystem },
+  write_file: { ...MUTATING_FILE, idempotentHint: true },
+  edit_file: { ...MUTATING_FILE },
+  list_allowed_directories: { ...READ_ONLY, category: TOOL_CATEGORIES.filesystem },
+  image_preview: { ...READ_ONLY, category: TOOL_CATEGORIES.filesystem },
+  skill_catalog: { ...READ_ONLY, category: TOOL_CATEGORIES.platform },
+  load_skill: { ...READ_ONLY, category: TOOL_CATEGORIES.platform },
+  project_list: { ...READ_ONLY, category: TOOL_CATEGORIES.platform },
+  project_inspect: { ...READ_ONLY, category: TOOL_CATEGORIES.platform },
+  external_tool_search: { ...READ_ONLY, category: TOOL_CATEGORIES.platform },
+  external_tool_call_read: { ...READ_ONLY, category: TOOL_CATEGORIES.platform },
+  external_tool_call_write: {
+    readOnlyHint: false,
+    idempotentHint: false,
+    destructiveHint: true,
+    openWorldHint: false,
+    riskLevel: 'low',
+    category: TOOL_CATEGORIES.platform
+  },
+  list_devices: { ...READ_ONLY, category: TOOL_CATEGORIES.platform },
+  shell_execute: {
+    readOnlyHint: false,
+    idempotentHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+    riskLevel: 'low',
+    category: TOOL_CATEGORIES.shell
+  },
+  start_process: {
+    readOnlyHint: false,
+    idempotentHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+    riskLevel: 'low',
+    category: TOOL_CATEGORIES.shell
+  },
+  read_process_output: { ...READ_ONLY, category: TOOL_CATEGORIES.shell },
+  interact_with_process: {
+    readOnlyHint: false,
+    idempotentHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+    riskLevel: 'low',
+    category: TOOL_CATEGORIES.shell
+  },
+  terminate_process: {
+    readOnlyHint: false,
+    idempotentHint: true,
+    destructiveHint: true,
+    openWorldHint: true,
+    riskLevel: 'low',
+    category: TOOL_CATEGORIES.shell
+  }
+}));
+
+export function normalizeRiskToolName(toolOrName) {
+  const name = typeof toolOrName === 'string' ? toolOrName : toolOrName?.name;
+  const value = String(name || '');
+  return value.startsWith('custom_') ? value.slice('custom_'.length) : value;
+}
+
+export function getToolRisk(toolOrName) {
+  const name = normalizeRiskToolName(toolOrName);
+  return RISK_MAP.get(name) || {
+    readOnlyHint: false,
+    idempotentHint: false,
+    destructiveHint: false,
+    openWorldHint: false,
+    riskLevel: 'unknown',
+    category: 'unknown'
+  };
+}
+
+export function applyToolRisk(tool) {
+  const risk = getToolRisk(tool);
+  return {
+    ...tool,
+    annotations: {
+      ...(tool.annotations || {}),
+      readOnlyHint: risk.readOnlyHint,
+      idempotentHint: risk.idempotentHint,
+      destructiveHint: risk.destructiveHint,
+      openWorldHint: risk.openWorldHint
+    },
+    _meta: {
+      ...(tool._meta || {}),
+      riskLevel: risk.riskLevel,
+      category: risk.category,
+      profileVisibility: {
+        safe: shouldExposeToolForProfile(tool, { name: 'safe', exposeShell: false, exposeDestructiveTools: false, exposeOpenWorldTools: false }),
+        assisted: shouldExposeToolForProfile(tool, { name: 'assisted', exposeShell: false, exposeDestructiveTools: true, exposeOpenWorldTools: false }),
+        yolo: shouldExposeToolForProfile(tool, { name: 'yolo', exposeShell: true, exposeDestructiveTools: true, exposeOpenWorldTools: true })
+      }
+    }
+  };
+}
+
+export function shouldExposeToolForProfile(toolOrName, safetyProfile) {
+  const name = normalizeRiskToolName(toolOrName);
+  const risk = getToolRisk(toolOrName);
+  if (['shell_execute', 'start_process', 'read_process_output', 'interact_with_process', 'terminate_process'].includes(name)) {
+    return Boolean(safetyProfile.exposeShell);
+  }
+  if (risk.openWorldHint && !safetyProfile.exposeOpenWorldTools) return false;
+  if (risk.destructiveHint && !safetyProfile.exposeDestructiveTools) return false;
+  return true;
+}
+
+export function assertToolAllowedForProfile(toolOrName, safetyProfile) {
+  if (!shouldExposeToolForProfile(toolOrName, safetyProfile)) {
+    const name = typeof toolOrName === 'string' ? toolOrName : toolOrName?.name;
+    throw new Error(`Tool ${name} is disabled by MCP_RUNTIME_PROFILE=${safetyProfile.name}.`);
+  }
+}
+
+export function buildToolRiskManifest(tools, safetyProfile) {
+  return tools.map(tool => {
+    const risk = getToolRisk(tool);
+    const visible = shouldExposeToolForProfile(tool, safetyProfile);
+    return {
+      name: tool.name,
+      category: risk.category,
+      riskLevel: risk.riskLevel,
+      readOnlyHint: risk.readOnlyHint,
+      idempotentHint: risk.idempotentHint,
+      destructiveHint: risk.destructiveHint,
+      openWorldHint: risk.openWorldHint,
+      visible,
+      reason: visible ? `Visible because MCP_RUNTIME_PROFILE=${safetyProfile.name}.` : `Hidden because MCP_RUNTIME_PROFILE=${safetyProfile.name}.`
+    };
+  });
+}

package/control-plane/scripts/tool-surface-stability.mjs

@@ -0,0 +1,38 @@
+const DYNAMIC_ROOT_META_KEYS = new Set(['trusted_roots', 'root_repo', 'repo_root']);
+
+export const LOCAL_COLLISION_TOOL_NAMES = new Set([
+  'read_text_file',
+  'write_file',
+  'edit_file',
+  'shell_execute',
+  'image_preview',
+  'skill_catalog',
+  'load_skill',
+  'project_list',
+  'project_inspect',
+  'external_tool_search',
+  'external_tool_call_read',
+  'external_tool_call_write',
+  'list_devices',
+  'start_process',
+  'read_process_output',
+  'interact_with_process',
+  'terminate_process'
+]);
+
+export function stableToolDefinition(tool = {}) {
+  const meta = { ...(tool._meta || {}) };
+  for (const key of DYNAMIC_ROOT_META_KEYS) delete meta[key];
+  const stable = { ...tool };
+  if (Object.keys(meta).length > 0) stable._meta = meta;
+  else delete stable._meta;
+  return stable;
+}
+
+export function workspaceCatalogChanges(change = {}, surfaceConfig = {}) {
+  return {
+    toolsChanged: false,
+    resourcesChanged: Boolean(change.rootsChanged && surfaceConfig.enumerateProjectResources),
+    promptsChanged: false
+  };
+}

package/control-plane/scripts/upstreams/catalog-cache.mjs

@@ -0,0 +1,28 @@
+export function createCatalogSnapshot({ generation = 0, diagnostics = {}, builtAt = new Date().toISOString() } = {}) {
+  return {
+    tools: [],
+    resources: [],
+    resourceTemplates: [],
+    prompts: [],
+    toolRoutes: new Map(),
+    resourceRoutes: new Map(),
+    promptRoutes: new Map(),
+    diagnostics,
+    builtAt,
+    generation
+  };
+}
+
+export function createCatalogState({ snapshot = createCatalogSnapshot() } = {}) {
+  return {
+    snapshot,
+    lastRefreshAt: snapshot.builtAt || null,
+    refreshInFlight: null,
+    lastRefreshError: null,
+    generation: snapshot.generation || 0
+  };
+}
+
+export function createCatalogCache() {
+  return createCatalogSnapshot();
+}