fraim-framework 2.0.161 → 2.0.163

package/dist/src/cli/commands/init-project.js

@@ -235,7 +235,13 @@ const runInitProject = async (options = {}) => {
         }
         result.warnings.push(`${configDisplayPath} was not created by init-project. The manager \`project-onboarding\` job is the only supported config-writing path.`);
     }
-    ['jobs', 'ai-employee/jobs', 'ai-employee/skills', 'ai-manager/jobs', 'personalized-employee'].forEach((dir) => {
+    [
+        'jobs',
+        'ai-employee/jobs',
+        'ai-employee/skills',
+        'ai-manager/jobs',
+        'personalized-employee',
+    ].forEach((dir) => {
         const dirPath = path_1.default.join(fraimDir, dir);
         if (!fs_1.default.existsSync(dirPath)) {
             fs_1.default.mkdirSync(dirPath, { recursive: true });

package/dist/src/cli/doctor/check-runner.js

@@ -7,7 +7,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runChecks = runChecks;
 const CHECK_TIMEOUT = 2000; // 2 seconds per check
-const MCP_CHECK_TIMEOUT = 10000; // 10 seconds for MCP connectivity checks
+// Issue #532: stdio MCP servers need up to 15s for handshake + npm version resolution
+// on first call via fraim-mcp-latest-launcher; 20s gives a 5s buffer.
+const MCP_CHECK_TIMEOUT = 20000; // 20 seconds for MCP connectivity checks
 const TOTAL_TIMEOUT = 30000; // 30 seconds total
 // Simple logger for doctor command (optional, falls back to no-op)
 const logger = {

package/dist/src/cli/doctor/checks/mcp-connectivity-checks.js

@@ -3,6 +3,7 @@
  * MCP connectivity checks for FRAIM doctor command
  * Tests FRAIM server connectivity and validates IDE MCP configurations
  * Issue #144: Enhanced doctor command
+ * Issue #532: Stdio MCP runtime connectivity check
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -43,6 +44,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNpmMajorVersion = getNpmMajorVersion;
 exports.diagnoseFraimMcpLaunchPlan = diagnoseFraimMcpLaunchPlan;
+exports.spawnAndHandshake = spawnAndHandshake;
+exports.getStdioMCPRuntimeChecks = getStdioMCPRuntimeChecks;
 exports.getMCPConnectivityChecks = getMCPConnectivityChecks;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -52,7 +55,16 @@ const axios_1 = __importDefault(require("axios"));
 const toml = __importStar(require("toml"));
 const ide_detector_1 = require("../../setup/ide-detector");
 const fraim_mcp_latest_launcher_1 = require("../../mcp/fraim-mcp-latest-launcher");
+const command_resolution_1 = require("../../mcp/command-resolution");
+// Cache the npm major version so execFileSync is called at most once per process.
+// Without caching, each IDE config check calls diagnoseFraimMcpLaunchPlan which calls
+// getNpmMajorVersion, and execFileSync blocks the event loop for ~2s on Windows.
+// With 8+ IDE checks running via Promise.all the blocking stacks sequentially.
+let _npmMajorVersionCache = undefined;
 function getNpmMajorVersion() {
+    if (_npmMajorVersionCache !== undefined) {
+        return _npmMajorVersionCache;
+    }
     try {
         const command = process.platform === 'win32' ? (process.env.ComSpec || 'cmd.exe') : 'npm';
         const args = process.platform === 'win32' ? ['/d', '/s', '/c', 'npm --version'] : ['--version'];
@@ -61,11 +73,12 @@ function getNpmMajorVersion() {
             stdio: ['ignore', 'pipe', 'ignore']
         });
         const major = Number.parseInt(output.trim().split('.')[0], 10);
-        return Number.isFinite(major) ? major : null;
+        _npmMajorVersionCache = Number.isFinite(major) ? major : null;
     }
     catch {
-        return null;
+        _npmMajorVersionCache = null;
     }
+    return _npmMajorVersionCache;
 }
 function diagnoseFraimMcpLaunchPlan(fraimServer, platform = process.platform, npmMajorVersion = getNpmMajorVersion()) {
     const command = String(fraimServer?.command || '');
@@ -419,6 +432,248 @@ async function validateIDEMCPConfig(ide) {
         };
     }
 }
+// ============================================================
+// Issue #532: Stdio MCP Runtime Connectivity Check
+// ============================================================
+const STDIO_HANDSHAKE_TIMEOUT_MS = 15000;
+/**
+ * Spawn a stdio MCP server, perform a two-phase JSON-RPC handshake
+ * (initialize then tools/list), and return a structured result.
+ *
+ * On Windows, wraps the command in cmd.exe /d /s /c so that .cmd wrappers
+ * resolve correctly. The same pattern is used by resolveManagedCommand and
+ * fraim-mcp-latest-launcher.
+ */
+async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const startTime = Date.now();
+        let spawnCommand;
+        let spawnArgs;
+        // spawnOptions is typed loosely so we can set windowsVerbatimArguments below.
+        let spawnOptions = {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: process.env
+        };
+        if (process.platform === 'win32') {
+            // On Windows, wrap in cmd.exe so .cmd wrappers are resolved.
+            // cmd.exe /d /s /c requires special handling when the command path contains spaces:
+            //   cmd /c ""path with spaces" arg1 arg2"
+            // The outer pair of double-quotes is mandatory when the first token is quoted.
+            // We must also pass windowsVerbatimArguments: true so Node's CreateProcess call
+            // does not re-escape our already-quoted command string.
+            const comSpec = process.env.ComSpec || 'cmd.exe';
+            const quotedTokens = [command, ...args].map((a) => {
+                const v = String(a);
+                return /[\s"&|<>^]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+            });
+            const innerCmd = quotedTokens.join(' ');
+            // Wrap in outer quotes only when the command contains spaces (i.e. was itself quoted).
+            const needsOuterQuote = /[\s"&|<>^]/.test(String(command));
+            const cmdString = needsOuterQuote ? `"${innerCmd}"` : innerCmd;
+            spawnCommand = comSpec;
+            spawnArgs = ['/d', '/s', '/c', cmdString];
+            spawnOptions = { ...spawnOptions, windowsVerbatimArguments: true };
+        }
+        else {
+            spawnCommand = command;
+            spawnArgs = args;
+        }
+        let child;
+        try {
+            child = (0, child_process_1.spawn)(spawnCommand, spawnArgs, spawnOptions);
+        }
+        catch (spawnErr) {
+            resolve({
+                status: 'error',
+                phase: 'spawn',
+                message: `Failed to spawn MCP server: ${spawnErr.message}`,
+                suggestion: 'Verify that npx is installed and accessible on PATH.',
+                details: { command, args, error: spawnErr.message }
+            });
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* best effort */ }
+            resolve({
+                status: 'error',
+                phase: 'initialize',
+                message: `MCP server did not respond within ${timeoutMs}ms`,
+                suggestion: 'The server may be slow to start. Check that the package is installed and npx cache is warm.',
+                details: { command, args, timeoutMs, elapsed: Date.now() - startTime }
+            });
+        }, timeoutMs);
+        let stderrBuffer = '';
+        let stdoutBuffer = '';
+        let spawnError = null;
+        child.stderr?.on('data', (d) => {
+            stderrBuffer += d.toString();
+        });
+        child.on('error', (err) => {
+            spawnError = err;
+        });
+        child.stdout?.on('data', (d) => {
+            stdoutBuffer += d.toString();
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (spawnError) {
+                const msg = spawnError.message || '';
+                const isEnoent = msg.includes('ENOENT') || msg.includes('not found');
+                resolve({
+                    status: 'error',
+                    phase: 'spawn',
+                    message: `Failed to start MCP server: ${msg}`,
+                    suggestion: isEnoent
+                        ? 'Verify that npx is installed. Run: npm install -g npm to update npm/npx.'
+                        : 'Check that the required package can be installed via npx.',
+                    details: { command, args, error: msg }
+                });
+                return;
+            }
+            if (code !== 0 && stdoutBuffer.trim() === '') {
+                resolve({
+                    status: 'error',
+                    phase: 'spawn',
+                    message: `MCP server exited with code ${code} before responding`,
+                    suggestion: 'Run: npx -y <package> manually to check for installation errors.',
+                    details: { command, args, exitCode: code, stderr: stderrBuffer.slice(0, 500) }
+                });
+                return;
+            }
+            // Parse all JSON-RPC messages received from stdout
+            const lines = stdoutBuffer.split('\n').map((l) => l.trim()).filter(Boolean);
+            let initializeResponse = null;
+            let toolsListResponse = null;
+            for (const line of lines) {
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg?.id === 1 && msg?.result !== undefined) {
+                        initializeResponse = msg;
+                    }
+                    if (msg?.id === 2 && msg?.result !== undefined) {
+                        toolsListResponse = msg;
+                    }
+                }
+                catch {
+                    // Ignore non-JSON lines (e.g., startup log output)
+                }
+            }
+            if (!initializeResponse) {
+                resolve({
+                    status: 'error',
+                    phase: 'initialize',
+                    message: 'MCP server did not return a valid initialize response',
+                    suggestion: 'The server may have crashed during startup. Check stderr for error details.',
+                    details: { command, args, exitCode: code, stderr: stderrBuffer.slice(0, 500) }
+                });
+                return;
+            }
+            if (!toolsListResponse) {
+                resolve({
+                    status: 'error',
+                    phase: 'tools-list',
+                    message: 'MCP server did not respond to tools/list',
+                    suggestion: 'The server initialized but did not expose any tools. Check the package documentation.',
+                    details: { command, args, exitCode: code }
+                });
+                return;
+            }
+            const toolCount = Array.isArray(toolsListResponse.result?.tools)
+                ? toolsListResponse.result.tools.length
+                : 0;
+            const elapsed = Date.now() - startTime;
+            resolve({
+                status: 'passed',
+                message: `MCP server responded with ${toolCount} tool(s) in ${elapsed}ms`,
+                details: { command, args, toolCount, elapsed }
+            });
+        });
+        // Send two-phase JSON-RPC handshake
+        try {
+            const initMsg = JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2024-11-05',
+                    capabilities: {},
+                    clientInfo: { name: 'fraim-doctor', version: '1.0' }
+                }
+            }) + '\n';
+            child.stdin?.write(initMsg);
+            const toolsMsg = JSON.stringify({
+                jsonrpc: '2.0',
+                id: 2,
+                method: 'tools/list',
+                params: {}
+            }) + '\n';
+            child.stdin?.write(toolsMsg);
+            child.stdin?.end();
+        }
+        catch {
+            // stdin may not be writable if the process exited immediately
+        }
+    });
+}
+/**
+ * Run a connectivity check for a single named stdio MCP server.
+ */
+async function testStdioMCPServer(serverName, command, args) {
+    if (process.env.NODE_ENV === 'test') {
+        return {
+            status: 'warning',
+            message: `Stdio MCP runtime check for "${serverName}" skipped (test mode)`,
+            details: { testMode: true, skipped: true, serverName }
+        };
+    }
+    const result = await spawnAndHandshake(command, args, STDIO_HANDSHAKE_TIMEOUT_MS);
+    if (result.status === 'passed') {
+        return {
+            status: 'passed',
+            message: `${serverName} stdio MCP: ${result.message}`,
+            details: result.details
+        };
+    }
+    return {
+        status: 'error',
+        message: `${serverName} stdio MCP connectivity failed (phase: ${result.phase}): ${result.message}`,
+        suggestion: result.suggestion,
+        details: { ...result.details, phase: result.phase }
+    };
+}
+/**
+ * Build the 3 stdio MCP runtime checks (git, playwright, fraim).
+ * Exported separately so callers can obtain just the runtime checks if needed.
+ */
+function getStdioMCPRuntimeChecks() {
+    const npx = (0, command_resolution_1.resolveManagedCommand)('npx');
+    // For the fraim MCP server we use the latest launcher so the test
+    // exercises the same path that IDE configs use.
+    const fraimLauncherPath = (0, fraim_mcp_latest_launcher_1.getFraimMcpLatestLauncherPath)();
+    return [
+        {
+            name: 'git stdio runtime check',
+            category: 'mcpConnectivity',
+            critical: false,
+            run: () => testStdioMCPServer('git', npx, ['-y', '@cyanheads/git-mcp-server'])
+        },
+        {
+            name: 'playwright stdio runtime check',
+            category: 'mcpConnectivity',
+            critical: false,
+            run: () => testStdioMCPServer('playwright', npx, ['-y', '@playwright/mcp'])
+        },
+        {
+            name: 'fraim stdio runtime check',
+            category: 'mcpConnectivity',
+            critical: false,
+            run: () => testStdioMCPServer('fraim', process.execPath, [fraimLauncherPath])
+        }
+    ];
+}
 /**
  * Get all MCP connectivity checks
  */
@@ -441,5 +696,9 @@ function getMCPConnectivityChecks() {
             run: async () => validateIDEMCPConfig(ide)
         });
     }
+    // Check 3 (Issue #532): Confirm stdio MCP servers respond at runtime.
+    // "Disconnected" in mcp list is expected on-demand-spawn behavior. These checks
+    // verify that each server can actually start and complete a JSON-RPC handshake.
+    checks.push(...getStdioMCPRuntimeChecks());
     return checks;
 }

package/dist/src/cli/utils/agent-adapters.js

@@ -71,7 +71,7 @@ This repository uses FRAIM.
 - When users ask for next step recommendations, use recommend-next-job skill under \`${employeeSkillsPath}/\` to gather context before suggesting jobs.
 
 > [!IMPORTANT]
-> **Job stubs are for discovery only.** When a user @mentions or references any file under \`${employeeJobsPath}/\` or \`${managerJobsPath}/\`, do NOT attempt to execute the job from the stub content. The stub only shows intent and phase names. Always call \`get_fraim_job({ job: "<job-name>" })\` first to get the full phased instructions before doing any work.
+> **Job stubs are for discovery only.** When a user mentions or references any file under \`${employeeJobsPath}/\` or \`${managerJobsPath}/\`, do NOT attempt to execute the job from the stub content. The stub only shows intent and phase names. Always call \`get_fraim_job({ job: "<job-name>" })\` first to get the full phased instructions before doing any work.
 `);
     const cursorManagedBody = buildManagedSection(`
 # FRAIM

package/dist/src/core/fraim-config-schema.generated.js

@@ -349,6 +349,51 @@ exports.FRAIM_CONFIG_SCHEMA = {
                                 }
                             }
                         },
+                        "playbooks": {
+                            "kind": "object",
+                            "properties": {
+                                "directory": {
+                                    "kind": "string"
+                                },
+                                "decisionCommand": {
+                                    "kind": "string"
+                                },
+                                "decisionTimeoutMs": {
+                                    "kind": "number"
+                                }
+                            }
+                        },
+                        "actionAdapters": {
+                            "kind": "record",
+                            "value": {
+                                "kind": "object",
+                                "properties": {
+                                    "type": {
+                                        "kind": "enum",
+                                        "values": [
+                                            "command",
+                                            "manual",
+                                            "handoff"
+                                        ]
+                                    },
+                                    "command": {
+                                        "kind": "string"
+                                    },
+                                    "timeoutMs": {
+                                        "kind": "number"
+                                    },
+                                    "targetSystem": {
+                                        "kind": "string"
+                                    },
+                                    "targetIdentityProvider": {
+                                        "kind": "string"
+                                    },
+                                    "instructions": {
+                                        "kind": "string"
+                                    }
+                                }
+                            }
+                        },
                         "queue": {
                             "kind": "object",
                             "properties": {
@@ -407,17 +452,6 @@ exports.FRAIM_CONFIG_SCHEMA = {
                                         "requireApprovalState": {
                                             "kind": "string"
                                         },
-                                        "selector": {
-                                            "kind": "object",
-                                            "properties": {
-                                                "shortDescriptionContains": {
-                                                    "kind": "array",
-                                                    "element": {
-                                                        "kind": "string"
-                                                    }
-                                                }
-                                            }
-                                        },
                                         "microsoftPasswordReset": {
                                             "kind": "object",
                                             "properties": {
@@ -564,6 +598,11 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "automation.support.contextResolver.scriptPath",
     "automation.support.contextResolver.arguments",
     "automation.support.contextResolver.timeoutMs",
+    "automation.support.playbooks",
+    "automation.support.playbooks.directory",
+    "automation.support.playbooks.decisionCommand",
+    "automation.support.playbooks.decisionTimeoutMs",
+    "automation.support.actionAdapters",
     "automation.support.queue",
     "automation.support.queue.provider",
     "automation.support.queue.table",
@@ -579,8 +618,6 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "automation.support.requestTypes.password_reset",
     "automation.support.requestTypes.password_reset.mode",
     "automation.support.requestTypes.password_reset.requireApprovalState",
-    "automation.support.requestTypes.password_reset.selector",
-    "automation.support.requestTypes.password_reset.selector.shortDescriptionContains",
     "automation.support.requestTypes.password_reset.microsoftPasswordReset",
     "automation.support.requestTypes.password_reset.microsoftPasswordReset.resetType",
     "automation.support.requestTypes.password_reset.microsoftPasswordReset.providedPasswordEnvVar",

package/dist/src/first-run/types.js

@@ -50,6 +50,14 @@ exports.FIRST_RUN_AGENT_OPTIONS = [
         launchCommand: 'gemini',
         installPackage: '@google/gemini-cli',
     },
+    {
+        id: 'copilot-cli',
+        label: 'GitHub Copilot',
+        detectAliases: ['copilot'],
+        loginCommand: 'copilot login',
+        launchCommand: 'copilot',
+        installPackage: '@github/copilot',
+    },
 ];
 /**
  * The canonical row set, in display order. Each row starts in `pending`;

package/dist/src/local-mcp-server/agent-token-prices.js

@@ -86,6 +86,59 @@ exports.AGENT_TOKEN_PRICES = [
         source: 'https://openai.com/api/pricing/ (gpt-5 row, applied to gpt-5.5 as nearest published rate)',
         verifiedOn: '2026-04-30',
     },
+    // Google — Gemini CLI. Standard paid-tier text/image/video token rates.
+    // Context caching maps to cache reads; the published storage-hour price
+    // cannot be derived from the CLI token stats and is intentionally omitted.
+    {
+        agent: 'gemini',
+        model: 'gemini-3.1-flash-lite',
+        inputPerMTok: 0.25,
+        outputPerMTok: 1.50,
+        cacheReadPerMTok: 0.025,
+        cacheCreationPerMTok: 0,
+        source: 'https://ai.google.dev/gemini-api/docs/pricing',
+        verifiedOn: '2026-06-02',
+    },
+    {
+        agent: 'gemini',
+        model: 'gemini-3-flash-preview',
+        inputPerMTok: 0.50,
+        outputPerMTok: 3.00,
+        cacheReadPerMTok: 0.05,
+        cacheCreationPerMTok: 0,
+        source: 'https://ai.google.dev/gemini-api/docs/pricing',
+        verifiedOn: '2026-06-02',
+    },
+    // GitHub Copilot CLI. The CLI's agentic mode uses GPT-4.1 (also branded
+    // "gpt-4.1" in the Copilot API stream). GitHub charges for Copilot via
+    // premium-request quota rather than per-token billing on most plans; the
+    // per-token rates below apply to the Copilot API / enterprise API billing
+    // path (pay-per-token, not included-requests) as published at
+    // https://docs.github.com/en/copilot/about-github-copilot/plans-for-github-copilot
+    // and the underlying OpenAI model pricing for gpt-4.1 at openai.com/api/pricing/.
+    // Coverage is 'partial' for Copilot runs where the CLI does not emit a cost
+    // field — the table backstops cost computation when a token count is present
+    // but no direct costUsd is in the stream.
+    {
+        agent: 'copilot',
+        model: 'gpt-4.1',
+        inputPerMTok: 2.00,
+        outputPerMTok: 8.00,
+        cacheReadPerMTok: 0.50,
+        cacheCreationPerMTok: 0,
+        source: 'https://openai.com/api/pricing/ (gpt-4.1 row; GitHub Copilot CLI agentic mode)',
+        verifiedOn: '2026-06-09',
+    },
+    {
+        agent: 'copilot',
+        model: 'gpt-4o',
+        inputPerMTok: 2.50,
+        outputPerMTok: 10.00,
+        cacheReadPerMTok: 1.25,
+        cacheCreationPerMTok: 0,
+        source: 'https://openai.com/api/pricing/ (gpt-4o row; GitHub Copilot CLI fallback model)',
+        verifiedOn: '2026-06-09',
+    },
 ];
 /**
  * Look up the price entry for an agent + model. Agent is matched