@claude-flow/cli 3.71.4 → 3.72.0

package/dist/src/commands/guidance.js

@@ -34,7 +34,7 @@ const compileCommand = {
                 output.writeln(output.error(`Root guidance file not found: ${rootPath}`));
                 return { success: false, message: `File not found: ${rootPath}` };
             }
-            const modExport = ctx.flags['mod-projection'] === true;
+            const modExport = (ctx.flags.modProjection ?? ctx.flags['mod-projection']) === true;
             const checked = modExport ? await (await import('../guidance/mod-sources.js')).readModGuidanceSources({
                 rootPath, localPath, revision: String(ctx.flags.revision || ''),
             }) : undefined;
@@ -112,7 +112,7 @@ const retrieveCommand = {
         const task = ctx.flags.task;
         const rootPath = ctx.flags.root || './CLAUDE.md';
         const localPath = ctx.flags.local;
-        const maxShards = parseInt(ctx.flags['max-shards'] || '5', 10);
+        const maxShards = parseInt(String(ctx.flags.maxShards ?? ctx.flags['max-shards'] ?? 5), 10);
         const intentOverride = ctx.flags.intent;
         const jsonOutput = ctx.flags.json === true;
         if (!task) {
@@ -338,9 +338,9 @@ const optimizeCommand = {
         const rootPath = ctx.flags.root || './CLAUDE.md';
         const localPath = ctx.flags.local;
         const applyChanges = ctx.flags.apply === true;
-        const contextSize = (ctx.flags['context-size'] || 'standard');
-        const targetScore = parseInt(ctx.flags['target-score'] || '90', 10);
-        const maxIterations = parseInt(ctx.flags['max-iterations'] || '5', 10);
+        const contextSize = (ctx.flags.contextSize ?? ctx.flags['context-size'] ?? 'standard');
+        const targetScore = parseInt(String(ctx.flags.targetScore ?? ctx.flags['target-score'] ?? 90), 10);
+        const maxIterations = parseInt(String(ctx.flags.maxIterations ?? ctx.flags['max-iterations'] ?? 5), 10);
         const jsonOutput = ctx.flags.json === true;
         output.writeln();
         output.writeln(output.bold('Guidance Optimizer'));
@@ -437,10 +437,10 @@ const abTestCommand = {
         { command: 'claude-flow guidance ab-test --json', description: 'Output full report as JSON' },
     ],
     action: async (ctx) => {
-        const configAPath = ctx.flags['config-a'];
-        const configBPath = ctx.flags['config-b'] || './CLAUDE.md';
+        const configAPath = (ctx.flags.configA ?? ctx.flags['config-a']);
+        const configBPath = (ctx.flags.configB ?? ctx.flags['config-b'] ?? './CLAUDE.md');
         const tasksPath = ctx.flags.tasks;
-        const workDir = ctx.flags['work-dir'];
+        const workDir = (ctx.flags.workDir ?? ctx.flags['work-dir']);
         const jsonOutput = ctx.flags.json === true;
         output.writeln();
         output.writeln(output.bold('A/B Behavioral Benchmark'));
@@ -541,7 +541,7 @@ const modCandidatesCommand = {
     action: async (ctx) => {
         try {
             const { collectModCandidates } = await import('../guidance/mod-projection.js');
-            const data = await collectModCandidates(String(ctx.flags.directory || '.claude-flow/mods/guidance/observations'), ctx.flags['bundle-id']);
+            const data = await collectModCandidates(String(ctx.flags.directory || '.claude-flow/mods/guidance/observations'), (ctx.flags.bundleId ?? ctx.flags['bundle-id']));
             output.writeln(JSON.stringify(data, null, ctx.flags.json === true ? undefined : 2));
             return { success: true, data };
         }

package/dist/src/commands/hooks.js

@@ -2529,8 +2529,8 @@ const workerDetectCommand = {
     ],
     action: async (ctx) => {
         const prompt = ctx.flags['prompt'];
-        const autoDispatch = ctx.flags['auto-dispatch'];
-        const minConfidence = parseFloat(ctx.flags['min-confidence'] || '0.5');
+        const autoDispatch = (ctx.flags.autoDispatch ?? ctx.flags['auto-dispatch']);
+        const minConfidence = parseFloat(String(ctx.flags.minConfidence ?? ctx.flags['min-confidence'] ?? 0.5) || '0.5');
         if (!prompt) {
             output.printError('--prompt is required');
             return { success: false, exitCode: 1 };
@@ -2570,7 +2570,12 @@ const workerDetectCommand = {
             }
             if (result.autoDispatched && result.workerIds) {
                 output.writeln();
-                output.writeln(output.success('Workers auto-dispatched:'));
+                if (result.autoDispatchStatus === 'synthetic-completed') {
+                    output.printWarning(result.note ?? 'No executor ran. Worker records are synthetic placeholders.');
+                }
+                else {
+                    output.writeln(output.success('Workers auto-dispatched:'));
+                }
                 result.workerIds.forEach(id => {
                     output.writeln(`  - ${id}`);
                 });
@@ -3079,8 +3084,8 @@ const coverageGapsCommand = {
     ],
     action: async (ctx) => {
         const threshold = ctx.flags.threshold ?? 80;
-        const groupByAgent = ctx.flags['group-by-agent'] !== false;
-        const criticalOnly = ctx.flags['critical-only'] || false;
+        const groupByAgent = (ctx.flags.groupByAgent ?? ctx.flags['group-by-agent']) !== false;
+        const criticalOnly = (ctx.flags.criticalOnly ?? ctx.flags['critical-only']) === true;
         const spinner = output.createSpinner({ text: 'Analyzing project coverage gaps...' });
         spinner.start();
         // Try reading coverage from disk first
@@ -4161,7 +4166,7 @@ const modelRouteCommand = {
         { name: 'task', short: 't', type: 'string', description: 'Task description to route', required: true },
         { name: 'context', short: 'c', type: 'string', description: 'Additional context' },
         { name: 'prefer-cost', type: 'boolean', description: 'Prefer lower cost models' },
-        { name: 'prefer-quality', type: 'boolean', description: 'Prefer higher quality models' },
+        { name: 'prefer-speed', type: 'boolean', description: 'Prefer faster models when possible' },
     ],
     examples: [
         { command: 'claude-flow hooks model-route -t "fix typo"', description: 'Route simple task (likely haiku)' },
@@ -4178,8 +4183,8 @@ const modelRouteCommand = {
             const result = await callMCPTool('hooks_model-route', {
                 task,
                 context: ctx.flags.context,
-                preferCost: ctx.flags['prefer-cost'],
-                preferQuality: ctx.flags['prefer-quality'],
+                preferCost: ctx.flags.preferCost,
+                preferSpeed: ctx.flags.preferSpeed,
             });
             if (ctx.flags.format === 'json') {
                 output.printJson(result);

package/dist/src/commands/init.js

@@ -816,16 +816,22 @@ const initClaudeAction = async (ctx) => {
         if (startDaemon || startAll) {
             output.writeln();
             output.printInfo('Starting services...');
-            const { execSync } = await import('child_process');
+            const { execFileSync } = await import('child_process');
+            // #4770: drop stderr via stdio, not a shell redirect (breaks on cmd.exe).
+            // shell on win32 so npx.cmd resolves (#2770); args are fixed literals.
+            const runCli = (args) => {
+                execFileSync('npx', ['@claude-flow/cli@latest', ...args], {
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                    cwd: ctx.cwd,
+                    timeout: 30000,
+                    shell: process.platform === 'win32',
+                });
+            };
             // Initialize memory database
             if (startAll) {
                 try {
                     output.writeln(output.dim('  Initializing memory database...'));
-                    execSync('npx @claude-flow/cli@latest memory init 2>/dev/null', {
-                        stdio: 'pipe',
-                        cwd: ctx.cwd,
-                        timeout: 30000
-                    });
+                    runCli(['memory', 'init']);
                     output.writeln(output.success('  ✓ Memory initialized'));
                 }
                 catch {
@@ -854,11 +860,7 @@ const initClaudeAction = async (ctx) => {
             if (startDaemon) {
                 try {
                     output.writeln(output.dim('  Starting daemon...'));
-                    execSync('npx @claude-flow/cli@latest daemon start 2>/dev/null', {
-                        stdio: 'pipe',
-                        cwd: ctx.cwd,
-                        timeout: 30000
-                    });
+                    runCli(['daemon', 'start']);
                     output.writeln(output.success('  ✓ Daemon started'));
                 }
                 catch {
@@ -872,11 +874,7 @@ const initClaudeAction = async (ctx) => {
             if (startAll) {
                 try {
                     output.writeln(output.dim('  Initializing swarm...'));
-                    execSync('npx @claude-flow/cli@latest swarm init --topology hierarchical 2>/dev/null', {
-                        stdio: 'pipe',
-                        cwd: ctx.cwd,
-                        timeout: 30000
-                    });
+                    runCli(['swarm', 'init', '--topology', 'hierarchical']);
                     output.writeln(output.success('  ✓ Swarm initialized'));
                 }
                 catch {

package/dist/src/commands/neural.js

@@ -35,8 +35,8 @@ const trainCommand = {
     action: async (ctx) => {
         const patternType = (ctx.flags.pattern || ctx.flags.patternType || ctx.flags['pattern-type']) || 'coordination';
         const epochs = parseInt(ctx.flags.epochs || '50', 10);
-        const learningRate = parseFloat(ctx.flags['learning-rate'] || '0.01');
-        const batchSize = parseInt(ctx.flags['batch-size'] || '32', 10);
+        const learningRate = parseFloat((ctx.flags.learningRate ?? ctx.flags['learning-rate']) || '0.01');
+        const batchSize = parseInt((ctx.flags.batchSize ?? ctx.flags['batch-size']) || '32', 10);
         const dim = Math.min(parseInt(ctx.flags.dim || '256', 10), 256);
         // #2549 follow-up — backend routing: 'native' = @ruvector/ruvllm
         // TrainingPipeline (real epochs/early-stopping/disk checkpoints),
@@ -44,7 +44,7 @@ const trainCommand = {
         // 'auto' = native when the module resolves, else wasm.
         const backendFlag = String(ctx.flags.backend || 'auto');
         // Feature: validation split + resume (native TrainingPipeline leg).
-        const valSplitRaw = parseFloat(ctx.flags['val-split'] ?? '0.1');
+        const valSplitRaw = parseFloat((ctx.flags.valSplit ?? ctx.flags['val-split']) ?? '0.1');
         const valSplit = Number.isFinite(valSplitRaw) ? Math.max(0, Math.min(1, valSplitRaw)) : 0.1;
         const resumePath = ctx.flags.resume ? String(ctx.flags.resume) : undefined;
         // --resume is a native-only capability; refuse the WASM combination up
@@ -1023,7 +1023,7 @@ const exportCommand = {
         const outputFile = ctx.flags.output;
         const pinToIpfs = ctx.flags.ipfs;
         const signExport = ctx.flags.sign !== false;
-        const stripPii = ctx.flags['strip-pii'] !== false;
+        const stripPii = (ctx.flags.stripPii ?? ctx.flags['strip-pii']) !== false;
         const customName = ctx.flags.name;
         output.writeln();
         output.writeln(output.bold('Secure Model Export'));
@@ -1703,7 +1703,8 @@ const routerTrainCommand = {
     action: async (ctx) => {
         const corpusPath = ctx.flags.corpus;
         const outPath = ctx.flags.out || './router.krr.json';
-        const qualityBar = parseFloat(ctx.flags['quality-bar'] || '0.8') || 0.8;
+        const requestedQualityBar = parseFloat(String(ctx.flags.qualityBar ?? ctx.flags['quality-bar'] ?? 0.8));
+        const qualityBar = Number.isNaN(requestedQualityBar) ? 0.8 : requestedQualityBar;
         // Indirect the optional-dep specifier through a string variable so tsc
         // doesn't statically resolve `@metaharness/router` at build time (TS2307
         // when it isn't installed — #2586 pattern). The dep is optional at
@@ -3464,7 +3465,8 @@ const routerBanditStateCommand = {
         const statePath = ctx.flags.path
             ?? path.resolve(process.cwd(), '.swarm', 'model-router-state.json');
         const fmt = ctx.flags.format || 'table';
-        const coldThreshold = parseInt(ctx.flags['cold-threshold'] || '4', 10) || 4;
+        const requestedColdThreshold = parseInt(String(ctx.flags.coldThreshold ?? ctx.flags['cold-threshold'] ?? 4), 10);
+        const coldThreshold = Number.isNaN(requestedColdThreshold) ? 4 : requestedColdThreshold;
         if (!fs.existsSync(statePath)) {
             const msg = `Bandit state file not found at ${statePath}`;
             if (fmt === 'json')

package/dist/src/commands/route.js

@@ -367,7 +367,7 @@ const feedbackCommand = {
         const taskDescription = ctx.flags.task;
         const agentId = ctx.flags.agent;
         const reward = ctx.flags.reward;
-        const nextTask = ctx.flags['next-task'];
+        const nextTask = ctx.flags.nextTask;
         if (!taskDescription || !agentId) {
             output.printError('Task description and agent are required');
             return { success: false, exitCode: 1 };

package/dist/src/commands/ruvector/backup.js

@@ -53,10 +53,10 @@ const backupSubcommand = {
         {
             name: 'format',
             short: 'f',
-            description: 'Output format',
+            description: 'Output format (defaults to SQL)',
             type: 'string',
-            default: 'sql',
-            choices: ['sql', 'json', 'csv'],
+            default: 'text',
+            choices: ['text', 'sql', 'json', 'csv'],
         },
         {
             name: 'compress',
@@ -125,9 +125,11 @@ const backupSubcommand = {
         const config = getConnectionConfig(ctx);
         let outputPath = ctx.flags.output;
         const tablesFilter = ctx.flags.tables;
-        const format = ctx.flags.format || 'sql';
+        // The CLI validates the shared --format flag against its global choices.
+        const requestedFormat = ctx.flags.format;
+        const format = !requestedFormat || requestedFormat === 'text' ? 'sql' : requestedFormat;
         const compress = ctx.flags.compress;
-        const includeIndexes = ctx.flags['include-indexes'] !== false;
+        const includeIndexes = (ctx.flags.includeIndexes ?? ctx.flags['include-indexes']) !== false;
         output.writeln();
         output.writeln(output.bold('RuVector Backup'));
         output.writeln(output.dim('='.repeat(60)));

package/dist/src/commands/ruvector/benchmark.js

@@ -158,7 +158,8 @@ export const benchmarkCommand = {
         const topK = parseInt(ctx.flags.k || '10', 10);
         const metric = ctx.flags.metric || 'cosine';
         const indexType = ctx.flags.index || 'hnsw';
-        const batchSize = parseInt(ctx.flags['batch-size'] || '1000', 10);
+        const batchSizeFlag = ctx.flags.batchSize ?? ctx.flags['batch-size'] ?? 1000;
+        const batchSize = typeof batchSizeFlag === 'string' ? Number(batchSizeFlag) : batchSizeFlag;
         const cleanup = ctx.flags.cleanup !== false;
         output.writeln();
         output.writeln(output.bold('RuVector Performance Benchmark'));
@@ -168,6 +169,10 @@ export const benchmarkCommand = {
             output.printError('Database name is required. Use --database or -d flag, or set PGDATABASE env.');
             return { success: false, exitCode: 1 };
         }
+        if (typeof batchSize !== 'number' || !Number.isSafeInteger(batchSize) || batchSize < 1) {
+            output.printError('--batch-size must be a positive integer');
+            return { success: false, exitCode: 1 };
+        }
         // Show benchmark configuration
         output.writeln(output.highlight('Benchmark Configuration:'));
         output.printTable({

package/dist/src/commands/ruvector/import.js

@@ -166,15 +166,21 @@ export const importCommand = {
     ],
     action: async (ctx) => {
         const inputFile = ctx.flags.input;
-        const fromMemory = ctx.flags['from-memory'];
+        const fromMemory = (ctx.flags.fromMemory ?? ctx.flags['from-memory']);
         const outputFile = ctx.flags.output;
-        const batchSize = ctx.flags['batch-size'] || 100;
+        const batchSizeFlag = ctx.flags.batchSize ?? ctx.flags['batch-size'] ?? 100;
+        const batchSize = typeof batchSizeFlag === 'string' ? Number(batchSizeFlag) : batchSizeFlag;
         const containerName = ctx.flags.container || 'ruvector-postgres';
         const verbose = ctx.flags.verbose;
         output.writeln();
         output.writeln(output.bold('RuVector PostgreSQL Import'));
         output.writeln(output.dim('='.repeat(50)));
         output.writeln();
+        if (typeof batchSize !== 'number' || !Number.isSafeInteger(batchSize) || batchSize < 1) {
+            const message = '--batch-size must be a positive integer';
+            output.printError(message);
+            return { success: false, message };
+        }
         // Validate input
         if (!inputFile && !fromMemory) {
             output.printError('Either --input <file> or --from-memory is required');
@@ -248,6 +254,7 @@ export const importCommand = {
         sqlStatements.push('');
         sqlStatements.push('BEGIN;');
         sqlStatements.push('');
+        const inserts = [];
         for (const entry of entries) {
             try {
                 // Track statistics
@@ -256,9 +263,7 @@ export const importCommand = {
                 if (entry.embedding && entry.embedding.length > 0) {
                     stats.withEmbeddings++;
                 }
-                const sql = generateInsertSQL(entry);
-                sqlStatements.push(sql);
-                sqlStatements.push('');
+                inserts.push(generateInsertSQL(entry));
                 stats.imported++;
                 if (verbose) {
                     output.writeln(output.dim(`  Processed: ${entry.key} (${ns})`));
@@ -270,6 +275,15 @@ export const importCommand = {
                 output.printWarning(`Skipped entry "${entry.key}": ${errorMessage}`);
             }
         }
+        // Send each batch as one statement while keeping ordered upserts in the same transaction.
+        for (let offset = 0; offset < inserts.length; offset += batchSize) {
+            const batch = inserts.slice(offset, offset + batchSize).join('\n\n');
+            let tag = 'ruvector_batch';
+            // A value containing the delimiter must stay inside the block.
+            while (batch.includes(`$${tag}$`))
+                tag += '_';
+            sqlStatements.push(`DO $${tag}$\nBEGIN\n${batch}\nEND;\n$${tag}$;`, '');
+        }
         sqlStatements.push('COMMIT;');
         sqlStatements.push('');
         sqlStatements.push(`-- Import complete: ${stats.imported} entries`);

package/dist/src/commands/ruvector/init.js

@@ -145,7 +145,7 @@ export const initCommand = {
         }
         const force = ctx.flags.force;
         const dimensions = parseInt(ctx.flags.dimensions || '1536', 10);
-        const indexType = ctx.flags['index-type'] || 'hnsw';
+        const indexType = (ctx.flags.indexType ?? ctx.flags['index-type']) || 'hnsw';
         // Show configuration
         output.writeln(output.highlight('Connection Configuration:'));
         output.printTable({

package/dist/src/commands/start.js

@@ -85,7 +85,7 @@ const startAction = async (ctx) => {
     const daemon = ctx.flags.daemon;
     const port = ctx.flags.port || DEFAULT_PORT;
     const topology = ctx.flags.topology || DEFAULT_TOPOLOGY;
-    const skipMcp = ctx.flags['skip-mcp'];
+    const skipMcp = ctx.flags.skipMcp;
     const cwd = ctx.cwd;
     // Check initialization
     if (!isInitialized(cwd)) {

package/dist/src/commands/status.js

@@ -281,7 +281,7 @@ function formatHealth(health) {
 const statusAction = async (ctx) => {
     const watch = ctx.flags.watch;
     const interval = ctx.flags.interval || DEFAULT_WATCH_INTERVAL / 1000;
-    const healthCheck = ctx.flags['health-check'];
+    const healthCheck = ctx.flags.healthCheck;
     const cwd = ctx.cwd;
     // Check initialization
     if (!isInitialized(cwd)) {

package/dist/src/commands/task.js

@@ -571,6 +571,12 @@ const assignCommand = {
                         taskId,
                         agentIds: selectedAgents
                     });
+                    // task_assign answers a finished task or an unknown agent with
+                    // success: false instead of throwing (#4725).
+                    if (result.success === false) {
+                        output.printError(`Failed to assign task ${taskId}: ${result.error || 'unknown error'}`);
+                        return { success: false, exitCode: 1, data: result };
+                    }
                     output.writeln();
                     output.printSuccess(`Task ${taskId} assigned to ${result.assignedTo.join(', ')}`);
                     return { success: true, data: result };
@@ -592,6 +598,17 @@ const assignCommand = {
                 agentIds: unassign ? [] : agentIds.split(',').map(id => id.trim()),
                 unassign
             });
+            // task_assign answers a finished task or an unknown agent with
+            // success: false instead of throwing (#4725).
+            if (result.success === false) {
+                if (ctx.flags.format === 'json') {
+                    output.printJson(result);
+                }
+                else {
+                    output.printError(`Failed to assign task ${taskId}: ${result.error || 'unknown error'}`);
+                }
+                return { success: false, exitCode: 1, data: result };
+            }
             output.writeln();
             if (unassign) {
                 output.printSuccess(`Task ${taskId} unassigned`);
@@ -630,7 +647,7 @@ const retryCommand = {
     ],
     action: async (ctx) => {
         const taskId = ctx.args[0];
-        const resetState = ctx.flags['reset-state'];
+        const resetState = (ctx.flags.resetState ?? ctx.flags['reset-state']);
         if (!taskId) {
             output.printError('Task ID is required');
             return { success: false, exitCode: 1 };

package/dist/src/commands/update.js

@@ -120,7 +120,7 @@ const allCommand = {
                 autoUpdate: {
                     patch: true,
                     minor: true,
-                    major: flags['include-major'] || false,
+                    major: flags.includeMajor || false,
                 },
             };
             const { results } = await checkForUpdates(config);

package/dist/src/funnel/local-signals.js

@@ -9,7 +9,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { execSync } from 'child_process';
+import { execFileSync, execSync } from 'child_process';
 export function getSecurityStatus(cwd = process.cwd()) {
     const empty = {
         status: 'PENDING', findings: 0, cvesFixed: 0, totalCves: 0,
@@ -67,7 +67,12 @@ export function getSwarmStatus() {
 /** Count of uncommitted-changed files (git status --short line count). */
 export function getGitUncommittedCount() {
     try {
-        const out = execSync('git status --porcelain 2>/dev/null', { encoding: 'utf-8', timeout: 3000 });
+        // #4770: no shell, so this also works on Windows.
+        const out = execFileSync('git', ['status', '--porcelain'], {
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
         const lines = out.split('\n').filter((l) => l.trim().length > 0);
         return lines.length;
     }

package/dist/src/mcp-protocol.d.ts

@@ -0,0 +1,90 @@
+/**
+ * MCP protocol-version handling for the stdio servers (ADR-524).
+ *
+ * Ruflo ships three stdio entry points (`bin/cli.js` auto-detect, `bin/mcp-server.js`,
+ * and `MCPServerManager` in mcp-server.ts). All three answered `initialize` with a
+ * hardcoded `2024-11-05` and knew nothing of the 2026-07-28 revision, which drops the
+ * handshake and carries the version on every request. This module is the one place
+ * that decides which revision a message speaks, so the three handlers cannot drift.
+ *
+ * Dual-era behaviour (spec: basic/versioning):
+ *  - `initialize` selects legacy semantics; the requested legacy version is echoed.
+ *  - a request carrying `_meta["io.modelcontextprotocol/protocolVersion"]` is served
+ *    statelessly: `resultType` and `serverInfo` on every result, cache hints on lists,
+ *    `-32602` for an unknown resource, `-32022` for an unsupported version.
+ *  - `server/discover` is always answered, so a dual-era client's stdio probe succeeds.
+ */
+export declare const MODERN_PROTOCOL_VERSIONS: readonly ["2026-07-28"];
+export declare const LEGACY_PROTOCOL_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2024-11-05"];
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+/** Offered to a legacy client whose requested version we do not know. */
+export declare const LATEST_LEGACY_PROTOCOL_VERSION: "2025-11-25";
+export declare const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+export declare const META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+export declare const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+export declare const ERROR_INVALID_PARAMS = -32602;
+export declare const ERROR_UNSUPPORTED_PROTOCOL_VERSION = -32022;
+/** 2025-11-25 and earlier; replaced by -32602 in 2026-07-28. */
+export declare const ERROR_LEGACY_RESOURCE_NOT_FOUND = -32002;
+/** Tool catalogue is fixed for the life of a stdio process; five minutes is a conservative hint. */
+export declare const TOOLS_LIST_TTL_MS = 300000;
+export declare const DISCOVER_TTL_MS = 3600000;
+export interface ServerIdentity {
+    name: string;
+    version: string;
+}
+export interface ProtocolContext {
+    /** True when the request used 2026-07-28 per-request metadata. */
+    modern: boolean;
+    /** Version the request declared, or undefined for legacy requests. */
+    version?: string;
+    /** Validated W3C traceparent, if the client propagated one. */
+    traceparent?: string;
+    tracestate?: string;
+}
+export interface JsonRpcMessage {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    result?: Record<string, unknown>;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export type Preflight = {
+    response: JsonRpcResponse;
+    context?: undefined;
+} | {
+    response?: undefined;
+    context: ProtocolContext;
+};
+/** The CLI package version, read once from package.json (dist/src/ → ../../). */
+export declare function rufloPackageVersion(): string;
+export declare function defaultServerIdentity(): ServerIdentity;
+/** Pick the legacy version to answer `initialize` with (spec: echo if supported, else our latest). */
+export declare function negotiateLegacyVersion(requested: unknown): string;
+export declare function isValidTraceparent(value: unknown): value is string;
+/**
+ * Decide how to serve one inbound message before the handler's own switch runs.
+ * Returns a complete response for `initialize`, `server/discover` and protocol
+ * errors; otherwise returns the context the handler passes to `finalizeResponse`.
+ */
+export declare function protocolPreflight(message: JsonRpcMessage, capabilities: Record<string, unknown>, identity?: ServerIdentity): Preflight;
+/** The resource-not-found code the request's revision expects. */
+export declare function resourceNotFoundCode(context: ProtocolContext): number;
+/** Stable, name-ordered copy so `tools/list` is byte-identical across calls (prompt-cache friendly). */
+export declare function sortToolsDeterministically<T extends {
+    name: string;
+}>(tools: readonly T[]): T[];
+/** Tool-call context fields to forward, so handlers and logs can join the caller's trace. */
+export declare function traceContextFields(context: ProtocolContext): Record<string, string>;
+/** Add the 2026-07-28 result fields to a handler's response. Legacy responses pass through untouched. */
+export declare function finalizeResponse(response: JsonRpcResponse | null, method: string | undefined, context: ProtocolContext, identity?: ServerIdentity): JsonRpcResponse | null;
+//# sourceMappingURL=mcp-protocol.d.ts.map