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

package/control-plane/scripts/benchmark-command.mjs

@@ -0,0 +1,9 @@
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+export function buildNodeOutputCommand(bytes, { platform = process.platform, execPath = process.execPath } = {}) {
+  const executable = shellQuote(execPath);
+  const script = shellQuote(`process.stdout.write(Buffer.alloc(${bytes}, 120))`);
+  return platform === 'win32' ? `& ${executable} -e ${script}` : `${executable} -e ${script}`;
+}

package/control-plane/scripts/benchmark-mcp-catalog.mjs

@@ -0,0 +1,174 @@
+import { pathToFileURL } from 'node:url';
+
+function jsonBytes(value) {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+
+function defaultClassifyTool(tool) {
+  if (tool?._meta?.upstream?.source === 'external-mcp') return 'external';
+  return 'core';
+}
+
+export function measureCatalogPayload({
+  toolsPayload = { tools: [] },
+  resourcesPayload = { resources: [] },
+  templatesPayload = { resourceTemplates: [] },
+  promptsPayload = { prompts: [] },
+  classifyTool = defaultClassifyTool
+} = {}) {
+  const tools = Array.isArray(toolsPayload?.tools) ? toolsPayload.tools : [];
+  const resources = Array.isArray(resourcesPayload?.resources) ? resourcesPayload.resources : [];
+  const templates = Array.isArray(templatesPayload?.resourceTemplates) ? templatesPayload.resourceTemplates : [];
+  const prompts = Array.isArray(promptsPayload?.prompts) ? promptsPayload.prompts : [];
+  const groups = {
+    core: { count: 0, bytes: 0 },
+    external: { count: 0, bytes: 0 },
+    other: { count: 0, bytes: 0 }
+  };
+
+  for (const tool of tools) {
+    const rawGroup = classifyTool(tool);
+    const group = Object.prototype.hasOwnProperty.call(groups, rawGroup) ? rawGroup : 'other';
+    groups[group].count += 1;
+    groups[group].bytes += jsonBytes(tool);
+  }
+
+  return {
+    toolCount: tools.length,
+    toolSchemaBytes: jsonBytes(toolsPayload),
+    resourceCount: resources.length,
+    resourceTemplateCount: templates.length,
+    promptCount: prompts.length,
+    groups
+  };
+}
+
+export function parseSyntheticCounts(value) {
+  const parts = String(value ?? '').split(',').map(part => Number(part.trim()));
+  if (parts.length !== 4 || parts.some(part => !Number.isInteger(part) || part < 0)) {
+    throw new Error('Invalid synthetic counts; expected tools,resources,templates,prompts as non-negative integers.');
+  }
+  const [tools, resources, templates, prompts] = parts;
+  return { tools, resources, templates, prompts };
+}
+
+function syntheticPayloads(counts) {
+  return {
+    toolsPayload: {
+      tools: Array.from({ length: counts.tools }, (_, index) => ({
+        name: `synthetic_tool_${index + 1}`,
+        description: 'Synthetic catalog benchmark tool.',
+        inputSchema: { type: 'object', properties: {} }
+      }))
+    },
+    resourcesPayload: {
+      resources: Array.from({ length: counts.resources }, (_, index) => ({
+        uri: `synthetic://resource/${index + 1}`,
+        name: `Synthetic resource ${index + 1}`
+      }))
+    },
+    templatesPayload: {
+      resourceTemplates: Array.from({ length: counts.templates }, (_, index) => ({
+        uriTemplate: `synthetic://template/${index + 1}/{id}`,
+        name: `Synthetic template ${index + 1}`
+      }))
+    },
+    promptsPayload: {
+      prompts: Array.from({ length: counts.prompts }, (_, index) => ({ name: `synthetic_prompt_${index + 1}` }))
+    }
+  };
+}
+
+function parseArgs(argv) {
+  const result = { url: '', bearerEnv: '', synthetic: '' };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--url') result.url = argv[++index] || '';
+    else if (arg === '--bearer-env') result.bearerEnv = argv[++index] || '';
+    else if (arg === '--synthetic') result.synthetic = argv[++index] || '';
+    else if (arg === '--help' || arg === '-h') result.help = true;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return result;
+}
+
+function parseMcpResponse(text) {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) throw new Error('Empty MCP response.');
+  if (trimmed.startsWith('{')) return JSON.parse(trimmed);
+  const dataLines = trimmed
+    .split(/\r?\n/)
+    .filter(line => line.startsWith('data:'))
+    .map(line => line.slice(5).trim())
+    .filter(Boolean);
+  if (!dataLines.length) throw new Error(`Unexpected MCP response: ${trimmed.slice(0, 300)}`);
+  return JSON.parse(dataLines.join('\n'));
+}
+
+async function mcpRequest(url, id, method, token, params = {}) {
+  const headers = {
+    accept: 'application/json, text/event-stream',
+    'content-type': 'application/json'
+  };
+  if (token) headers.authorization = `Bearer ${token}`;
+  const response = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ jsonrpc: '2.0', id, method, params })
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`MCP HTTP ${response.status}: ${text.slice(0, 300)}`);
+  const parsed = parseMcpResponse(text);
+  if (parsed?.error) throw new Error(`MCP ${method} failed: ${parsed.error.message || JSON.stringify(parsed.error)}`);
+  return parsed?.result || {};
+}
+
+async function measureRemoteCatalog({ url, token }) {
+  let id = 1;
+  await mcpRequest(url, id++, 'initialize', token, {
+    protocolVersion: '2025-03-26',
+    capabilities: {},
+    clientInfo: { name: 'catalog-benchmark', version: '1.0.0' }
+  });
+  const [toolsPayload, resourcesPayload, templatesPayload, promptsPayload] = await Promise.all([
+    mcpRequest(url, id++, 'tools/list', token),
+    mcpRequest(url, id++, 'resources/list', token),
+    mcpRequest(url, id++, 'resources/templates/list', token),
+    mcpRequest(url, id++, 'prompts/list', token)
+  ]);
+  return measureCatalogPayload({ toolsPayload, resourcesPayload, templatesPayload, promptsPayload });
+}
+
+function usage() {
+  return [
+    'Usage:',
+    '  npm run benchmark:catalog -- --url http://127.0.0.1:8102/mcp [--bearer-env MCP_BEARER_TOKEN]',
+    '  npm run benchmark:catalog -- --synthetic 86,75,3,36'
+  ].join('\n');
+}
+
+export async function main(argv = process.argv.slice(2), env = process.env) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    process.stdout.write(`${usage()}\n`);
+    return;
+  }
+
+  let report;
+  if (args.synthetic) {
+    report = measureCatalogPayload(syntheticPayloads(parseSyntheticCounts(args.synthetic)));
+  } else {
+    if (!args.url) throw new Error('--url is required unless --synthetic is used.');
+    const token = args.bearerEnv ? String(env[args.bearerEnv] || '') : '';
+    if (args.bearerEnv && !token) throw new Error(`Bearer token environment variable is empty: ${args.bearerEnv}`);
+    report = await measureRemoteCatalog({ url: args.url, token });
+  }
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || '').href) {
+  main().catch(error => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/control-plane/scripts/catalog-budget.mjs

@@ -0,0 +1,87 @@
+export function catalogToolBytes(tool) {
+  return Buffer.byteLength(JSON.stringify(tool), 'utf8');
+}
+
+export function classifyExternalToolLane(tool) {
+  const annotations = tool?.annotations;
+  return annotations?.readOnlyHint === true &&
+    annotations?.destructiveHint === false &&
+    annotations?.openWorldHint === false
+    ? 'read'
+    : 'write';
+}
+
+function diagnostics(mode, budgetBytes, tools, eagerTools, deferredTools) {
+  const sumBytes = items => items.reduce((sum, tool) => sum + catalogToolBytes(tool), 0);
+  return {
+    mode,
+    budgetBytes,
+    total: { count: tools.length, bytes: sumBytes(tools) },
+    eager: { count: eagerTools.length, bytes: sumBytes(eagerTools) },
+    deferred: { count: deferredTools.length, bytes: sumBytes(deferredTools) }
+  };
+}
+
+export function selectExternalCatalog(tools = [], externalConfig = {}, servers = []) {
+  const mode = externalConfig.exposure_mode || 'direct';
+  const budgetBytes = Number(externalConfig.eager_schema_budget_bytes ?? 24576);
+  const allowlist = Array.isArray(externalConfig.eager_allowlist) ? externalConfig.eager_allowlist : [];
+
+  if (mode === 'direct') {
+    return {
+      eagerTools: [...tools],
+      deferredTools: [],
+      diagnostics: diagnostics(mode, budgetBytes, tools, tools, [])
+    };
+  }
+  if (mode === 'brokered') {
+    return {
+      eagerTools: [],
+      deferredTools: [...tools],
+      diagnostics: diagnostics(mode, budgetBytes, tools, [], tools)
+    };
+  }
+  if (mode !== 'hybrid') throw new Error(`Invalid external exposure mode: ${mode}`);
+
+  const byName = new Map(tools.map(tool => [tool.name, tool]));
+  const selected = [];
+  const selectedNames = new Set();
+  let usedBytes = 0;
+
+  for (const name of allowlist) {
+    const tool = byName.get(name);
+    if (!tool) throw new Error(`External MCP eager allowlist contains unknown tool: ${name}`);
+    const bytes = catalogToolBytes(tool);
+    if (usedBytes + bytes > budgetBytes) {
+      throw new Error(`External MCP eager allowlist exceeds schema budget at ${name}: ${usedBytes + bytes} > ${budgetBytes} bytes`);
+    }
+    selected.push(tool);
+    selectedNames.add(tool.name);
+    usedBytes += bytes;
+  }
+
+  const serverOrder = new Map(servers.map((server, index) => [server.id, index]));
+  const candidates = tools
+    .filter(tool => !selectedNames.has(tool.name) && classifyExternalToolLane(tool) === 'read')
+    .sort((left, right) => {
+      const leftOrder = serverOrder.get(left?._meta?.upstream?.upstreamId) ?? Number.MAX_SAFE_INTEGER;
+      const rightOrder = serverOrder.get(right?._meta?.upstream?.upstreamId) ?? Number.MAX_SAFE_INTEGER;
+      if (leftOrder !== rightOrder) return leftOrder - rightOrder;
+      return String(left.name).localeCompare(String(right.name));
+    });
+
+  for (const tool of candidates) {
+    const bytes = catalogToolBytes(tool);
+    if (usedBytes + bytes > budgetBytes) break;
+    selected.push(tool);
+    selectedNames.add(tool.name);
+    usedBytes += bytes;
+  }
+
+  const deferredTools = tools.filter(tool => !selectedNames.has(tool.name));
+  return {
+    eagerTools: selected,
+    deferredTools,
+    diagnostics: diagnostics(mode, budgetBytes, tools, selected, deferredTools)
+  };
+}

package/control-plane/scripts/check-device-public-contract.mjs

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildDevicePublicContract, classifyDevicePublicContractChanges } from './device-public-contract.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const fixturePath = path.join(root, 'contracts', 'device-public-contract-v1.json');
+const current = buildDevicePublicContract();
+
+if (process.argv.includes('--write')) {
+  fs.mkdirSync(path.dirname(fixturePath), { recursive: true });
+  fs.writeFileSync(fixturePath, `${JSON.stringify(current, null, 2)}\n`);
+  console.log(`Wrote ${path.relative(root, fixturePath)}`);
+  process.exit(0);
+}
+
+const baseline = JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+const result = classifyDevicePublicContractChanges(baseline, current);
+console.log(JSON.stringify(result, null, 2));
+if (result.counts.breaking > 0) process.exit(1);

package/control-plane/scripts/custom-tools/index.mjs

@@ -0,0 +1,221 @@
+import { fail, ok } from './response-utils.mjs';
+import { inspectProject, listProjects, PROJECT_INSPECTION_VIEWS } from '../project-inspection.mjs';
+import { applyToolRisk } from '../tool-risk.mjs';
+import { skillResourceUri } from '../skills/index.mjs';
+
+function schema(properties = {}, required = []) {
+  return { type: 'object', properties, required, additionalProperties: false };
+}
+
+function structuredOutputSchema() {
+  return {
+    type: 'object',
+    properties: {
+      ok: { type: 'boolean' },
+      tool: { type: 'string' },
+      summary: { type: 'string' },
+      data: { type: 'object' }
+    },
+    required: ['ok', 'tool', 'summary', 'data'],
+    additionalProperties: false
+  };
+}
+
+function requireExternalToolBroker(context = {}) {
+  if (!context.externalToolBroker) throw new Error('External tool broker is unavailable.');
+  return context.externalToolBroker;
+}
+
+function requireSkillRegistry(context = {}) {
+  if (!context.skillRegistry) throw new Error('Skill registry is unavailable.');
+  return context.skillRegistry;
+}
+
+function skillCatalog(args = {}, context = {}) {
+  const snapshot = requireSkillRegistry(context).snapshot();
+  const version = snapshot.catalogVersion;
+  if (String(args.known_version || '') === version) return { changed: false, version };
+  return {
+    changed: true,
+    version,
+    skills: snapshot.skills.map(skill => ({
+      name: skill.name,
+      description: skill.description,
+      uri: skill.uri,
+      revision: skill.skillRevision
+    }))
+  };
+}
+
+function loadSkill(args = {}, context = {}) {
+  const registry = requireSkillRegistry(context);
+  const skill = registry.getByName(String(args.name || ''));
+  if (!skill) throw new Error(`Unknown skill: ${args.name}`);
+  const resource = String(args.resource || '').trim();
+  if (!resource) {
+    return {
+      name: skill.name,
+      description: skill.description,
+      uri: skill.uri,
+      revision: skill.skillRevision,
+      body: skill.body,
+      resources: skill.resources
+    };
+  }
+  if (resource.startsWith('/') || resource.includes('\\') || resource.split('/').some(segment => !segment || segment === '.' || segment === '..')) {
+    throw new Error('Invalid skill resource path.');
+  }
+  const requestedUri = skillResourceUri(skill.name, resource);
+  const entry = skill.resources.find(item => item.uri === requestedUri);
+  if (!entry) throw new Error(`Unknown resource for ${skill.name}: ${resource}`);
+  const loaded = registry.readResource(entry.uri);
+  if (!loaded) throw new Error(`Unknown resource for ${skill.name}: ${resource}`);
+  return {
+    name: skill.name,
+    uri: loaded.uri,
+    revision: skill.skillRevision,
+    mimeType: loaded.mimeType,
+    digest: loaded.digest,
+    size: loaded.size,
+    ...(loaded.text !== undefined ? { text: loaded.text } : { blob: loaded.blob })
+  };
+}
+
+const TOOL_DEFINITIONS = [
+  {
+    name: 'skill_catalog',
+    description: 'Discover the current reusable skill catalog for clients that do not natively implement the MCP Skills extension. Returns compact metadata only; use load_skill for content.',
+    inputSchema: schema({
+      known_version: { type: 'string', description: 'Previously observed catalog version; matching versions return changed:false.' }
+    }),
+    outputSchema: structuredOutputSchema(),
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
+    handler: (args, context) => ok('skill_catalog', 'Read skill catalog', skillCatalog(args, context))
+  },
+  {
+    name: 'load_skill',
+    description: 'Load one reusable skill, or one explicitly listed supporting resource, for clients that do not natively implement the MCP Skills extension.',
+    inputSchema: schema({
+      name: { type: 'string', minLength: 1, description: 'Canonical skill name from skill_catalog.' },
+      resource: { type: 'string', description: 'Optional relative resource path from the selected skill manifest.' }
+    }, ['name']),
+    outputSchema: structuredOutputSchema(),
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
+    handler: (args, context) => ok('load_skill', 'Loaded skill content', loadSkill(args, context))
+  },
+  {
+    name: 'image_preview',
+    description: 'Load a bounded image preview from one explicit owned online device for visual inspection.',
+    inputSchema: schema({
+      device_id: { type: 'string', minLength: 1, description: 'Owned online device containing the image.' },
+      path: { type: 'string' },
+      file: { type: 'string' },
+      sourcePath: { type: 'string' },
+      embed: { type: 'boolean', default: true },
+      includeImage: { type: 'boolean', default: true },
+      includeData: { type: 'boolean', default: true },
+      maxBytes: { type: 'number', default: 8388608 }
+    }, ['device_id']),
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
+    handler: (args, context) => {
+      if (!context.callDeviceTool) throw new Error('Device execution routing is unavailable.');
+      return context.callDeviceTool('image_preview', args);
+    }
+  },
+  {
+    name: 'project_list',
+    description: 'List configured projects for one explicit owned online device. Local absolute paths stay hidden unless path exposure is explicitly enabled.',
+    inputSchema: schema({
+      device_id: { type: 'string', minLength: 1, description: 'Owned online device id whose configured projects should be listed.' },
+      query: { type: 'string', description: 'Optional project id or display-name filter.' },
+      cursor: { type: 'string', description: 'Opaque cursor returned by the previous page.' },
+      limit: { type: 'integer', minimum: 1, maximum: 200, default: 50 }
+    }, ['device_id']),
+    outputSchema: structuredOutputSchema(),
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
+    handler: (args, context) => ok('project_list', 'Listed projects', listProjects(context, args))
+  },
+  {
+    name: 'project_inspect',
+    description: 'Inspect one configured project through bounded summary, tree, Git, README, or package views. Use read_text_file for generic file bodies.',
+    inputSchema: schema({
+      device_id: { type: 'string', minLength: 1, description: 'Owned online device id associated with the project.' },
+      project_id: { type: 'string', description: 'Configured project id on that device.' },
+      view: { type: 'string', enum: [...PROJECT_INSPECTION_VIEWS] },
+      depth: { type: 'integer', minimum: 1, maximum: 10, default: 3 },
+      staged: { type: 'boolean', default: false },
+      cursor: { type: 'string', description: 'Opaque cursor returned by a bounded tree page.' },
+      limit: { type: 'integer', minimum: 1, maximum: 500, default: 200 }
+    }, ['device_id', 'project_id', 'view']),
+    outputSchema: structuredOutputSchema(),
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
+    handler: async (args, context) => ok(
+      'project_inspect',
+      `Inspected project ${args.project_id}`,
+      await inspectProject(context, { ...args, deviceId: args.device_id, projectId: args.project_id })
+    )
+  },
+  {
+    name: 'external_tool_search',
+    description: 'Search the bounded external MCP catalog without exposing full deferred schemas. Results are filtered by runtime profile.',
+    inputSchema: schema({
+      query: { type: 'string', description: 'Optional name/description search text.' },
+      server: { type: 'string', description: 'Optional external MCP server id.' },
+      lane: { type: 'string', enum: ['read', 'write'], description: 'Optional risk lane filter.' },
+      cursor: { type: 'string', description: 'Opaque cursor returned by the previous search page.' },
+      limit: { type: 'integer', minimum: 1, maximum: 50, default: 20 }
+    }),
+    outputSchema: structuredOutputSchema(),
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
+    handler: (args, context) => ok(
+      'external_tool_search',
+      'Searched external MCP tools',
+      requireExternalToolBroker(context).search(args, context.runtimeProfile)
+    )
+  },
+  {
+    name: 'external_tool_call_read',
+    description: 'Invoke one discovered external MCP tool only when its cached annotations place it in the read lane. Arguments are validated against the cached full input schema before forwarding.',
+    inputSchema: schema({
+      name: { type: 'string', minLength: 1 },
+      arguments: { type: 'object', default: {} }
+    }, ['name']),
+    annotations: { readOnlyHint: true, idempotentHint: true, destructiveHint: false, openWorldHint: false },
+    handler: (args, context) => requireExternalToolBroker(context).call('read', args, context.runtimeProfile)
+  },
+  {
+    name: 'external_tool_call_write',
+    description: 'Invoke one discovered external MCP tool only when its cached annotations place it in the write lane. Arguments are validated against the cached full input schema before forwarding.',
+    inputSchema: schema({
+      name: { type: 'string', minLength: 1 },
+      arguments: { type: 'object', default: {} }
+    }, ['name']),
+    annotations: { readOnlyHint: false, idempotentHint: false, destructiveHint: true, openWorldHint: false },
+    handler: (args, context) => requireExternalToolBroker(context).call('write', args, context.runtimeProfile)
+  }
+];
+
+const LOCAL_TOOLS = new Map(TOOL_DEFINITIONS.map(tool => [tool.name, tool]));
+
+export function isLocalCustomTool(name) {
+  return LOCAL_TOOLS.has(String(name || ''));
+}
+
+export function listCustomTools(_context = {}) {
+  return TOOL_DEFINITIONS.map(tool => applyToolRisk({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    ...(tool.outputSchema ? { outputSchema: tool.outputSchema } : {}),
+    annotations: { ...tool.annotations }
+  }));
+}
+
+export async function callCustomTool(name, args = {}, context = {}) {
+  const localName = String(name || '');
+  const tool = LOCAL_TOOLS.get(localName);
+  if (!tool) return fail(localName || 'unknown', 'UNKNOWN_TOOL', `Unknown local tool: ${name}`);
+  return await tool.handler(args || {}, context);
+}
+
+export const LOCAL_TOOL_NAMES = [...LOCAL_TOOLS.keys()];

package/control-plane/scripts/custom-tools/path-utils.mjs

@@ -0,0 +1,117 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const DEFAULT_EXCLUDES = ['node_modules/**', '.git/**', 'logs/**', 'packages/**', '_zip_temp/**'];
+
+export function normalizeWindowsPath(value) {
+  return String(value ?? '').trim().replace(/^['"]|['"]$/g, '').replace(/^\\\\\?\\/, '').replaceAll('/', path.sep);
+}
+
+export function getTrustedRoots(context = {}) {
+  const roots = Array.isArray(context.resolvedRepoRoots) && context.resolvedRepoRoots.length > 0
+    ? context.resolvedRepoRoots
+    : [context.resolvedRepoRoot || context.packageRoot || process.cwd()];
+  return [...new Set(roots.filter(Boolean).map(root => path.resolve(normalizeWindowsPath(root))))];
+}
+
+export function assertInsideTrustedRoots(targetPath, roots) {
+  const resolved = path.resolve(normalizeWindowsPath(targetPath));
+  const trustedRoots = getTrustedRoots({ resolvedRepoRoots: roots });
+  const root = trustedRoots.find(candidate => {
+    const relative = path.relative(candidate, resolved);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+  });
+  if (!root) {
+    const error = new Error(`Path is outside current workspace scope: ${targetPath}`);
+    error.code = 'PATH_OUT_OF_SCOPE';
+    error.details = { path: targetPath, trustedRoots };
+    throw error;
+  }
+  return { path: resolved, root };
+}
+
+export function resolveInsideTrustedRoots(inputPath, context = {}, options = {}) {
+  const roots = getTrustedRoots(context);
+  const base = options.workingDirectory
+    ? assertInsideTrustedRoots(options.workingDirectory, roots).path
+    : roots[0];
+  const raw = inputPath === undefined || inputPath === null || String(inputPath).trim() === '' ? base : normalizeWindowsPath(inputPath);
+  const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(base, raw);
+  const checked = assertInsideTrustedRoots(resolved, roots);
+  if (options.mustExist && !fs.existsSync(checked.path)) {
+    const error = new Error(`Path does not exist: ${checked.path}`);
+    error.code = 'PATH_NOT_FOUND';
+    error.details = { path: checked.path };
+    throw error;
+  }
+  return checked;
+}
+
+export function toRelativeFromRoot(targetPath, root) {
+  return path.relative(path.resolve(root), path.resolve(targetPath)).replaceAll(path.sep, '/');
+}
+
+export function defaultExcludePatterns(extra = [], options = {}) {
+  const base = DEFAULT_EXCLUDES.filter(pattern => !options.includeGit || pattern !== '.git/**');
+  return [...new Set([...base, ...extra])];
+}
+
+function escapeRegex(text) {
+  return String(text).replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+
+export function globToRegExp(pattern) {
+  const normalized = String(pattern || '**/*').replaceAll('\\', '/');
+  let out = '^';
+  for (let i = 0; i < normalized.length; i += 1) {
+    const ch = normalized[i];
+    const next = normalized[i + 1];
+    if (ch === '*' && next === '*') {
+      const after = normalized[i + 2];
+      if (after === '/') {
+        out += '(?:.*/)?';
+        i += 2;
+      } else {
+        out += '.*';
+        i += 1;
+      }
+    } else if (ch === '*') {
+      out += '[^/]*';
+    } else if (ch === '?') {
+      out += '[^/]';
+    } else {
+      out += escapeRegex(ch);
+    }
+  }
+  out += '$';
+  return new RegExp(out);
+}
+
+export function matchesAnyGlob(relativePath, patterns = ['**/*']) {
+  const value = String(relativePath).replaceAll('\\', '/');
+  return patterns.some(pattern => globToRegExp(pattern).test(value));
+}
+
+export function shouldExclude(relativePath, patterns = []) {
+  const value = String(relativePath).replaceAll('\\', '/');
+  return patterns.some(pattern => globToRegExp(pattern).test(value) || value === String(pattern).replace(/\/\*\*$/, ''));
+}
+
+export async function walkFiles(startPath, root, options = {}) {
+  const include = options.include?.length ? options.include : ['**/*'];
+  const exclude = options.exclude || defaultExcludePatterns();
+  const files = [];
+  async function visit(current) {
+    const stat = await fs.promises.stat(current);
+    const rel = toRelativeFromRoot(current, root);
+    if (rel && shouldExclude(rel, exclude)) return;
+    if (stat.isDirectory()) {
+      const entries = await fs.promises.readdir(current);
+      for (const entry of entries) await visit(path.join(current, entry));
+      return;
+    }
+    if (stat.isFile() && matchesAnyGlob(rel, include) && !shouldExclude(rel, exclude)) files.push(current);
+  }
+  await visit(startPath);
+  return files;
+}

package/control-plane/scripts/custom-tools/response-utils.mjs

@@ -0,0 +1,34 @@
+export function textJson(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+export function ok(tool, summary, data = {}) {
+  const value = { ok: true, tool: String(tool), summary, data };
+  return { ...textJson(value), structuredContent: value };
+}
+
+export function fail(tool, code, message, details = {}) {
+  return textJson({ ok: false, tool: String(tool), error: { code, message, details } });
+}
+
+export function redactSecret(value) {
+  const text = String(value ?? '');
+  if (text.length <= 8) return '****';
+  return `${text.slice(0, 4)}...${text.slice(-4)}`;
+}
+
+export function truncateText(text, maxBytes = 200000) {
+  const value = String(text ?? '');
+  const limit = Number(maxBytes);
+  if (!Number.isFinite(limit) || limit <= 0) return { text: '', truncated: value.length > 0 };
+  const bytes = Buffer.byteLength(value, 'utf8');
+  if (bytes <= limit) return { text: value, truncated: false };
+  let end = Math.min(value.length, limit);
+  while (Buffer.byteLength(value.slice(0, end), 'utf8') > limit && end > 0) end -= 1;
+  return { text: value.slice(0, end), truncated: true };
+}
+
+export function parseToolResult(result) {
+  const text = result?.content?.find?.(entry => entry?.type === 'text')?.text ?? '{}';
+  return JSON.parse(text);
+}