@elliotding/ai-agent-mcp 0.2.20 → 0.2.22

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}`;
@@ -85,6 +88,73 @@ function extractFrontmatterDescription(content) {
     }
     return undefined;
 }
+// ── Render-safety: base64-encode non-markdown file content ─────────────────
+//
+// Background: shipping raw shell / script bodies inside `content` /
+// `expected_content` fields of LocalAction items causes Cursor's renderer
+// (marked.js inline-link regex) to enter catastrophic backtracking on
+// `$()`, `[[ ]]`, URL-like substrings, and freezes the main thread.
+// See workspace/Issues/mcp-sync-complex-skill-cursor-crash.md.
+//
+// First attempt (markdown_fence_v1) tried to wrap content in a code fence,
+// but Cursor's renderer feeds the *raw JSON literal* to marked.js, where
+// `\n` is escaped as `\\n` and the fence never starts a real new line, so
+// the fence is just inert text and the inline-link regex still walks the
+// shell-script chars. Real-world test confirmed the freeze persisted.
+//
+// Final fix: for any non-`.md`/`.mdc` text file, base64-encode the content
+// and set `encoding: 'base64'`. The base64 alphabet (`[A-Za-z0-9+/=]`)
+// contains none of the metacharacters that marked.js's link regex looks
+// for (`[`, `]`, `(`, `)`, `<`, `>`, `!`), so backtracking cannot happen
+// no matter how long the string is.
+//
+// Markdown / mdc files stay UTF-8: they are valid markdown by themselves
+// and field testing has not produced a freeze on plain markdown content.
+const MARKDOWN_EXTENSIONS = new Set(['md', 'mdc']);
+function fileExtension(filePath) {
+    const m = /\.([A-Za-z0-9]+)$/.exec(filePath);
+    return m ? m[1].toLowerCase() : '';
+}
+/**
+ * Encode a text file body for safe transport in the JSON tool response.
+ *
+ * Returns `{ content, encoding }` ready to spread into a write_file action.
+ *
+ * For `.md` / `.mdc` files: `{ content: rawContent, encoding: 'utf8' }`
+ * (no transformation, valid markdown is safe to render directly).
+ *
+ * For everything else: `{ content: base64(rawContent), encoding: 'base64' }`
+ * to defuse Cursor's marked.js link-regex catastrophic backtracking on
+ * shell/script characters.
+ *
+ * If the caller already declared a `priorEncoding` of 'base64' (binary file
+ * pre-encoded by the upstream), we pass content through unchanged.
+ */
+function encodeForRender(filePath, rawContent, priorEncoding) {
+    if (priorEncoding === 'base64') {
+        return { content: rawContent, encoding: 'base64' };
+    }
+    if (MARKDOWN_EXTENSIONS.has(fileExtension(filePath))) {
+        return { content: rawContent, encoding: 'utf8' };
+    }
+    return {
+        content: Buffer.from(rawContent, 'utf8').toString('base64'),
+        encoding: 'base64',
+    };
+}
+/**
+ * Same as encodeForRender, but produces the field shape required by
+ * CheckFileAction (`expected_content` + a sibling encoding hint stored as
+ * `expected_content_encoding`). Returns the encoding even when 'utf8' so
+ * the AI Agent has an unambiguous signal.
+ */
+function encodeForCheck(filePath, rawContent, priorEncoding) {
+    const enc = encodeForRender(filePath, rawContent, priorEncoding);
+    return {
+        expected_content: enc.content,
+        expected_content_encoding: enc.encoding,
+    };
+}
 async function syncResources(params) {
     const startTime = Date.now();
     const typedParams = params;
@@ -104,6 +174,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,
@@ -248,17 +325,18 @@ async function syncResources(params) {
                                             localActions.push({
                                                 action: 'check_file',
                                                 path: `${skillDir}/${scriptFile.relative_path}`,
-                                                expected_content: scriptFile.content,
+                                                ...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`,
-                                            expected_content: metadata.script_files[0]?.content ?? '', // Use first script as proxy
+                                            ...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,
@@ -327,7 +405,7 @@ async function syncResources(params) {
                                         localActions.push({
                                             action: 'check_file',
                                             path: checkPath,
-                                            expected_content: file.content,
+                                            ...encodeForCheck(file.path, file.content),
                                             resource_id: sub.id,
                                             resource_name: sub.name,
                                             resource_type: sub.type,
@@ -340,7 +418,7 @@ async function syncResources(params) {
                                     localActions.push({
                                         action: 'check_file',
                                         path: mcpJsonPath,
-                                        expected_content: file.content,
+                                        ...encodeForCheck(file.path, file.content),
                                         resource_id: sub.id,
                                         resource_name: sub.name,
                                         resource_type: sub.type,
@@ -352,7 +430,7 @@ async function syncResources(params) {
                                     localActions.push({
                                         action: 'check_file',
                                         path: checkPath,
-                                        expected_content: file.content,
+                                        ...encodeForCheck(file.path, file.content),
                                         resource_id: sub.id,
                                         resource_name: sub.name,
                                         resource_type: sub.type,
@@ -484,13 +562,12 @@ async function syncResources(params) {
                                     localActions.push({
                                         action: 'write_file',
                                         path: `${skillDir}/${firstScript.path}`,
-                                        content: firstScript.content,
-                                        encoding: 'utf8',
+                                        ...encodeForRender(firstScript.path, firstScript.content),
                                         mode: firstScript.path.includes('/scripts/') ? '0755' : undefined,
                                         // Atomic update marker: client checks manifest FIRST
                                         is_skill_manifest: true,
                                         // SKILL.md content for version comparison (stored separately in .manifests/)
-                                        skill_manifest_content: rawContent,
+                                        skill_manifest_content: Buffer.from(rawContent, "utf8").toString("base64"),
                                     });
                                 }
                                 // 2. Remaining script files (client writes these ONLY if manifest changed)
@@ -501,8 +578,7 @@ async function syncResources(params) {
                                     localActions.push({
                                         action: 'write_file',
                                         path: `${skillDir}/${scriptFile.path}`,
-                                        content: scriptFile.content,
-                                        encoding: 'utf8',
+                                        ...encodeForRender(scriptFile.path, scriptFile.content),
                                         mode: scriptFile.path.includes('/scripts/') ? '0755' : undefined,
                                     });
                                 }
@@ -532,11 +608,10 @@ async function syncResources(params) {
                                             localActions.push({
                                                 action: 'write_file',
                                                 path: `${skillDir}/${firstScript.relative_path}`,
-                                                content: firstScript.content,
-                                                encoding: firstScript.encoding ?? 'utf8',
+                                                ...encodeForRender(firstScript.relative_path, firstScript.content, firstScript.encoding),
                                                 mode: firstScript.mode,
                                                 is_skill_manifest: true,
-                                                skill_manifest_content: rawContent,
+                                                skill_manifest_content: Buffer.from(rawContent, "utf8").toString("base64"),
                                             });
                                         }
                                         for (let i = 1; i < metadata.script_files.length; i++) {
@@ -546,8 +621,7 @@ async function syncResources(params) {
                                             localActions.push({
                                                 action: 'write_file',
                                                 path: `${skillDir}/${scriptFile.relative_path}`,
-                                                content: scriptFile.content,
-                                                encoding: scriptFile.encoding ?? 'utf8',
+                                                ...encodeForRender(scriptFile.relative_path, scriptFile.content, scriptFile.encoding),
                                                 mode: scriptFile.mode,
                                             });
                                         }
@@ -672,8 +746,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.
@@ -721,7 +797,25 @@ 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.
+                            // We emit a merge_toml action for the AI Agent to update that file.
+                            // The value is the JSON-serialised mcp-config entry so the agent can
+                            // parse and embed it in the correct TOML table.
+                            const tomlPath = clientAdapter.getMcpConfigPath();
+                            const serverName = cfg['name'] ?? sub.name;
+                            localActions.push({
+                                action: 'merge_toml',
+                                toml_path: tomlPath,
+                                key: `mcp.servers.${serverName}`,
+                                value: JSON.stringify(cfg),
+                                overwrite: false,
+                            });
+                            logger_1.logger.info({ resourceId: sub.id, resourceName: sub.name, serverName, 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 });
+                        }
+                        else if (typeof cfg['command'] === 'string') {
                             // ── Format A: local executable ──────────────────────────────────
                             const installDir = `${(0, cursor_paths_1.getCursorTypeDirForClient)('mcp')}/${sub.name}`;
                             const writeActions = [];
@@ -733,7 +827,7 @@ async function syncResources(params) {
                                 localActions.push({
                                     action: 'write_file',
                                     path: fileDest,
-                                    content: file.content,
+                                    ...encodeForRender(file.path, file.content),
                                 });
                                 writeActions.push(fileDest);
                             }
@@ -803,43 +897,57 @@ 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();
                             localActions.push({
-                                action: 'write_file',
-                                path: fileDest,
-                                content: file.content,
+                                action: 'merge_toml',
+                                toml_path: tomlPath,
+                                key: `mcp.servers.${sub.name}`,
+                                value: JSON.stringify({ command: 'node', args: [] }),
+                                overwrite: false,
                             });
-                            writeActions.push(fileDest);
+                            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: '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 });
                         }
-                        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 });
@@ -853,11 +961,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 = [];
@@ -878,7 +1000,7 @@ async function syncResources(params) {
                             localActions.push({
                                 action: 'write_file',
                                 path: destPath,
-                                content: file.content,
+                                ...encodeForRender(file.path, file.content),
                             });
                             writeActions.push({ destPath, contentLength: file.content.length });
                         }
@@ -936,7 +1058,43 @@ 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
+                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;
@@ -947,6 +1105,7 @@ async function syncResources(params) {
             details,
             ...(skippedResources.length > 0 ? { skipped_resources: skippedResources } : {}),
             ...(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);
@@ -1055,16 +1214,31 @@ exports.syncResourcesTool = {
         'This allows the server to skip downloading MCP resources that are already configured, ' +
         'significantly reducing API calls, network traffic, and local action overhead. ' +
         '\n' +
+        '⚠️ BASE64 DECODE — APPLIES TO BOTH write_file AND check_file: ' +
+        '  When `encoding === "base64"` (write_file) or `expected_content_encoding === "base64"` ' +
+        '  (check_file), the corresponding `content` / `expected_content` field is base64-encoded ' +
+        '  by the server. The server does this for ALL non-.md/.mdc files (shell scripts, configs, ' +
+        '  binary blobs) to keep Cursor\'s renderer from triggering catastrophic regex backtracking ' +
+        '  on raw script characters ($(), [[ ]], URLs etc.) — see prior incident notes. ' +
+        '  AI Agent MUST decode base64 BEFORE writing to disk or comparing against local content: ' +
+        '    write_file:  fileBytes = Buffer.from(action.content, "base64") (write as binary buffer) ' +
+        '    check_file:  decoded = Buffer.from(action.expected_content, "base64").toString("utf8") ' +
+        '                 then string-compare against fs.readFileSync(action.path, "utf8") ' +
+        '  When the encoding field is "utf8" (or omitted), the value is the literal file body — ' +
+        '  write or compare as-is, no decoding. ' +
         '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). ' +
         '        Where {CSP_AGENT_ROOT} is a SIBLING of {CURSOR_ROOT} (same parent directory). ' +
-        '    (3) Compare manifest content with action.skill_manifest_content field (string equality). ' +
+        '    (3) action.skill_manifest_content is ALWAYS base64-encoded — first decode it: ' +
+        '        decodedManifest = Buffer.from(action.skill_manifest_content, "base64").toString("utf8") ' +
+        '        Then compare decodedManifest against the existing manifest file content (string equality). ' +
         '    (4) If identical: SKIP this action AND ALL SUBSEQUENT write_file actions for this skill. ' +
         '    (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 action.skill_manifest_content to {CSP_AGENT_ROOT}/.manifests/<skill-name>.md ' +
+        '        - After writing all script files, write decodedManifest (the UTF-8 form, NOT the raw base64 string) ' +
+        '          to {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. ' +