@elliotding/ai-agent-mcp 0.2.21 → 0.2.23

package/dist/tools/sync-resources.js

@@ -62,6 +62,9 @@ const errors_1 = require("../types/errors");
 const index_js_1 = require("../telemetry/index.js");
 const index_js_2 = require("../prompts/index.js");
 const md_reference_expander_js_1 = require("../utils/md-reference-expander.js");
+const index_js_3 = require("../client-adapters/index.js");
+const policy_generator_js_1 = require("./policy-generator.js");
+const index_js_4 = require("../config/index.js");
 const downloadCache = new Map();
 function syncCacheKey(userToken, resourceId) {
     return `${userToken}::${resourceId}`;
@@ -139,6 +142,36 @@ function encodeForRender(filePath, rawContent, priorEncoding) {
         encoding: 'base64',
     };
 }
+function codexMcpUrl(url) {
+    // Codex consumes Streamable HTTP MCP endpoints. Server-side MCP resource
+    // packages may still ship Cursor/SSE URLs for backward compatibility.
+    return url.replace(/\/sse\/?$/, '/mcp');
+}
+function toCodexMcpTomlEntry(entry) {
+    const converted = { ...entry };
+    if (typeof converted.url === 'string') {
+        converted.url = codexMcpUrl(converted.url);
+    }
+    if (converted.headers && !converted.http_headers) {
+        converted.http_headers = converted.headers;
+        delete converted.headers;
+    }
+    // Codex infers HTTP MCP transport from `url`; keeping Cursor's `sse`
+    // transport marker in config.toml makes the generated config misleading.
+    if (converted.transport === 'sse' || converted.transport === 'streamable_http' || converted.transport === 'streamable-http') {
+        delete converted.transport;
+    }
+    return converted;
+}
+function queueCodexMcpTomlAction(localActions, tomlPath, serverName, entry) {
+    localActions.push({
+        action: 'merge_toml',
+        toml_path: tomlPath,
+        key: `mcp_servers.${serverName}`,
+        value: toCodexMcpTomlEntry(entry),
+        overwrite: false,
+    });
+}
 /**
  * Same as encodeForRender, but produces the field shape required by
  * CheckFileAction (`expected_content` + a sibling encoding hint stored as
@@ -152,6 +185,52 @@ function encodeForCheck(filePath, rawContent, priorEncoding) {
         expected_content_encoding: enc.encoding,
     };
 }
+async function loadPromptResourceFiles(resourceId, resourceName, resourceType, userToken) {
+    const downloadResult = await client_1.apiClient.downloadResource(resourceId, userToken);
+    if (downloadResult.files.length > 0) {
+        return downloadResult.files;
+    }
+    return multi_source_manager_1.multiSourceGitManager.readResourceFiles(resourceName, resourceType);
+}
+function getPrimaryPromptFile(sourceFiles, resourceName, isSkill) {
+    return isSkill
+        ? (sourceFiles.find((f) => path.basename(f.path) === 'SKILL.md') ??
+            sourceFiles.find((f) => f.path.endsWith('.md')) ??
+            sourceFiles[0])
+        : (sourceFiles.find((f) => path.basename(f.path).replace(/\.md$/, '') === resourceName) ??
+            sourceFiles.find((f) => f.path.endsWith('.md')) ??
+            sourceFiles[0]);
+}
+function getLocalScriptFiles(sourceFiles) {
+    return sourceFiles.filter(f => !f.path.endsWith('.md') &&
+        f.path !== 'SKILL.md' &&
+        !f.path.endsWith('/SKILL.md'));
+}
+function queueComplexSkillCheckActions(localActions, clientAdapter, resourceId, resourceName, scriptFiles, manifestContent) {
+    if (scriptFiles.length === 0) {
+        return 0;
+    }
+    const skillDir = clientAdapter.getSkillDir(resourceName);
+    for (const scriptFile of scriptFiles) {
+        localActions.push({
+            action: 'check_file',
+            path: `${skillDir}/${scriptFile.path}`,
+            ...encodeForCheck(scriptFile.path, scriptFile.content, scriptFile.encoding),
+            resource_id: resourceId,
+            resource_name: resourceName,
+            resource_type: 'skill',
+        });
+    }
+    localActions.push({
+        action: 'check_file',
+        path: `${clientAdapter.getManifestDir()}/${resourceName}.md`,
+        ...encodeForCheck('SKILL.md', manifestContent),
+        resource_id: resourceId,
+        resource_name: resourceName,
+        resource_type: 'skill',
+    });
+    return scriptFiles.length + 1;
+}
 async function syncResources(params) {
     const startTime = Date.now();
     const typedParams = params;
@@ -171,6 +250,13 @@ async function syncResources(params) {
             ? new Set(typedParams.resource_ids)
             : null;
         const confirmedFullSync = typedParams._confirmed_full_sync === true;
+        // Resolve client adapter: prefer the caller-supplied agent_profile, fall
+        // back to the server-wide config.agentProfile (set via CSP_AGENT_PROFILE).
+        const resolvedProfile = typedParams.agent_profile ?? index_js_4.config.agentProfile ?? 'cursor';
+        const clientAdapter = index_js_3.adapterRegistry.get(resolvedProfile);
+        // Collect per-rule content for Codex policy aggregation (stage 4).
+        // Each entry is raw rule markdown to be merged into csp-routing-policy.md.
+        const codexRuleContents = [];
         (0, logger_1.logToolStep)('sync_resources', 'Parameters validated', {
             mode,
             scope,
@@ -208,16 +294,21 @@ async function syncResources(params) {
         (0, logger_1.logToolStep)('sync_resources', 'Step 1: Fetching subscriptions from API', { scope, types });
         const t1 = Date.now();
         const allSubscriptions = await client_1.apiClient.getSubscriptions({ types }, userToken);
+        const visibleAllSubscriptions = {
+            ...allSubscriptions,
+            subscriptions: index_js_2.promptManager.filterSuppressedSubscriptions(userToken ?? '', allSubscriptions.subscriptions),
+        };
+        visibleAllSubscriptions.total = visibleAllSubscriptions.subscriptions.length;
         // Apply resource_ids filter if provided — only process the specified resources.
         // This is done client-side: the subscription list API has no resource_ids filter,
         // but downloadResource(id) is already a single-resource endpoint so per-resource
         // processing is efficient regardless.
         const subscriptions = resourceIds
             ? {
-                total: allSubscriptions.subscriptions.filter(s => resourceIds.has(s.id)).length,
-                subscriptions: allSubscriptions.subscriptions.filter(s => resourceIds.has(s.id)),
+                total: visibleAllSubscriptions.subscriptions.filter(s => resourceIds.has(s.id)).length,
+                subscriptions: visibleAllSubscriptions.subscriptions.filter(s => resourceIds.has(s.id)),
             }
-            : allSubscriptions;
+            : visibleAllSubscriptions;
         (0, logger_1.logToolStep)('sync_resources', 'Subscriptions fetched', {
             totalFromApi: allSubscriptions.total,
             afterFilter: subscriptions.total,
@@ -296,47 +387,34 @@ async function syncResources(params) {
                         };
                         const isRegistered = index_js_2.promptManager.has(index_js_2.promptManager.buildPromptName(meta), userToken ?? '');
                         if (isRegistered) {
-                            tally.cached++;
-                            details.push({ id: sub.id, name: sub.name, action: 'cached', version: resourceVersion });
-                            // ── ADDITIONAL: Check if skill has local scripts in .csp-ai-agent ────
-                            // Complex skills store scripts in ~/.csp-ai-agent/skills/<name>/
-                            // We need to verify those are also up-to-date
+                            let checkAction = 'cached';
+                            // Complex skills need local script and manifest checks in the
+                            // active client subtree.  Use the same API/Git source-file path
+                            // as incremental sync; Git metadata alone misses API-backed
+                            // skills such as zoom-build and can falsely report "cached".
                             if (sub.type === 'skill') {
                                 try {
-                                    const metadata = await multi_source_manager_1.multiSourceGitManager.scanResourceMetadata(sub.name, sub.type);
-                                    if (metadata.has_scripts && metadata.script_files) {
-                                        (0, logger_1.logToolStep)('sync_resources', 'Skill has scripts — generating script check actions', {
+                                    const sourceFiles = await loadPromptResourceFiles(sub.id, sub.name, sub.type, userToken);
+                                    const scriptFiles = getLocalScriptFiles(sourceFiles);
+                                    const primaryFile = getPrimaryPromptFile(sourceFiles, sub.name, true);
+                                    const actionCount = queueComplexSkillCheckActions(localActions, clientAdapter, sub.id, sub.name, scriptFiles, primaryFile?.content ?? '');
+                                    if (actionCount > 0) {
+                                        checkAction = 'failed';
+                                        (0, logger_1.logToolStep)('sync_resources', 'Complex skill check actions queued for AI Agent', {
                                             resourceId: sub.id,
-                                            scriptCount: metadata.script_files.length,
-                                        });
-                                        // Check each script file in .csp-ai-agent
-                                        const skillDir = `${(0, cursor_paths_1.getCspAgentDirForClient)('skills')}/${sub.name}`;
-                                        for (const scriptFile of metadata.script_files) {
-                                            localActions.push({
-                                                action: 'check_file',
-                                                path: `${skillDir}/${scriptFile.relative_path}`,
-                                                ...encodeForCheck(scriptFile.relative_path, scriptFile.content, scriptFile.encoding),
-                                                resource_id: sub.id,
-                                                resource_name: sub.name,
-                                                resource_type: sub.type,
-                                            });
-                                        }
-                                        // Also check the manifest file
-                                        const proxyScript = metadata.script_files[0];
-                                        localActions.push({
-                                            action: 'check_file',
-                                            path: `${(0, cursor_paths_1.getCspAgentRootDirForClient)()}/.manifests/${sub.name}.md`,
-                                            ...encodeForCheck(proxyScript?.relative_path ?? '', proxyScript?.content ?? '', proxyScript?.encoding), // Use first script as proxy
-                                            resource_id: sub.id,
-                                            resource_name: sub.name,
-                                            resource_type: sub.type,
+                                            scriptCount: scriptFiles.length,
+                                            manifestPath: `${clientAdapter.getManifestDir()}/${sub.name}.md`,
+                                            actionCount,
                                         });
                                     }
                                 }
-                                catch {
-                                    // No scripts or scan failed — skip script check
+                                catch (err) {
+                                    checkAction = 'failed';
+                                    logger_1.logger.warn({ resourceId: sub.id, resourceName: sub.name, error: err.message }, 'Failed to prepare complex skill local checks');
                                 }
                             }
+                            tally[checkAction]++;
+                            details.push({ id: sub.id, name: sub.name, action: checkAction, version: resourceVersion });
                         }
                         else {
                             tally.failed++;
@@ -427,12 +505,14 @@ async function syncResources(params) {
                                     });
                                 }
                             }
-                            // Placeholder: AI will update this after executing check actions
-                            tally.cached++;
+                            // Server cannot access the user's local filesystem. Once
+                            // check_file actions are queued, report the resource as failed
+                            // until the Agent executes those checks and observes matches.
+                            tally.failed++;
                             details.push({
                                 id: sub.id,
                                 name: sub.name,
-                                action: 'cached',
+                                action: 'failed',
                                 version: resourceVersion,
                             });
                             (0, logger_1.logToolStep)('sync_resources', 'Check actions queued for AI Agent', {
@@ -484,13 +564,7 @@ async function syncResources(params) {
                         //   - command: prefer the file whose name matches the resource name
                         //   - fallback: first .md file, then first file of any type
                         const isSkill = sub.type === 'skill';
-                        const primaryFile = isSkill
-                            ? (sourceFiles.find((f) => path.basename(f.path) === 'SKILL.md') ??
-                                sourceFiles.find((f) => f.path.endsWith('.md')) ??
-                                sourceFiles[0])
-                            : (sourceFiles.find((f) => path.basename(f.path).replace(/\.md$/, '') === sub.name) ??
-                                sourceFiles.find((f) => f.path.endsWith('.md')) ??
-                                sourceFiles[0]);
+                        const primaryFile = getPrimaryPromptFile(sourceFiles, sub.name, isSkill);
                         const rawContent = primaryFile?.content ?? '';
                         // Extract description from frontmatter (---\ndescription: ...\n---)
                         // falling back to the subscription's description field or resource name.
@@ -527,9 +601,7 @@ async function syncResources(params) {
                         // WHY: zoom-build and other complex skills are NOT in git but ARE in API response
                         try {
                             // Filter out markdown files from sourceFiles to identify scripts
-                            const scriptFiles = sourceFiles.filter(f => !f.path.endsWith('.md') &&
-                                f.path !== 'SKILL.md' &&
-                                !f.path.endsWith('/SKILL.md'));
+                            const scriptFiles = getLocalScriptFiles(sourceFiles);
                             if (scriptFiles.length > 0) {
                                 // Complex skill detected via API download
                                 (0, logger_1.logToolStep)('sync_resources', 'Complex skill detected (via API) — generating local actions', {
@@ -537,10 +609,15 @@ async function syncResources(params) {
                                     scriptCount: scriptFiles.length,
                                     source: 'API',
                                 });
-                                // Use isolated directory for complex skills (not ~/.cursor/skills/)
-                                // SKILL.md is NOT downloaded — only scripts are cached locally
-                                // This prevents Cursor from auto-discovering the skill while enabling script execution
-                                const skillDir = `${(0, cursor_paths_1.getCspAgentDirForClient)('skills')}/${sub.name}`;
+                                // Use client-adapter-resolved directory so Cursor and Codex each get
+                                // their own isolated subtree:
+                                //   Cursor → ~/.csp-ai-agent/skills/<name>/
+                                //   Codex  → ~/.csp-ai-agent/codex/skills/<name>/
+                                // SKILL.md is NOT downloaded — only scripts are cached locally.
+                                // This prevents the client from auto-discovering the skill while
+                                // enabling script execution.
+                                const skillDir = clientAdapter.getSkillDir(sub.name);
+                                const manifestPath = `${clientAdapter.getManifestDir()}/${sub.name}.md`;
                                 // Generate write_file actions for script files ONLY (exclude SKILL.md)
                                 // First script file carries is_skill_manifest marker for atomic update check
                                 // 1. First script file (with manifest check marker)
@@ -553,9 +630,10 @@ async function syncResources(params) {
                                         action: 'write_file',
                                         path: `${skillDir}/${firstScript.path}`,
                                         ...encodeForRender(firstScript.path, firstScript.content),
-                                        mode: firstScript.path.includes('/scripts/') ? '0755' : undefined,
+                                        mode: firstScript.path.includes('scripts/') ? '0755' : undefined,
                                         // Atomic update marker: client checks manifest FIRST
                                         is_skill_manifest: true,
+                                        manifest_path: manifestPath,
                                         // SKILL.md content for version comparison (stored separately in .manifests/)
                                         skill_manifest_content: Buffer.from(rawContent, "utf8").toString("base64"),
                                     });
@@ -569,7 +647,7 @@ async function syncResources(params) {
                                         action: 'write_file',
                                         path: `${skillDir}/${scriptFile.path}`,
                                         ...encodeForRender(scriptFile.path, scriptFile.content),
-                                        mode: scriptFile.path.includes('/scripts/') ? '0755' : undefined,
+                                        mode: scriptFile.path.includes('scripts/') ? '0755' : undefined,
                                     });
                                 }
                                 (0, logger_1.logToolStep)('sync_resources', 'Script files added to local_actions_required (SKILL.md excluded)', {
@@ -588,7 +666,9 @@ async function syncResources(params) {
                                         scriptCount: metadata.script_files.length,
                                         source: 'Git',
                                     });
-                                    const skillDir = `${(0, cursor_paths_1.getCspAgentDirForClient)('skills')}/${sub.name}`;
+                                    // Use client-adapter-resolved directory (Cursor vs Codex subtree).
+                                    const skillDir = clientAdapter.getSkillDir(sub.name);
+                                    const manifestPath = `${clientAdapter.getManifestDir()}/${sub.name}.md`;
                                     if (metadata.script_files.length > 0) {
                                         const firstScript = metadata.script_files[0];
                                         if (!firstScript) {
@@ -599,8 +679,9 @@ async function syncResources(params) {
                                                 action: 'write_file',
                                                 path: `${skillDir}/${firstScript.relative_path}`,
                                                 ...encodeForRender(firstScript.relative_path, firstScript.content, firstScript.encoding),
-                                                mode: firstScript.mode,
+                                                mode: firstScript.mode ?? (firstScript.relative_path.includes('scripts/') ? '0755' : undefined),
                                                 is_skill_manifest: true,
+                                                manifest_path: manifestPath,
                                                 skill_manifest_content: Buffer.from(rawContent, "utf8").toString("base64"),
                                             });
                                         }
@@ -612,7 +693,7 @@ async function syncResources(params) {
                                                 action: 'write_file',
                                                 path: `${skillDir}/${scriptFile.relative_path}`,
                                                 ...encodeForRender(scriptFile.relative_path, scriptFile.content, scriptFile.encoding),
-                                                mode: scriptFile.mode,
+                                                mode: scriptFile.mode ?? (scriptFile.relative_path.includes('scripts/') ? '0755' : undefined),
                                             });
                                         }
                                     }
@@ -736,8 +817,10 @@ async function syncResources(params) {
                 // not on this (possibly remote Linux) server.
                 if (sub.type === 'mcp') {
                     const mcpConfigFile = resourceFiles.find((f) => path.basename(f.path) === 'mcp-config.json');
-                    // ~/.cursor/mcp.json on the user's machine
-                    const mcpJsonPath = `${(0, cursor_paths_1.getCursorRootDirForClient)()}/mcp.json`;
+                    // Config path differs per client: mcp.json (Cursor) vs config.toml (Codex)
+                    const mcpJsonPath = resolvedProfile === 'codex'
+                        ? clientAdapter.getMcpConfigPath() // ~/.codex/config.toml
+                        : `${(0, cursor_paths_1.getCursorRootDirForClient)()}/mcp.json`;
                     // ── Optimization: skip if already configured (incremental mode only) ────
                     // In incremental mode, if the AI Agent reports this MCP server is already
                     // in ~/.cursor/mcp.json, skip downloading and generating write_file actions.
@@ -785,7 +868,33 @@ async function syncResources(params) {
                         catch {
                             logger_1.logger.warn({ resourceId: sub.id, resourceName: sub.name }, 'sync_resources: failed to parse mcp-config.json — treating as empty config');
                         }
-                        if (typeof cfg['command'] === 'string') {
+                        if (resolvedProfile === 'codex') {
+                            // ── Codex MCP: inject server entry into config.toml via merge_toml ──
+                            // The Codex CLI reads MCP server configuration from ~/.codex/config.toml.
+                            // Format A becomes [mcp_servers.<name>]. Format B emits one
+                            // table per remote server entry. URL entries are normalised from
+                            // Cursor/SSE (`/sse`) to Codex Streamable HTTP (`/mcp`).
+                            const tomlPath = clientAdapter.getMcpConfigPath();
+                            const queuedServers = [];
+                            if (typeof cfg['command'] === 'string') {
+                                const serverName = cfg['name'] ?? sub.name;
+                                queueCodexMcpTomlAction(localActions, tomlPath, serverName, cfg);
+                                queuedServers.push(serverName);
+                            }
+                            else {
+                                for (const [serverName, entry] of Object.entries(cfg)) {
+                                    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+                                        logger_1.logger.warn({ resourceId: sub.id, resourceName: sub.name, serverName }, 'sync_resources: skipping invalid Codex MCP config entry');
+                                        continue;
+                                    }
+                                    queueCodexMcpTomlAction(localActions, tomlPath, serverName, entry);
+                                    queuedServers.push(serverName);
+                                }
+                            }
+                            logger_1.logger.info({ resourceId: sub.id, resourceName: sub.name, serverKeys: queuedServers, tomlPath, profile: 'codex' }, 'sync_resources: Codex MCP — merge_toml action queued');
+                            (0, logger_1.logToolStep)('sync_resources', 'Codex MCP: merge_toml queued', { resourceId: sub.id, serverKeys: queuedServers });
+                        }
+                        else if (typeof cfg['command'] === 'string') {
                             // ── Format A: local executable ──────────────────────────────────
                             const installDir = `${(0, cursor_paths_1.getCursorTypeDirForClient)('mcp')}/${sub.name}`;
                             const writeActions = [];
@@ -867,43 +976,51 @@ async function syncResources(params) {
                     }
                     else {
                         // No mcp-config.json: heuristic fallback
-                        const installDir = `${(0, cursor_paths_1.getCursorTypeDirForClient)('mcp')}/${sub.name}`;
-                        const writeActions = [];
-                        for (const file of resourceFiles) {
-                            const normalised = path.normalize(file.path);
-                            if (normalised.startsWith('..'))
-                                continue;
-                            const fileDest = `${installDir}/${normalised}`;
+                        if (resolvedProfile === 'codex') {
+                            // Codex: emit a bare merge_toml with minimal entry
+                            const tomlPath = clientAdapter.getMcpConfigPath();
+                            queueCodexMcpTomlAction(localActions, tomlPath, sub.name, { command: 'node', args: [] });
+                            logger_1.logger.info({ resourceId: sub.id, resourceName: sub.name, tomlPath, profile: 'codex' }, 'sync_resources: Codex MCP heuristic — merge_toml action queued (no mcp-config.json)');
+                        }
+                        else {
+                            const installDir = `${(0, cursor_paths_1.getCursorTypeDirForClient)('mcp')}/${sub.name}`;
+                            const writeActions = [];
+                            for (const file of resourceFiles) {
+                                const normalised = path.normalize(file.path);
+                                if (normalised.startsWith('..'))
+                                    continue;
+                                const fileDest = `${installDir}/${normalised}`;
+                                localActions.push({
+                                    action: 'write_file',
+                                    path: fileDest,
+                                    ...encodeForRender(file.path, file.content),
+                                });
+                                writeActions.push(fileDest);
+                            }
+                            const jsEntry = resourceFiles.find((f) => f.path.endsWith('.js'));
+                            const pyEntry = resourceFiles.find((f) => f.path.endsWith('.py'));
+                            const entryFile = jsEntry ?? pyEntry ?? resourceFiles[0];
+                            const cmd = jsEntry ? 'node' : 'python3';
+                            const entryPath = `${installDir}/${entryFile?.path ?? ''}`;
                             localActions.push({
-                                action: 'write_file',
-                                path: fileDest,
-                                ...encodeForRender(file.path, file.content),
+                                action: 'merge_mcp_json',
+                                mcp_json_path: mcpJsonPath,
+                                server_name: sub.name,
+                                entry: { command: cmd, args: [entryPath] },
+                                skip_if_exists: true,
                             });
-                            writeActions.push(fileDest);
+                            logger_1.logger.info({
+                                resourceId: sub.id,
+                                resourceName: sub.name,
+                                format: 'heuristic',
+                                installDir,
+                                mcpJsonPath,
+                                cmd,
+                                entryPath,
+                                writeFiles: writeActions,
+                            }, 'sync_resources: MCP heuristic fallback — write_file + merge_mcp_json actions queued');
+                            (0, logger_1.logToolStep)('sync_resources', 'MCP heuristic fallback: write_file + merge_mcp_json queued', { resourceId: sub.id });
                         }
-                        const jsEntry = resourceFiles.find((f) => f.path.endsWith('.js'));
-                        const pyEntry = resourceFiles.find((f) => f.path.endsWith('.py'));
-                        const entryFile = jsEntry ?? pyEntry ?? resourceFiles[0];
-                        const cmd = jsEntry ? 'node' : 'python3';
-                        const entryPath = `${installDir}/${entryFile?.path ?? ''}`;
-                        localActions.push({
-                            action: 'merge_mcp_json',
-                            mcp_json_path: mcpJsonPath,
-                            server_name: sub.name,
-                            entry: { command: cmd, args: [entryPath] },
-                            skip_if_exists: true,
-                        });
-                        logger_1.logger.info({
-                            resourceId: sub.id,
-                            resourceName: sub.name,
-                            format: 'heuristic',
-                            installDir,
-                            mcpJsonPath,
-                            cmd,
-                            entryPath,
-                            writeFiles: writeActions,
-                        }, 'sync_resources: MCP heuristic fallback — write_file + merge_mcp_json actions queued');
-                        (0, logger_1.logToolStep)('sync_resources', 'MCP heuristic fallback: write_file + merge_mcp_json queued', { resourceId: sub.id });
                     }
                     tally.synced++;
                     details.push({ id: sub.id, name: sub.name, action: 'synced', version: resourceVersion });
@@ -917,11 +1034,25 @@ async function syncResources(params) {
                 // or has different content, the AI writes it unconditionally, which also
                 // recovers files that were accidentally deleted by the user.
                 //
-                // DUAL-LAYER STRATEGY (v1.6):
+                // DUAL-LAYER STRATEGY (v1.6, Cursor only):
                 //   - scope='global'    → write to ~/.cursor/rules/ only (macOS support)
                 //   - scope='workspace' → write to ${WORKSPACE}/.cursor/rules/ only (Windows support)
                 //   - scope='all'       → write to BOTH locations (maximum compatibility)
+                //
+                // CODEX STRATEGY: rules are aggregated into csp-routing-policy.md and injected
+                // via developer_instructions in config.toml (no .mdc files written to disk).
                 if (sub.type === 'rule') {
+                    if (resolvedProfile === 'codex') {
+                        // Collect rule content for policy aggregation; no individual file actions.
+                        for (const file of resourceFiles) {
+                            codexRuleContents.push({ name: sub.name, content: file.content });
+                        }
+                        logger_1.logger.info({ resourceId: sub.id, resourceName: sub.name, profile: 'codex' }, 'sync_resources: Rule collected for Codex policy aggregation');
+                        tally.synced++;
+                        details.push({ id: sub.id, name: sub.name, action: 'synced', version: resourceVersion });
+                        continue;
+                    }
+                    // ── Cursor: dual-layer .mdc file strategy (unchanged) ──────────────
                     const writeActions = [];
                     // Determine target directories based on scope parameter
                     const targetDirs = [];
@@ -1000,17 +1131,71 @@ async function syncResources(params) {
         else if (resourceIds) {
             logger_1.logger.info({ resourceIdsFilter: [...resourceIds], expectedPromptCount: expectedPromptNames.size }, 'sync_resources: skipping pruneStalePrompts — resource_ids filter active (partial sync)');
         }
-        // ── Step 5: Health score ───────────────────────────────────────────────
+        // ── Step 5 (Codex): Aggregate collected rules into policy actions ──────
+        // If any rule content was collected during this sync run, materialise the
+        // csp-routing-policy.md file and emit a merge_toml action to inject it
+        // into developer_instructions in ~/.codex/config.toml.
+        let restartRequired = false;
+        let restartHint;
+        if (resolvedProfile === 'codex' && codexRuleContents.length > 0) {
+            try {
+                const policyStrategy = clientAdapter.getPolicyStrategy();
+                const policyContent = (0, policy_generator_js_1.generatePolicyContent)(codexRuleContents);
+                const policyFile = policyStrategy.policyFile ?? '~/.csp-ai-agent/codex/csp-routing-policy.md';
+                const tomlPath = policyStrategy.configTomlPath ?? '~/.codex/config.toml';
+                const tomlKey = policyStrategy.configTomlKey ?? 'developer_instructions';
+                // 1. Write the policy markdown file
+                localActions.push({
+                    action: 'write_file',
+                    path: policyFile,
+                    content: policyContent,
+                    encoding: 'utf8',
+                });
+                // 2. Inject the policy file reference into developer_instructions.
+                // overwrite: false keeps this action idempotent after the first
+                // successful setup, so restart hints do not force a re-apply loop.
+                localActions.push({
+                    action: 'merge_toml',
+                    toml_path: tomlPath,
+                    key: tomlKey,
+                    value: `Please read and follow the CSP routing policy at: ${policyFile}`,
+                    overwrite: false,
+                });
+                restartRequired = true;
+                restartHint = `CSP routing policy has been updated. Please restart Codex for the policy to take effect: codex`;
+                logger_1.logger.info({ profile: 'codex', policyFile, tomlPath, ruleCount: codexRuleContents.length }, 'sync_resources: Codex policy materialised — merge_toml action queued');
+            }
+            catch (err) {
+                logger_1.logger.error({ error: err instanceof Error ? err.message : String(err) }, 'sync_resources: Failed to generate Codex policy');
+            }
+        }
+        // ── Step 6: Health score ───────────────────────────────────────────────
         const healthScore = tally.total > 0
             ? Math.round(((tally.synced + tally.cached + tally.skipped) / tally.total) * 100)
             : 100;
+        const pendingSetup = localActions.flatMap((action) => {
+            if (action.action !== 'merge_mcp_json' || !action.missing_env || action.missing_env.length === 0) {
+                return [];
+            }
+            return [{
+                    server_name: action.server_name,
+                    mcp_json_path: action.mcp_json_path,
+                    missing_env: action.missing_env,
+                    command_needs_verification: typeof action.entry.command === 'string',
+                    command: typeof action.entry.command === 'string' ? action.entry.command : '',
+                    setup_hint: action.setup_hint ?? `Fill in env vars for MCP server "${action.server_name}".`,
+                    ...(action.setup_doc ? { setup_doc: action.setup_doc } : {}),
+                }];
+        });
         const result = {
             mode,
             health_score: healthScore,
             summary: tally,
             details,
             ...(skippedResources.length > 0 ? { skipped_resources: skippedResources } : {}),
+            ...(pendingSetup.length > 0 ? { pending_setup: pendingSetup } : {}),
             ...(localActions.length > 0 ? { local_actions_required: localActions } : {}),
+            ...(restartRequired ? { restart_required: true, restart_hint: restartHint } : {}),
         };
         const duration = Date.now() - startTime;
         (0, logger_1.logToolCall)('sync_resources', 'user-id', params, duration);
@@ -1134,7 +1319,7 @@ exports.syncResourcesTool = {
         'For write_file actions: ' +
         '  SPECIAL HANDLING FOR COMPLEX SKILLS (when action has `is_skill_manifest: true`): ' +
         '    (1) This action is the FIRST script file — check skill version using manifest FIRST. ' +
-        '    (2) Read manifest file at {CSP_AGENT_ROOT}/.manifests/<skill-name>.md (if exists). ' +
+        '    (2) Read manifest file at action.manifest_path when present; otherwise read {CSP_AGENT_ROOT}/.manifests/<skill-name>.md. ' +
         '        Where {CSP_AGENT_ROOT} is a SIBLING of {CURSOR_ROOT} (same parent directory). ' +
         '    (3) action.skill_manifest_content is ALWAYS base64-encoded — first decode it: ' +
         '        decodedManifest = Buffer.from(action.skill_manifest_content, "base64").toString("utf8") ' +
@@ -1143,7 +1328,7 @@ exports.syncResourcesTool = {
         '    (5) If different or manifest missing: ' +
         '        - PROCEED with this action and all subsequent write_file actions for this skill. ' +
         '        - After writing all script files, write decodedManifest (the UTF-8 form, NOT the raw base64 string) ' +
-        '          to {CSP_AGENT_ROOT}/.manifests/<skill-name>.md ' +
+        '          to action.manifest_path when present, otherwise {CSP_AGENT_ROOT}/.manifests/<skill-name>.md ' +
         '    (6) NOTE: SKILL.md is NEVER written to the skills directory (only to .manifests/) to prevent Cursor auto-discovery. ' +
         '  GENERAL HANDLING (when action has NO `is_skill_manifest` marker): ' +
         '    (1) Read the existing file at `path` (if it exists) using fs.readFile() or equivalent. ' +