cloudflare-mcp-smart-proxy 1.5.10 → 1.5.17

package/connector-cli.js

@@ -303,6 +303,12 @@ function printInstallResult(result, { includeContent = false, includeSecrets = f
     if (Number.isInteger(result.activation.toolCount)) {
       console.error(`tools: ${result.activation.toolCount}`);
     }
+    if (result.activation.workspaceRoot) {
+      console.error(`workspace root: ${result.activation.workspaceRoot}`);
+    }
+    if (result.activation.workspaceId) {
+      console.error(`workspace: ${result.activation.workspaceId}`);
+    }
   }
   if (includeContent) {
     const apiKey = result.serverDefinition?.env?.CLOUDFLARE_MCP_API_KEY || '';

package/index.js

@@ -49,6 +49,7 @@ const WORKSPACE_ID = FIXED_PROJECT_CONTEXT
   : '';
 const DEVICE_IDENTITY_PATH = process.env.CLOUDMCP_DEVICE_IDENTITY_PATH || '';
 const AUTO_SYNC_PROFILE = (process.env.CLOUDMCP_AUTO_SYNC_PROFILE || 'true') !== 'false';
+const AUTO_SYNC_SKILLS = (process.env.CLOUDMCP_AUTO_SYNC_SKILLS || 'true') !== 'false';
 const AUTO_APPLY_BRAIN = (process.env.CLOUDMCP_AUTO_APPLY_BRAIN || 'true') !== 'false';
 const AUTO_REPORT_PROJECT_PROBE = (process.env.CLOUDMCP_AUTO_REPORT_PROJECT_PROBE || 'true') === 'true';
 const AUTO_GENERATE_CONTEXT_PACK = (process.env.CLOUDMCP_AUTO_GENERATE_CONTEXT_PACK || 'true') === 'true';
@@ -90,6 +91,7 @@ const router = new SmartRouter(
   () => connectorBridge.getScopeHeaders()
 );
 localTools.setCloudToolCaller((tool, params) => router.callCloudTool(tool, params));
+connectorBridge.setCloudToolCaller((tool, params, options) => router.callCloudTool(tool, params, options));
 
 // 创建 MCP 服务器
 const server = new Server(
@@ -287,6 +289,7 @@ async function main() {
       bridgeStatus = await connectorBridge.initialize({
         autoApplyBrain: AUTO_APPLY_BRAIN,
         autoSyncProfile: AUTO_SYNC_PROFILE,
+        autoSyncSkills: AUTO_SYNC_SKILLS,
         autoReportProjectProbe: AUTO_REPORT_PROJECT_PROBE,
         autoGenerateContextPack: AUTO_GENERATE_CONTEXT_PACK
       });
@@ -305,6 +308,10 @@ async function main() {
         console.error(`Brain applied for IDE: ${applyResult.ide} (${applyResult.applied?.length || 0} files written)`);
       }
       console.error(`Connector bridge auto probe: ${AUTO_REPORT_PROJECT_PROBE ? 'enabled' : 'disabled'}`);
+      const skillSync = bridgeStatus.state?.lastSkillSync;
+      if (skillSync) {
+        console.error(`Global Skill sync: ${skillSync.success ? `${skillSync.synchronized?.length || 0} synchronized` : `failed (${skillSync.error})`}`);
+      }
     } else {
       console.error('Connector bridge profile: not configured');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-mcp-smart-proxy",
-  "version": "1.5.10",
+  "version": "1.5.17",
   "description": "Smart proxy for Cloudflare MCP - routes tools to cloud or local execution",
   "repository": {
     "type": "git",

package/src/codex-app-server.js

@@ -3,9 +3,117 @@ import fs from 'node:fs';
 import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 
+function parseTomlValue(value) {
+  const normalized = String(value || '').trim();
+  if (!normalized) return '';
+  try {
+    return JSON.parse(normalized);
+  } catch {
+    return normalized.replace(/^"|"$/g, '');
+  }
+}
+
+export function readCodexMcpServerConfig(configPath, serverName = 'cloudmcp') {
+  const content = readText(configPath);
+  const serverSection = `[mcp_servers.${serverName}]`;
+  const envSection = `[mcp_servers.${serverName}.env]`;
+  let section = '';
+  const server = { env: {} };
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('[') && line.endsWith(']')) {
+      section = line;
+      continue;
+    }
+    if (section !== serverSection && section !== envSection) continue;
+    const separator = line.indexOf('=');
+    if (separator < 1) continue;
+    const key = line.slice(0, separator).trim();
+    const value = parseTomlValue(line.slice(separator + 1));
+    if (section === envSection) server.env[key] = String(value);
+    else server[key] = value;
+  }
+  if (!server.command) {
+    throw new Error(`Codex MCP server "${serverName}" is missing from ${configPath}`);
+  }
+  return {
+    command: String(server.command),
+    args: Array.isArray(server.args) ? server.args.map(String) : [],
+    env: server.env
+  };
+}
+
+export async function probeCodexMcpServer({
+  configPath,
+  serverName = 'cloudmcp',
+  cwd = process.cwd(),
+  timeoutMs = DEFAULT_TIMEOUT_MS
+} = {}) {
+  const configured = readCodexMcpServerConfig(configPath, serverName);
+  const transport = new StdioClientTransport({
+    command: configured.command,
+    args: configured.args,
+    cwd,
+    env: { ...process.env, ...configured.env },
+    stderr: 'pipe'
+  });
+  const client = new Client({ name: 'cloudmcp-reload-verifier', version: '1.0.0' });
+  const withTimeout = async (operation) => {
+    let timer;
+    try {
+      return await Promise.race([
+        operation,
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`Timed out probing MCP server "${serverName}"`)), timeoutMs);
+          timer.unref?.();
+        })
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  };
+  try {
+    await withTimeout(client.connect(transport));
+    const result = await withTimeout(client.listTools());
+    const tools = Array.isArray(result?.tools) ? result.tools : [];
+    if (tools.length === 0) {
+      throw new Error(`Codex MCP server "${serverName}" returned no tools during a fresh probe`);
+    }
+    const statusResult = await withTimeout(client.callTool({
+      name: 'connector_bridge_status',
+      arguments: {}
+    }));
+    const statusText = (Array.isArray(statusResult?.content) ? statusResult.content : [])
+      .find((entry) => entry?.type === 'text')?.text;
+    let status;
+    try {
+      status = JSON.parse(statusText || '{}');
+    } catch {
+      throw new Error(`Codex MCP server "${serverName}" returned an invalid connector workspace status`);
+    }
+    const expectedWorkspaceRoot = path.resolve(cwd);
+    const actualWorkspaceRoot = status?.workspaceRoot ? path.resolve(status.workspaceRoot) : '';
+    const workspaceId = String(status?.workspaceId || '').trim();
+    const workspaceResolution = String(status?.state?.workspaceResolution?.status || '').trim();
+    if (actualWorkspaceRoot !== expectedWorkspaceRoot || !workspaceId || workspaceResolution !== 'resolved') {
+      throw new Error(
+        `Codex MCP server "${serverName}" resolved the wrong project workspace: `
+        + `expected_root=${expectedWorkspaceRoot} actual_root=${actualWorkspaceRoot || 'missing'} `
+        + `workspace_id=${workspaceId || 'missing'} resolution=${workspaceResolution || 'missing'}`
+      );
+    }
+    return { toolCount: tools.length, workspaceId, workspaceRoot: actualWorkspaceRoot, workspaceResolution };
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
 function readText(filePath) {
   try {
     return fs.readFileSync(filePath, 'utf8');
@@ -333,6 +441,8 @@ export async function reloadCodexMcpServer({
   ),
   timeoutMs = DEFAULT_TIMEOUT_MS,
   rpcClient = null,
+  configPath = process.env.CODEX_SHARED_CONFIG_PATH || '',
+  toolProbe = null,
   runtimeValidator = validateCodexAppServerRuntime
 } = {}) {
   const resolvedSocketPath = resolveCodexAppServerSocket({
@@ -378,11 +488,28 @@ export async function reloadCodexMcpServer({
     if (toolCount === 0) {
       throw new Error(`Codex loaded MCP server "${serverName}" without any tools`);
     }
+    const probeResult = toolProbe
+      ? await toolProbe({ serverName, configPath, timeoutMs })
+      : (!rpcClient
+        ? await probeCodexMcpServer({
+            configPath: configPath || path.join(path.resolve(codexHome || path.join(homeDir, '.codex')), 'config.toml'),
+            serverName,
+            timeoutMs
+          })
+        : { toolCount });
+    if (Number(probeResult?.toolCount) !== toolCount) {
+      throw new Error(
+        `Codex MCP server "${serverName}" reload is stale: app_server_tools=${toolCount} fresh_probe_tools=${Number(probeResult?.toolCount) || 0}`
+      );
+    }
     return {
       status: 'ready',
       serverName,
       socketPath: resolvedSocketPath,
       toolCount,
+      workspaceId: probeResult?.workspaceId || null,
+      workspaceRoot: probeResult?.workspaceRoot || null,
+      workspaceResolution: probeResult?.workspaceResolution || null,
       authStatus: server.authStatus || server.auth_status || null
     };
   } finally {

package/src/connector-bridge.js

@@ -5,6 +5,7 @@ import { DeviceIdentity } from './device-identity.js';
 import { discoverProjectProbe } from './project-probe-discovery.js';
 import { detectIde, applyBrainSnapshot } from './ide-configurator.js';
 import { discoverProjectIdentity } from './project-identity.js';
+import { syncGlobalSkills } from './skill-sync.js';
 
 function normalizeString(value, fallback = '') {
   const normalized = typeof value === 'string' ? value.trim() : '';
@@ -56,8 +57,14 @@ export class ConnectorBridge {
       lastGeneratedContextPack: null,
       lastSyncAt: null,
       lastProjectProbeReportAt: null,
+      lastSkillSync: null,
       lastError: null
     };
+    this.cloudToolCaller = null;
+  }
+
+  setCloudToolCaller(caller) {
+    this.cloudToolCaller = typeof caller === 'function' ? caller : null;
   }
 
   isConfigured() {
@@ -112,6 +119,7 @@ export class ConnectorBridge {
   async initialize({
     autoSyncProfile = true,
     autoApplyBrain = true,
+    autoSyncSkills = true,
     autoReportProjectProbe = false,
     autoGenerateContextPack = false
   } = {}) {
@@ -119,6 +127,17 @@ export class ConnectorBridge {
       return this.getBridgeStatus();
     }
 
+    if (autoSyncSkills) {
+      try {
+        await this.syncSkills();
+      } catch (error) {
+        this.state.lastSkillSync = {
+          success: false,
+          error: error.message,
+          synchronized_at: Date.now()
+        };
+      }
+    }
     const workspaceResolution = await this.resolveCurrentWorkspace();
     if (!workspaceResolution.workspaceId) return this.getBridgeStatus();
     try {
@@ -237,6 +256,18 @@ export class ConnectorBridge {
     };
   }
 
+  async syncSkills(options = {}) {
+    if (typeof this.cloudToolCaller !== 'function') {
+      throw new Error('Cloud Skill synchronization is not configured');
+    }
+    const result = await syncGlobalSkills({
+      callCloudTool: this.cloudToolCaller,
+      ...options
+    });
+    this.state.lastSkillSync = result;
+    return result;
+  }
+
   async reportStatus({
     status = 'succeeded',
     summary = {},

package/src/local-memory-coordinator.js

@@ -31,6 +31,38 @@ function fingerprint(parts) {
   return createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 24);
 }
 
+function targetMarkerPath(directory, targetId) {
+  return path.join(directory, '.cloudmcp-targets', `${targetId}.json`);
+}
+
+function readTargetMarker(contract) {
+  const markerPath = targetMarkerPath(contract.directory, contract.targetId);
+  if (fs.existsSync(markerPath)) return readJson(markerPath);
+
+  const legacyMarkerPath = path.join(contract.directory, 'contract.json');
+  if (!fs.existsSync(legacyMarkerPath)) return null;
+  const legacyMarker = readJson(legacyMarkerPath);
+  return legacyMarker.targetId === contract.targetId ? legacyMarker : null;
+}
+
+function conflictEntryPath(directory, entry) {
+  const hash = String(entry.canonicalHash || '').replace(/[^A-Za-z0-9_-]/g, '-');
+  return path.join(directory, '.cloudmcp-conflicts', `${entry.id}.${hash}.json`);
+}
+
+function preserveLocalConflict(directory, entry) {
+  const conflictPath = conflictEntryPath(directory, entry);
+  if (fs.existsSync(conflictPath)) {
+    const preserved = assertMemoryEntryIntegrity(readJson(conflictPath));
+    if (canonicalMemoryJson(preserved) !== canonicalMemoryJson(entry)) {
+      throw new Error(`Local memory conflict evidence differs for ${entry.id}`);
+    }
+    return conflictPath;
+  }
+  writeJsonAtomically(conflictPath, entry);
+  return conflictPath;
+}
+
 function resolveConfiguredDirectory(directory, workspaceRoot) {
   const raw = typeof directory === 'string' ? directory.trim() : '';
   if (!raw) throw new Error('directory is required');
@@ -132,10 +164,11 @@ export class LocalMemoryCoordinator {
       cloudScopeIds,
       status: 'preparing'
     };
-    writeJsonAtomically(path.join(directory, 'contract.json'), preparingContract);
+    writeJsonAtomically(targetMarkerPath(directory, targetId), preparingContract);
     writeJsonAtomically(this.contractPath, { ...preparingContract, directory });
 
     let hydratedEntries = 0;
+    let reconciledConflicts = 0;
     for (const scopeId of cloudScopeIds) {
       let offset = 0;
       while (true) {
@@ -145,6 +178,10 @@ export class LocalMemoryCoordinator {
           limit: 50,
           offset
         });
+        if (loaded?.pagination?.complete !== true) {
+          const reason = loaded?.pagination?.incomplete_reason || 'pagination.complete was not true';
+          throw new Error(`Cloud memory hydration is incomplete for ${scopeId}: ${reason}`);
+        }
         const entries = Array.isArray(loaded?.entries) ? loaded.entries : [];
         for (const entry of entries) {
           assertMemoryEntryIntegrity(entry);
@@ -152,29 +189,33 @@ export class LocalMemoryCoordinator {
           if (fs.existsSync(entryPath)) {
             const current = assertMemoryEntryIntegrity(readJson(entryPath));
             if (current.canonicalHash !== entry.canonicalHash) {
-              throw new Error(`Local memory entry differs from CloudMCP: ${entry.id}`);
+              preserveLocalConflict(directory, current);
+              writeJsonAtomically(entryPath, entry);
+              reconciledConflicts += 1;
             }
           } else {
             writeJsonAtomically(entryPath, entry);
           }
           hydratedEntries += 1;
         }
-        if (!loaded?.pagination?.hasMore) break;
+        if (!loaded.pagination.hasMore) break;
+        if (entries.length === 0) {
+          throw new Error(`Cloud memory hydration returned an empty non-terminal page for ${scopeId}`);
+        }
         offset += entries.length;
-        if (entries.length === 0) break;
       }
     }
     const publicContract = { ...preparingContract, status: 'active' };
-    writeJsonAtomically(path.join(directory, 'contract.json'), publicContract);
+    writeJsonAtomically(targetMarkerPath(directory, targetId), publicContract);
     writeJsonAtomically(this.contractPath, { ...publicContract, directory });
-    return { configured: true, verified: true, contract: publicContract, hydratedEntries };
+    return { configured: true, verified: true, contract: publicContract, hydratedEntries, reconciledConflicts };
   }
 
   verify(params = {}) {
     const contract = this.getContract();
     if (!contract) throw new Error('Local memory target is not configured');
-    const marker = readJson(path.join(contract.directory, 'contract.json'));
-    if (marker.targetId !== contract.targetId || marker.schemaVersion !== 1 || marker.status !== 'active') {
+    const marker = readTargetMarker(contract);
+    if (!marker || marker.targetId !== contract.targetId || marker.schemaVersion !== 1 || marker.status !== 'active') {
       throw new Error('Local memory target contract verification failed');
     }
     if (params.memory_id) {

package/src/local-tools.js

@@ -70,6 +70,10 @@ export class LocalToolExecutor {
         if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
         return await this.connectorBridge.syncProfile();
 
+      case 'connector_sync_skills':
+        if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
+        return await this.connectorBridge.syncSkills(params || {});
+
       case 'connector_report_status':
         if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
         return await this.connectorBridge.reportStatus(params || {});
@@ -144,7 +148,7 @@ export class LocalToolExecutor {
       },
       {
         name: 'capture_memory',
-        description: 'Validate one governed memory and commit the same canonical JSON entry to the configured local target and CloudMCP scope.',
+        description: 'Validate one governed memory, reject secret-shaped values from every semantic field including tags, and commit the same canonical JSON entry to the configured local target and CloudMCP scope.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -462,6 +466,14 @@ export class LocalToolExecutor {
           properties: {}
         }
       },
+      {
+        name: 'connector_sync_skills',
+        description: 'Synchronize verified global CloudMCP Skills into the current user Codex Skill directory',
+        inputSchema: {
+          type: 'object',
+          properties: {}
+        }
+      },
       {
         name: 'connector_report_status',
         description: 'Report local connector apply status back to CloudMCP',

package/src/project-identity.js

@@ -61,12 +61,11 @@ export async function discoverProjectIdentity(workspaceRoot = process.cwd()) {
   ]);
   const aliases = Array.from(new Set([
     gitRemote ? `git:${gitRemote}` : '',
-    packageName ? `package:${packageName}` : '',
-    `repo:${normalizeAlias(repoName)}`
+    packageName ? `package:${packageName}` : ''
   ].filter(Boolean)));
 
   return {
-    canonicalId: aliases[0],
+    canonicalId: aliases[0] || '',
     aliases,
     repoName,
     gitRemote: gitRemote || null,

package/src/project-probe-discovery.js

@@ -1,5 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
+import { discoverProjectIdentity } from './project-identity.js';
 
 async function pathExists(target) {
   try {
@@ -67,6 +68,7 @@ export async function discoverProjectProbe({
 }) {
   const repoRoot = path.resolve(workspaceRoot || process.cwd());
   const repoName = path.basename(repoRoot);
+  const projectIdentity = await discoverProjectIdentity(repoRoot);
   const topLevel = await safeReadDir(repoRoot);
   const dirNames = topLevel.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   const fileNames = topLevel.filter((entry) => entry.isFile()).map((entry) => entry.name);
@@ -120,7 +122,7 @@ export async function discoverProjectProbe({
     workspaceId: workspaceId || null,
     repoName,
     repoRoot,
-    gitRemote: null,
+    gitRemote: projectIdentity.gitRemote,
     defaultBranch: 'main',
     languages,
     frameworkHints,

package/src/router.js

@@ -66,6 +66,7 @@ export class SmartRouter {
         'execute_shell_command',
         'connector_bridge_status',
         'connector_sync_profile',
+        'connector_sync_skills',
         'connector_report_status',
         'connector_discover_project_probe',
         'connector_report_project_probe',

package/src/skill-sync.js

@@ -0,0 +1,187 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const GLOBAL_SKILL_COLLECTION_ID = 'skill_collection:global';
+const PORTABLE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const PORTABLE_VERSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
+
+function normalizeString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortValue(value[key])]));
+}
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function assertPortableId(value, label) {
+  const normalized = normalizeString(value);
+  if (!PORTABLE_ID_PATTERN.test(normalized)) throw new Error(`${label} is not portable: ${normalized || '(empty)'}`);
+  return normalized;
+}
+
+function assertSafeRelativePath(value) {
+  const normalized = normalizeString(value);
+  if (!normalized || path.isAbsolute(normalized) || normalized.includes('\\')) {
+    throw new Error(`Skill file path is unsafe: ${normalized || '(empty)'}`);
+  }
+  if (normalized.split('/').some((part) => !part || part === '.' || part === '..')) {
+    throw new Error(`Skill file path is unsafe: ${normalized}`);
+  }
+  return normalized;
+}
+
+async function pathState(target) {
+  try {
+    const stat = await fs.lstat(target);
+    return { exists: true, stat };
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { exists: false, stat: null };
+    throw error;
+  }
+}
+
+function validateBundle(response) {
+  const bundle = response?.bundle;
+  const manifest = bundle?.manifest;
+  if (!manifest || manifest.schemaVersion !== 'cloudmcp.skill.v1') {
+    throw new Error('CloudMCP returned an unsupported Skill bundle');
+  }
+  const skillId = assertPortableId(manifest.skillId, 'skill_id');
+  const versionId = normalizeString(response?.version_id);
+  if (!PORTABLE_VERSION_ID_PATTERN.test(versionId)) throw new Error(`version_id is not portable: ${versionId || '(empty)'}`);
+  if (response?.skill_id !== skillId) throw new Error(`Skill identity mismatch for ${skillId}`);
+  if (!Array.isArray(manifest.files) || !Array.isArray(bundle.files)) {
+    throw new Error(`Skill bundle file inventory is missing for ${skillId}`);
+  }
+  const unsignedManifest = { ...manifest };
+  delete unsignedManifest.packageHash;
+  const expectedPackageHash = sha256(JSON.stringify(sortValue(unsignedManifest)));
+  if (manifest.packageHash !== expectedPackageHash) throw new Error(`Skill package hash mismatch for ${skillId}`);
+
+  const contentByPath = new Map(bundle.files.map((file) => [assertSafeRelativePath(file?.path), file?.content]));
+  const files = manifest.files.map((descriptor) => {
+    const filePath = assertSafeRelativePath(descriptor?.path);
+    const content = contentByPath.get(filePath);
+    if (typeof content !== 'string') throw new Error(`Skill file content is missing: ${skillId}/${filePath}`);
+    if (descriptor.executable === true || descriptor.role === 'script' || filePath.startsWith('scripts/')) {
+      throw new Error(`Executable Skill content is not supported: ${skillId}/${filePath}`);
+    }
+    if (!/^(?:text\/|application\/(?:json|yaml|x-yaml)$)/i.test(descriptor.mediaType || '')) {
+      throw new Error(`Binary Skill content is not supported: ${skillId}/${filePath}`);
+    }
+    if (Buffer.byteLength(content) !== descriptor.size || sha256(content) !== descriptor.sha256) {
+      throw new Error(`Skill file verification failed: ${skillId}/${filePath}`);
+    }
+    return { path: filePath, content };
+  });
+  if (!files.some((file) => file.path === 'SKILL.md')) throw new Error(`SKILL.md is missing for ${skillId}`);
+  if (contentByPath.size !== files.length) throw new Error(`Skill bundle inventory mismatch for ${skillId}`);
+  return { skillId, versionId, manifest, files };
+}
+
+async function writeVerifiedFile(target, content) {
+  await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+  const existing = await pathState(target);
+  if (existing.exists) {
+    if (!existing.stat.isFile()) throw new Error(`Managed Skill path is not a file: ${target}`);
+    const current = await fs.readFile(target, 'utf8');
+    if (current !== content) throw new Error(`Managed Skill cache conflict: ${target}`);
+    return false;
+  }
+  await fs.writeFile(target, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+  return true;
+}
+
+async function materializeVersion(cacheRoot, verified) {
+  const versionDir = path.join(cacheRoot, verified.skillId, verified.versionId);
+  await fs.mkdir(versionDir, { recursive: true, mode: 0o700 });
+  for (const file of verified.files) {
+    const target = path.resolve(versionDir, ...file.path.split('/'));
+    if (!target.startsWith(`${path.resolve(versionDir)}${path.sep}`)) throw new Error(`Skill path escaped cache: ${file.path}`);
+    await writeVerifiedFile(target, file.content);
+  }
+  await writeVerifiedFile(
+    path.join(versionDir, '.cloudmcp-manifest.json'),
+    `${JSON.stringify(verified.manifest, null, 2)}\n`
+  );
+  return versionDir;
+}
+
+async function activateVersion(skillsRoot, cacheRoot, skillId, versionDir) {
+  await fs.mkdir(skillsRoot, { recursive: true, mode: 0o700 });
+  const activePath = path.join(skillsRoot, skillId);
+  const existing = await pathState(activePath);
+  if (existing.exists) {
+    if (!existing.stat.isSymbolicLink()) {
+      throw new Error(`Refusing to overwrite unmanaged local Skill: ${activePath}`);
+    }
+    const currentTarget = path.resolve(path.dirname(activePath), await fs.readlink(activePath));
+    const managedRoot = `${path.resolve(cacheRoot)}${path.sep}`;
+    if (!currentTarget.startsWith(managedRoot)) {
+      throw new Error(`Refusing to replace unmanaged Skill symlink: ${activePath}`);
+    }
+    if (currentTarget === path.resolve(versionDir)) return { activePath, changed: false };
+    const historyRoot = path.join(cacheRoot, '.activation-history');
+    await fs.mkdir(historyRoot, { recursive: true, mode: 0o700 });
+    await fs.rename(activePath, path.join(historyRoot, `${skillId}.${Date.now()}.${process.pid}`));
+  }
+  await fs.symlink(versionDir, activePath, process.platform === 'win32' ? 'junction' : 'dir');
+  return { activePath, changed: true };
+}
+
+export async function syncGlobalSkills({
+  callCloudTool,
+  homeDir = os.homedir(),
+  cacheRoot = process.env.CLOUDMCP_SKILL_CACHE_ROOT || path.join(homeDir, '.cloudmcp', 'skills'),
+  skillsRoot = process.env.CLOUDMCP_USER_SKILLS_ROOT || path.join(homeDir, '.agents', 'skills')
+} = {}) {
+  if (typeof callCloudTool !== 'function') throw new Error('Cloud Skill tool caller is not configured');
+  const skills = [];
+  let cursor = '';
+  do {
+    const searchResult = await callCloudTool('search_skills', {
+      collection_id: GLOBAL_SKILL_COLLECTION_ID,
+      query: '',
+      limit: 100,
+      ...(cursor ? { cursor } : {})
+    }, { workspaceId: 'workspace.global' });
+    skills.push(...(Array.isArray(searchResult?.skills) ? searchResult.skills : []));
+    cursor = normalizeString(searchResult?.next_cursor);
+    if (searchResult?.complete !== false) cursor = '';
+    if (searchResult?.complete === false && !cursor) throw new Error('CloudMCP returned an incomplete Skill catalog without a cursor');
+  } while (cursor);
+  const synchronized = [];
+  for (const skill of skills) {
+    const skillId = assertPortableId(skill?.skill_id, 'skill_id');
+    const response = await callCloudTool('get_skill_bundle', {
+      skill_id: skillId,
+      version_id: skill.active_version_id
+    }, { workspaceId: 'workspace.global' });
+    const verified = validateBundle(response);
+    const versionDir = await materializeVersion(cacheRoot, verified);
+    const activation = await activateVersion(skillsRoot, cacheRoot, skillId, versionDir);
+    synchronized.push({
+      skill_id: skillId,
+      version_id: verified.versionId,
+      package_hash: verified.manifest.packageHash,
+      cache_path: versionDir,
+      active_path: activation.activePath,
+      changed: activation.changed
+    });
+  }
+  return {
+    success: true,
+    collection_id: GLOBAL_SKILL_COLLECTION_ID,
+    skills_root: skillsRoot,
+    synchronized,
+    synchronized_at: Date.now()
+  };
+}