muxed 0.2.1 → 0.2.2

package/dist/cli.mjs

@@ -11,12 +11,13 @@ import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontex
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
 import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
 import crypto from "node:crypto";
-import { execFile, fork } from "node:child_process";
+import { execFile, execSync, fork } from "node:child_process";
 import http from "node:http";
 import { compile } from "json-schema-to-typescript";
 import net from "node:net";
 import { Command } from "commander";
 import { PostHog } from "posthog-node";
+import { fileURLToPath } from "node:url";
 import * as readline from "node:readline/promises";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -77,6 +78,7 @@ const DaemonConfigSchema = z.object({
 	connectTimeout: z.number().optional(),
 	requestTimeout: z.number().optional(),
 	healthCheckInterval: z.number().optional(),
+	healthCheckTimeout: z.number().optional(),
 	maxRestartAttempts: z.number().optional(),
 	maxTotalTimeout: z.number().optional(),
 	taskExpiryTimeout: z.number().optional(),
@@ -120,6 +122,7 @@ const DAEMON_DEFAULTS = {
 	connectTimeout: 3e4,
 	requestTimeout: 3e4,
 	healthCheckInterval: 3e4,
+	healthCheckTimeout: 1e4,
 	maxRestartAttempts: -1,
 	maxTotalTimeout: 3e5,
 	taskExpiryTimeout: 36e5,
@@ -698,6 +701,7 @@ var ServerManager = class {
 	stopped = false;
 	connectTimeout;
 	healthCheckInterval;
+	healthCheckTimeout;
 	maxRestartAttempts;
 	onHealthChange;
 	constructor(name, config, options) {
@@ -705,6 +709,7 @@ var ServerManager = class {
 		this.config = config;
 		this.connectTimeout = options?.connectTimeout;
 		this.healthCheckInterval = options?.healthCheckInterval ?? 3e4;
+		this.healthCheckTimeout = options?.healthCheckTimeout ?? 1e4;
 		this.maxRestartAttempts = options?.maxRestartAttempts ?? -1;
 	}
 	setHealthCallback(cb) {
@@ -911,7 +916,7 @@ var ServerManager = class {
 		if (!this.client || this.status !== "connected") return;
 		this.lastHealthCheck = /* @__PURE__ */ new Date();
 		try {
-			await this.client.ping();
+			await this.client.ping({ timeout: this.healthCheckTimeout });
 			if (this.consecutiveFailures > 0) getLogger().info(`Health check recovered after ${this.consecutiveFailures} failures`, this.name);
 			this.consecutiveFailures = 0;
 		} catch (err) {
@@ -966,10 +971,14 @@ var ServerManager = class {
 		if (!this.client) return;
 		this.tools = (await this.client.listTools()).tools;
 	}
+	ensureConnected() {
+		if (!this.client || this.status !== "connected") throw new Error(`Server "${this.name}" is not connected`);
+		return this.client;
+	}
 	async callTool(name, args, timeout) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
+		const client = this.ensureConnected();
 		const options = timeout ? { signal: AbortSignal.timeout(timeout) } : void 0;
-		return await this.client.callTool({
+		return await client.callTool({
 			name,
 			arguments: args
 		}, void 0, options);
@@ -982,8 +991,7 @@ var ServerManager = class {
 		this.resources = (await this.client.listResources()).resources;
 	}
 	async readResource(uri) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.readResource({ uri });
+		return await this.ensureConnected().readResource({ uri });
 	}
 	listPrompts() {
 		return this.prompts;
@@ -993,40 +1001,35 @@ var ServerManager = class {
 		this.prompts = (await this.client.listPrompts()).prompts;
 	}
 	async getPrompt(name, args) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.getPrompt({
+		return await this.ensureConnected().getPrompt({
 			name,
 			arguments: args
 		});
 	}
 	async complete(ref, argument) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
+		const client = this.ensureConnected();
 		if (!this.capabilities?.completions) throw new Error(`Server "${this.name}" does not support completions`);
-		return await this.client.complete({
+		return await client.complete({
 			ref,
 			argument
 		});
 	}
 	async listTasks(cursor) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
+		const client = this.ensureConnected();
 		if (!this.capabilities?.experimental?.tasks) throw new Error(`Server "${this.name}" does not support tasks`);
-		return await this.client.experimental.tasks.listTasks(cursor);
+		return await client.experimental.tasks.listTasks(cursor);
 	}
 	async getTask(taskId) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.experimental.tasks.getTask(taskId);
+		return await this.ensureConnected().experimental.tasks.getTask(taskId);
 	}
 	async getTaskResult(taskId) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.experimental.tasks.getTaskResult(taskId);
+		return await this.ensureConnected().experimental.tasks.getTaskResult(taskId);
 	}
 	async cancelTask(taskId) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.experimental.tasks.cancelTask(taskId);
+		return await this.ensureConnected().experimental.tasks.cancelTask(taskId);
 	}
 	async callToolWithTask(name, args) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		const stream = this.client.experimental.tasks.callToolStream({
+		const stream = this.ensureConnected().experimental.tasks.callToolStream({
 			name,
 			arguments: args
 		});
@@ -1180,6 +1183,7 @@ var ServerPool = class {
 			const manager = new ServerManager(name, serverConfig, {
 				connectTimeout: config.daemon?.connectTimeout,
 				healthCheckInterval: config.daemon?.healthCheckInterval,
+				healthCheckTimeout: config.daemon?.healthCheckTimeout,
 				maxRestartAttempts: config.daemon?.maxRestartAttempts
 			});
 			manager.setHealthCallback((serverName, status, error) => {
@@ -1481,6 +1485,7 @@ var ServerPool = class {
 			const manager = new ServerManager(name, serverConfig, {
 				connectTimeout: newConfig.daemon?.connectTimeout,
 				healthCheckInterval: newConfig.daemon?.healthCheckInterval,
+				healthCheckTimeout: newConfig.daemon?.healthCheckTimeout,
 				maxRestartAttempts: newConfig.daemon?.maxRestartAttempts
 			});
 			manager.setHealthCallback((serverName, status, error) => {
@@ -1496,6 +1501,7 @@ var ServerPool = class {
 				const newManager = new ServerManager(name, serverConfig, {
 					connectTimeout: newConfig.daemon?.connectTimeout,
 					healthCheckInterval: newConfig.daemon?.healthCheckInterval,
+					healthCheckTimeout: newConfig.daemon?.healthCheckTimeout,
 					maxRestartAttempts: newConfig.daemon?.maxRestartAttempts
 				});
 				newManager.setHealthCallback((serverName, status, error) => {
@@ -1639,6 +1645,240 @@ function filterFields(data, fields) {
 	}
 	return data;
 }
+const DEFAULT_BUDGET = 48e3;
+function isLeaf(schema) {
+	const type = schema.type;
+	if (type === "string" || type === "number" || type === "integer" || type === "boolean" || type === "null") {
+		if (!schema.anyOf && !schema.oneOf && !schema.allOf) return true;
+	}
+	if (schema.$ref) return true;
+	if (!schema.properties && !schema.items && !schema.additionalProperties && !schema.patternProperties && !schema.anyOf && !schema.oneOf && !schema.allOf && !schema.if && !schema.not) return true;
+	return false;
+}
+function buildHint(schema) {
+	const parts = [];
+	const props = schema.properties;
+	if (props) {
+		const count = Object.keys(props).length;
+		const required = schema.required;
+		if (required && required.length > 0) parts.push(`${count} properties, ${required.length} required`);
+		else parts.push(`${count} ${count === 1 ? "property" : "properties"}`);
+		return parts.join(", ");
+	}
+	if (schema.type === "object" && schema.additionalProperties) return `map<string, ${schema.additionalProperties.type ?? "unknown"}>`;
+	if (schema.items) {
+		const items = schema.items;
+		if (items.type === "object" && items.properties) {
+			const count = Object.keys(items.properties).length;
+			return `items: object (${count} ${count === 1 ? "property" : "properties"})`;
+		}
+		return `items: ${items.type ?? "unknown"}`;
+	}
+	for (const keyword of ["anyOf", "oneOf"]) {
+		const variants = schema[keyword];
+		if (variants) return `${keyword}: ${variants.length} variants`;
+	}
+	if (schema.allOf) return `allOf: ${schema.allOf.length} schemas`;
+	if (schema.enum) return `enum: ${schema.enum.length} values`;
+	return schema.type ?? "schema";
+}
+function buildCollapsedNode(schema) {
+	const result = {};
+	if (schema.type) result.type = schema.type;
+	if (schema.description) result.description = schema.description;
+	result._collapsed = true;
+	result._hint = buildHint(schema);
+	return result;
+}
+function collapseChild(schema, childDepth, maxDepth) {
+	if (typeof schema !== "object" || schema === null) return {
+		schema,
+		hasCollapsed: false
+	};
+	if (isLeaf(schema)) return {
+		schema,
+		hasCollapsed: false
+	};
+	if (childDepth > maxDepth) return {
+		schema: buildCollapsedNode(schema),
+		hasCollapsed: true
+	};
+	return collapseNode(schema, childDepth, maxDepth);
+}
+function collapseNode(schema, currentDepth, maxDepth) {
+	if (typeof schema !== "object" || schema === null) return {
+		schema,
+		hasCollapsed: false
+	};
+	if (isLeaf(schema)) return {
+		schema,
+		hasCollapsed: false
+	};
+	let hasCollapsed = false;
+	const result = {};
+	for (const [key, value] of Object.entries(schema)) switch (key) {
+		case "properties": {
+			const props = value;
+			const newProps = {};
+			for (const [propName, propSchema] of Object.entries(props)) {
+				const collapsed = collapseChild(propSchema, currentDepth + 1, maxDepth);
+				newProps[propName] = collapsed.schema;
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			}
+			result.properties = newProps;
+			break;
+		}
+		case "items": {
+			const collapsed = collapseChild(value, currentDepth + 1, maxDepth);
+			result.items = collapsed.schema;
+			if (collapsed.hasCollapsed) hasCollapsed = true;
+			break;
+		}
+		case "additionalProperties":
+			if (typeof value === "object" && value !== null) {
+				const collapsed = collapseChild(value, currentDepth + 1, maxDepth);
+				result.additionalProperties = collapsed.schema;
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			} else result.additionalProperties = value;
+			break;
+		case "patternProperties": {
+			const patterns = value;
+			const newPatterns = {};
+			for (const [pattern, patternSchema] of Object.entries(patterns)) {
+				const collapsed = collapseChild(patternSchema, currentDepth + 1, maxDepth);
+				newPatterns[pattern] = collapsed.schema;
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			}
+			result.patternProperties = newPatterns;
+			break;
+		}
+		case "anyOf":
+		case "oneOf":
+		case "allOf": {
+			const variants = value;
+			const newVariants = [];
+			for (const variant of variants) {
+				const collapsed = collapseNode(variant, currentDepth, maxDepth);
+				newVariants.push(collapsed.schema);
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			}
+			result[key] = newVariants;
+			break;
+		}
+		case "if":
+		case "then":
+		case "else":
+		case "not": {
+			const collapsed = collapseNode(value, currentDepth, maxDepth);
+			result[key] = collapsed.schema;
+			if (collapsed.hasCollapsed) hasCollapsed = true;
+			break;
+		}
+		case "$defs":
+		case "definitions": {
+			const defs = value;
+			const newDefs = {};
+			for (const [defName, defSchema] of Object.entries(defs)) {
+				const collapsed = collapseChild(defSchema, currentDepth + 1, maxDepth);
+				newDefs[defName] = collapsed.schema;
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			}
+			result[key] = newDefs;
+			break;
+		}
+		default: result[key] = value;
+	}
+	return {
+		schema: result,
+		hasCollapsed
+	};
+}
+function collapseSchema(schema, maxDepth) {
+	return collapseNode(schema, 0, Math.max(0, maxDepth));
+}
+function extractSubtree(schema, path) {
+	const segments = path.split(".");
+	let current = schema;
+	for (const segment of segments) {
+		if (!current || typeof current !== "object") return void 0;
+		const props = current.properties;
+		if (props && segment in props) {
+			current = props[segment];
+			continue;
+		}
+		if (segment === "items" && current.items) {
+			current = current.items;
+			continue;
+		}
+		if (segment === "additionalProperties" && typeof current.additionalProperties === "object") {
+			current = current.additionalProperties;
+			continue;
+		}
+		const index = parseInt(segment, 10);
+		if (!isNaN(index)) {
+			for (const keyword of [
+				"anyOf",
+				"oneOf",
+				"allOf"
+			]) {
+				const variants = current[keyword];
+				if (variants && index >= 0 && index < variants.length) {
+					current = variants[index];
+					break;
+				}
+			}
+			if (current !== schema) continue;
+		}
+		const patterns = current.patternProperties;
+		if (patterns && segment in patterns) {
+			current = patterns[segment];
+			continue;
+		}
+		return;
+	}
+	return current;
+}
+function autoDepth(schemas, budgetChars = DEFAULT_BUDGET) {
+	if (schemas.length === 0) return {
+		depth: 0,
+		fullyExpanded: true
+	};
+	let depth = 1;
+	let lastFit = 0;
+	let lastFullyExpanded = false;
+	const depth0 = schemas.map((s) => collapseSchema(s, 0));
+	const depth0Size = depth0.reduce((sum, r) => sum + JSON.stringify(r.schema).length, 0);
+	const depth0Expanded = depth0.every((r) => !r.hasCollapsed);
+	if (depth0Size > budgetChars) return {
+		depth: 0,
+		fullyExpanded: depth0Expanded
+	};
+	lastFit = 0;
+	lastFullyExpanded = depth0Expanded;
+	if (depth0Expanded) return {
+		depth: 0,
+		fullyExpanded: true
+	};
+	for (depth = 1; depth <= 20; depth++) {
+		const results = schemas.map((s) => collapseSchema(s, depth));
+		const totalSize = results.reduce((sum, r) => sum + JSON.stringify(r.schema).length, 0);
+		const fullyExpanded = results.every((r) => !r.hasCollapsed);
+		if (totalSize > budgetChars) return {
+			depth: lastFit,
+			fullyExpanded: lastFullyExpanded
+		};
+		lastFit = depth;
+		lastFullyExpanded = fullyExpanded;
+		if (fullyExpanded) return {
+			depth,
+			fullyExpanded: true
+		};
+	}
+	return {
+		depth: lastFit,
+		fullyExpanded: lastFullyExpanded
+	};
+}
 function createDaemonServer(serverPool, config) {
 	const socketPath = getSocketPath();
 	let idleTimer;
@@ -1667,11 +1907,37 @@ function createDaemonServer(serverPool, config) {
 				result: serverPool.listServers()
 			};
 			case "tools/list": {
-				const server = params?.server;
+				const p = params;
+				const tools = serverPool.listAllTools(p?.server);
+				if (p?.includeSchema) {
+					const schemas = tools.map(({ tool }) => tool.inputSchema ?? {});
+					const depth = p.schemaDepth ?? autoDepth(schemas, p.schemaBudget).depth;
+					return {
+						jsonrpc: "2.0",
+						id,
+						result: tools.map(({ server, tool }) => ({
+							server,
+							tool: {
+								name: tool.name,
+								title: tool.title,
+								description: tool.description,
+								annotations: tool.annotations,
+								inputSchema: collapseSchema(tool.inputSchema ?? {}, depth).schema
+							}
+						}))
+					};
+				}
 				return {
 					jsonrpc: "2.0",
 					id,
-					result: serverPool.listAllTools(server)
+					result: tools.map(({ server, tool }) => ({
+						server,
+						tool: {
+							name: tool.name,
+							title: tool.title,
+							annotations: tool.annotations
+						}
+					}))
 				};
 			}
 			case "tools/call": {
@@ -1764,10 +2030,34 @@ function createDaemonServer(serverPool, config) {
 						data: toErrorData(found.error)
 					}
 				};
+				let tool = found.tool;
+				if (p.path) {
+					const subtree = extractSubtree(tool.inputSchema ?? {}, p.path);
+					if (!subtree) return {
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32602,
+							message: `Path not found in schema: ${p.path}`,
+							data: {
+								code: "SCHEMA_PATH_NOT_FOUND",
+								path: p.path
+							}
+						}
+					};
+					tool = {
+						...tool,
+						inputSchema: subtree
+					};
+				}
+				if (p.schemaDepth !== void 0) tool = {
+					...tool,
+					inputSchema: collapseSchema(tool.inputSchema ?? {}, p.schemaDepth).schema
+				};
 				return {
 					jsonrpc: "2.0",
 					id,
-					result: found.tool
+					result: tool
 				};
 			}
 			case "tools/validate": {
@@ -1845,10 +2135,36 @@ function createDaemonServer(serverPool, config) {
 					}
 				};
 				try {
+					const matches = serverPool.grepTools(p.pattern);
+					if (p.includeSchema) {
+						const schemas = matches.map(({ tool }) => tool.inputSchema ?? {});
+						const depth = p.schemaDepth ?? autoDepth(schemas, p.schemaBudget).depth;
+						return {
+							jsonrpc: "2.0",
+							id,
+							result: matches.map(({ server, tool }) => ({
+								server,
+								tool: {
+									name: tool.name,
+									title: tool.title,
+									description: tool.description,
+									annotations: tool.annotations,
+									inputSchema: collapseSchema(tool.inputSchema ?? {}, depth).schema
+								}
+							}))
+						};
+					}
 					return {
 						jsonrpc: "2.0",
 						id,
-						result: serverPool.grepTools(p.pattern)
+						result: matches.map(({ server, tool }) => ({
+							server,
+							tool: {
+								name: tool.name,
+								title: tool.title,
+								annotations: tool.annotations
+							}
+						}))
 					};
 				} catch (err) {
 					return {
@@ -2536,16 +2852,32 @@ async function ensureDaemon(configPath) {
 		400
 	]);
 }
-async function sendRequest(method, params) {
+async function sendRequest(method, params, timeout = 9e4) {
 	const socketPath = getSocketPath();
 	return new Promise((resolve, reject) => {
 		const socket = net.createConnection(socketPath);
 		let buffer = "";
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			socket.destroy();
+			reject(/* @__PURE__ */ new Error(`Request timed out after ${timeout}ms`));
+		}, timeout);
 		socket.on("error", (err) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
 			if (err.code === "ENOENT") reject(/* @__PURE__ */ new Error("Daemon is not running. Run `muxed status` to check."));
 			else if (err.code === "ECONNREFUSED") reject(/* @__PURE__ */ new Error("Daemon may have crashed. Try running a command to auto-restart it."));
 			else reject(err);
 		});
+		socket.on("close", () => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error("Daemon closed the connection before sending a response"));
+		});
 		socket.on("connect", () => {
 			const request = {
 				jsonrpc: "2.0",
@@ -2559,6 +2891,9 @@ async function sendRequest(method, params) {
 			buffer += data.toString();
 			const newlineIndex = buffer.indexOf("\n");
 			if (newlineIndex === -1) return;
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
 			const line = buffer.slice(0, newlineIndex).trim();
 			socket.destroy();
 			try {
@@ -2604,7 +2939,6 @@ function formatTools(tools) {
 	return formatTable([
 		"Tool",
 		"Title",
-		"Description",
 		"Hints"
 	], tools.map(({ server, tool }) => {
 		const hints = [];
@@ -2614,7 +2948,6 @@ function formatTools(tools) {
 		return [
 			`${server}/${tool.name}`,
 			tool.title ?? "—",
-			truncate(tool.description ?? "", 60),
 			hints.join(" ")
 		];
 	}));
@@ -2848,6 +3181,24 @@ function formatInit(result) {
 		lines.push("");
 		lines.push("All discovered servers already exist in muxed config. Nothing to do.");
 	}
+	if (result.instructionResults && result.instructionResults.length > 0) {
+		lines.push("");
+		lines.push("Instructions:");
+		for (const r of result.instructionResults) switch (r.action) {
+			case "created":
+				lines.push(`  ${r.target} \u2014 created (v${r.newVersion})`);
+				break;
+			case "updated":
+				lines.push(`  ${r.target} \u2014 updated (v${r.previousVersion} \u2192 v${r.newVersion})`);
+				break;
+			case "up-to-date":
+				lines.push(`  ${r.target} \u2014 up-to-date (v${r.previousVersion})`);
+				break;
+			case "skipped":
+				lines.push(`  ${r.target} \u2014 skipped`);
+				break;
+		}
+	}
 	return lines.join("\n");
 }
 function formatMcpServer(name, config, scope) {
@@ -3016,20 +3367,27 @@ async function shutdown() {
 		if (_client) await _client.shutdown();
 	} catch {}
 }
-const toolsCommand = new Command("tools").description("List all available tools, optionally filtered by server name").argument("[server]", "Filter by server name").option("--json", "Output as JSON").action(async (server, opts) => {
+const toolsCommand = new Command("tools").description("List all available tools, optionally filtered by server name").argument("[server]", "Filter by server name").option("--json", "Output as JSON").option("--include <fields>", "Include additional fields (e.g. \"schema\")").option("--depth <n>", "Schema collapse depth (requires --include schema)", parseInt).action(async (server, opts) => {
 	const configPath = toolsCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
-	const result = await sendRequest("tools/list", server ? { server } : void 0);
+	const params = {};
+	if (server) params.server = server;
+	if (opts.include === "schema") params.includeSchema = true;
+	if (opts.depth !== void 0) params.schemaDepth = opts.depth;
+	const result = await sendRequest("tools/list", params);
 	capture("tools_listed", {
 		filtered_by_server: !!server,
 		tool_count: result.length
 	});
 	console.log(opts.json ? formatJson(result) : formatTools(result));
 });
-const infoCommand = new Command("info").description("Show input schema and description for a specific tool").argument("<server/tool>", "Tool identifier (e.g. myserver/mytool)").option("--json", "Output as JSON").action(async (serverTool, opts) => {
+const infoCommand = new Command("info").description("Show input schema and description for a specific tool").argument("<server/tool>", "Tool identifier (e.g. myserver/mytool)").option("--json", "Output as JSON").option("--path <path>", "Extract a subtree of the input schema (e.g. \"filters.tags\")").option("--depth <n>", "Collapse schema at this depth", parseInt).action(async (serverTool, opts) => {
 	const configPath = infoCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
-	const result = await sendRequest("tools/info", { name: serverTool });
+	const params = { name: serverTool };
+	if (opts.path) params.path = opts.path;
+	if (opts.depth !== void 0) params.schemaDepth = opts.depth;
+	const result = await sendRequest("tools/info", params);
 	if (opts.json) console.log(formatJson(result));
 	else {
 		const slashIndex = serverTool.indexOf("/");
@@ -3187,10 +3545,13 @@ const callCommand = new Command("call").description("Execute a tool with JSON ar
 		process.exit(1);
 	}
 });
-const grepCommand = new Command("grep").description("Search tools by regex pattern across names, titles, and descriptions").argument("<pattern>", "Regex pattern to search").option("--json", "Output as JSON").action(async (pattern, opts) => {
+const grepCommand = new Command("grep").description("Search tools by regex pattern across names, titles, and descriptions").argument("<pattern>", "Regex pattern to search").option("--json", "Output as JSON").option("--include <fields>", "Include additional fields (e.g. \"schema\")").option("--depth <n>", "Schema collapse depth (requires --include schema)", parseInt).action(async (pattern, opts) => {
 	const configPath = grepCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
-	const result = await sendRequest("tools/grep", { pattern });
+	const params = { pattern };
+	if (opts.include === "schema") params.includeSchema = true;
+	if (opts.depth !== void 0) params.schemaDepth = opts.depth;
+	const result = await sendRequest("tools/grep", params);
 	capture("tools_searched", { result_count: result.length });
 	console.log(opts.json ? formatJson(result) : formatTools(result));
 });
@@ -3665,6 +4026,261 @@ function getMuxedConfigPath(scope, explicitPath) {
 	if (scope === "local") return path.join(process.cwd(), "muxed.config.json");
 	return path.join(home, ".muxed", "config.json");
 }
+let cached = null;
+function getVersion() {
+	if (cached) return cached;
+	const dir = path.dirname(fileURLToPath(import.meta.url));
+	for (const rel of ["../package.json", "../../package.json"]) {
+		const p = path.resolve(dir, rel);
+		try {
+			const pkg = JSON.parse(fs.readFileSync(p, "utf-8"));
+			if (pkg.name === "muxed" && pkg.version) {
+				cached = pkg.version;
+				return cached;
+			}
+		} catch {}
+	}
+	return "0.0.0";
+}
+function compareSemver(a, b) {
+	const pa = a.split(".").map(Number);
+	const pb = b.split(".").map(Number);
+	for (let i = 0; i < 3; i++) {
+		const na = pa[i] ?? 0;
+		const nb = pb[i] ?? 0;
+		if (na < nb) return -1;
+		if (na > nb) return 1;
+	}
+	return 0;
+}
+const MUXED_BLOCK_RE = /<muxed\s+version="([^"]+)">\n?([\s\S]*?)\n?<\/muxed>/;
+const MDC_VERSION_RE = /muxed_version:\s*(.+)/;
+function extractMuxedVersion(content, format) {
+	if (format === "tagged") return content.match(MUXED_BLOCK_RE)?.[1]?.trim() ?? null;
+	const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+	if (!fmMatch) return null;
+	return fmMatch[1].match(MDC_VERSION_RE)?.[1]?.trim() ?? null;
+}
+function getInstructionTargets(opts) {
+	const home = os.homedir();
+	const cwd = process.cwd();
+	const targets = [];
+	targets.push({
+		name: "CLAUDE.md (global)",
+		filePath: path.join(home, ".claude", "CLAUDE.md"),
+		format: "tagged",
+		scope: "global"
+	});
+	targets.push({
+		name: "AGENTS.md (global)",
+		filePath: path.join(home, ".codex", "AGENTS.md"),
+		format: "tagged",
+		scope: "global"
+	});
+	const cursorDir = path.join(cwd, ".cursor");
+	if (fs.existsSync(cursorDir)) targets.push({
+		name: ".cursor/rules/muxed.mdc",
+		filePath: path.join(cursorDir, "rules", "muxed.mdc"),
+		format: "owned",
+		scope: "local"
+	});
+	if (opts.local) {
+		targets.push({
+			name: "CLAUDE.md (local)",
+			filePath: path.join(cwd, "CLAUDE.md"),
+			format: "tagged",
+			scope: "local"
+		});
+		targets.push({
+			name: "AGENTS.md (local)",
+			filePath: path.join(cwd, "AGENTS.md"),
+			format: "tagged",
+			scope: "local"
+		});
+	}
+	return targets;
+}
+let cachedHasBun = null;
+function hasBun() {
+	if (cachedHasBun !== null) return cachedHasBun;
+	try {
+		execSync("bun --version", { stdio: "ignore" });
+		cachedHasBun = true;
+	} catch {
+		cachedHasBun = false;
+	}
+	return cachedHasBun;
+}
+function buildStaticInstructions() {
+	const bun = hasBun();
+	const run = bun ? "bunx" : "npx";
+	return `# Muxed — MCP Server Aggregator
+
+Muxed is a CLI tool and Node.js library that aggregates multiple MCP servers behind a single daemon. Use it to discover and call MCP tools on demand.
+
+## CLI Usage
+
+### Mandatory Workflow
+
+**ALWAYS follow this order — never skip the inspect step.**
+
+1. **Discover** tools:
+   \`\`\`
+   ${run} muxed grep "<pattern>"              # Search tool names and descriptions
+   ${run} muxed tools [server]                # List available tools
+   \`\`\`
+
+2. **Inspect** schema (REQUIRED before calling):
+   \`\`\`
+   ${run} muxed info <server>/<tool>          # View tool JSON schema
+   \`\`\`
+
+3. **Call** with correct parameters:
+   \`\`\`
+   ${run} muxed call <server>/<tool> '<json>' # Execute a tool
+   \`\`\`
+
+Tool names and parameter schemas change frequently and cannot be guessed. Every call without inspecting the schema first will fail.
+
+### Additional Commands
+
+\`\`\`
+${run} muxed servers                           # List connected MCP servers
+${run} muxed resources [server]                # List MCP resources
+${run} muxed read <server>/<resource>          # Read an MCP resource
+${run} muxed call <s>/<t> '<j>' --dry-run      # Validate args without executing
+${run} muxed call <s>/<t> '<j>' --fields "a,b" # Extract specific fields
+${run} muxed -h                                # Full command reference
+\`\`\`
+
+### Error Handling
+
+- If a tool call fails, read the error — it includes suggestions and similar tool names.
+- Use \`--dry-run\` to validate arguments before executing destructive tools.
+
+## Node.js / TypeScript Scripts (Preferred for Complex Workflows)
+
+For multi-step MCP workflows, **write and execute a script** instead of making individual CLI calls. A single script execution replaces many sequential CLI invocations — dramatically reducing round-trips and token usage.
+
+\`\`\`typescript
+import { createClient } from 'muxed/client';
+
+const client = await createClient();
+
+// Batch multiple MCP operations in one script execution
+const tools = await client.tools();
+const result = await client.call('server/tool', { param: 'value' });
+const data = await client.call('db/query', { sql: 'SELECT ...' });
+
+// Process results, chain calls, handle errors — all in one execution
+console.log(JSON.stringify({ tools: tools.length, result, data }));
+\`\`\`
+
+Run scripts with: \`${bun ? "bun" : "npx tsx"} script.ts\`.
+
+**When to use scripts vs CLI:**
+- **CLI** (\`${run} muxed call ...\`) — single tool discovery or one-off calls
+- **Scripts** — any workflow involving 2+ MCP calls, data processing, or conditional logic`;
+}
+function wrapTaggedBlock(content, version) {
+	return `<muxed version="${version}">\n${content}\n</muxed>`;
+}
+function buildMdcFile(content, version) {
+	return `---
+description: Muxed MCP server aggregator - CLI usage instructions
+globs:
+alwaysApply: true
+muxed_version: ${version}
+---
+
+${content}
+`;
+}
+function injectInstructions(target, instructions, version, opts) {
+	const base = {
+		target: target.name,
+		filePath: target.filePath
+	};
+	let existing = null;
+	if (fs.existsSync(target.filePath)) existing = fs.readFileSync(target.filePath, "utf-8");
+	if (target.format === "owned") {
+		if (existing !== null) {
+			const existingVersion = extractMuxedVersion(existing, "owned");
+			if (existingVersion && compareSemver(existingVersion, version) >= 0) return {
+				...base,
+				action: "up-to-date",
+				previousVersion: existingVersion
+			};
+			if (!opts.dryRun) {
+				const dir = path.dirname(target.filePath);
+				if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+				fs.writeFileSync(target.filePath, buildMdcFile(instructions, version));
+			}
+			return {
+				...base,
+				action: existingVersion ? "updated" : "created",
+				previousVersion: existingVersion ?? void 0,
+				newVersion: version
+			};
+		}
+		if (!opts.dryRun) {
+			const dir = path.dirname(target.filePath);
+			if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+			fs.writeFileSync(target.filePath, buildMdcFile(instructions, version));
+		}
+		return {
+			...base,
+			action: "created",
+			newVersion: version
+		};
+	}
+	const block = wrapTaggedBlock(instructions, version);
+	if (existing === null) {
+		if (!opts.dryRun) {
+			const dir = path.dirname(target.filePath);
+			if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+			fs.writeFileSync(target.filePath, block + "\n");
+		}
+		return {
+			...base,
+			action: "created",
+			newVersion: version
+		};
+	}
+	const existingVersion = extractMuxedVersion(existing, "tagged");
+	if (existingVersion !== null) {
+		if (compareSemver(existingVersion, version) >= 0) return {
+			...base,
+			action: "up-to-date",
+			previousVersion: existingVersion
+		};
+		if (!opts.dryRun) {
+			const updated = existing.replace(MUXED_BLOCK_RE, block);
+			fs.writeFileSync(target.filePath, updated);
+		}
+		return {
+			...base,
+			action: "updated",
+			previousVersion: existingVersion,
+			newVersion: version
+		};
+	}
+	if (!opts.dryRun) {
+		const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+		fs.writeFileSync(target.filePath, existing + separator + block + "\n");
+	}
+	return {
+		...base,
+		action: "created",
+		newVersion: version
+	};
+}
+function injectAllInstructions(opts) {
+	const targets = getInstructionTargets({ local: opts.local });
+	const instructions = buildStaticInstructions();
+	const version = getVersion();
+	return targets.map((target) => injectInstructions(target, instructions, version, opts));
+}
 async function confirm(message, opts) {
 	const rl = readline.createInterface({
 		input: opts?.input ?? process.stdin,
@@ -3732,7 +4348,7 @@ async function resolveConflicts(unresolvedConflicts, isInteractive) {
 		conflicts
 	};
 }
-const initCommand = new Command("init").description("Discover and import MCP servers from agent configs (Claude Code, Cursor)").option("--dry-run", "Show what would be done without writing files").option("--json", "Output as JSON").option("-y, --yes", "Skip prompts; resolve conflicts by priority (claude-code > cursor > first)").option("--no-delete", "Keep original server entries in agent configs").option("--no-replace", "Don't add muxed entry to agent configs").action(async (opts) => {
+const initCommand = new Command("init").description("Discover and import MCP servers from agent configs (Claude Code, Cursor)").option("--dry-run", "Show what would be done without writing files").option("--json", "Output as JSON").option("-y, --yes", "Skip prompts; resolve conflicts by priority (claude-code > cursor > first)").option("--delete", "Remove imported servers from original agent configs").option("--no-replace", "Don't add muxed entry to agent configs").option("--local", "Also inject instructions into local agent files (CLAUDE.md, AGENTS.md)").option("--no-instructions", "Skip injecting CLI instructions into agent files").action(async (opts) => {
 	const configPath = initCommand.parent?.opts().config;
 	const isInteractive = !opts.dryRun && !opts.json && !opts.yes && !!process.stdin.isTTY;
 	const { discovered, warnings } = discoverAgentConfigs();
@@ -3755,7 +4371,7 @@ const initCommand = new Command("init").description("Discover and import MCP ser
 	}
 	if (!opts.dryRun && imported.length > 0) writeMuxedConfig(muxedPath, result.merged);
 	const modifiedFiles = [];
-	const shouldDelete = isInteractive ? await confirm("Remove imported servers from agent config files? (backups will be created)") : opts.delete;
+	const shouldDelete = isInteractive ? await confirm("Remove imported servers from agent config files? (backups will be created)") : !!opts.delete;
 	if (!opts.dryRun && shouldDelete) for (const dc of discovered) try {
 		modifyAgentConfig(dc, {
 			delete: true,
@@ -3765,6 +4381,10 @@ const initCommand = new Command("init").description("Discover and import MCP ser
 	} catch (err) {
 		warnings.push(`Failed to modify ${dc.configPath}: ${err instanceof Error ? err.message : String(err)}`);
 	}
+	const instructionResults = (isInteractive ? await confirm("Inject muxed CLI instructions into agent files? (CLAUDE.md, AGENTS.md)") : opts.instructions) ? injectAllInstructions({
+		local: !!opts.local,
+		dryRun: !!opts.dryRun
+	}) : [];
 	const initResult = {
 		discovered: discovered.map((d) => ({
 			agent: d.agent.name,
@@ -3778,14 +4398,17 @@ const initCommand = new Command("init").description("Discover and import MCP ser
 		warnings,
 		modifiedFiles,
 		muxedConfigPath: muxedPath,
-		dryRun: opts.dryRun ?? false
+		dryRun: opts.dryRun ?? false,
+		instructionResults
 	};
 	capture("init_run", {
 		dry_run: opts.dryRun ?? false,
 		imported_count: imported.length,
 		conflict_count: conflicts.length,
 		warning_count: warnings.length,
-		discovered_agents: initResult.discovered.map((d) => d.agent)
+		discovered_agents: initResult.discovered.map((d) => d.agent),
+		instruction_targets: instructionResults.length,
+		instruction_actions: instructionResults.map((r) => r.action)
 	});
 	console.log(opts.json ? formatJson(initResult) : formatInit(initResult));
 });
@@ -3842,7 +4465,10 @@ const cliFragments = {
 	intro: "You have access to an `npx muxed` CLI command for interacting with MCP (Model Context Protocol) servers. This command allows you to discover and call MCP tools on demand. Prioritize the use of skills over MCP tools.",
 	grep: (p) => `npx muxed grep "${p}"`,
 	tools: (s) => s ? `npx muxed tools ${s}` : "npx muxed tools",
+	toolsSchema: (s) => s ? `npx muxed tools ${s} --include schema` : "npx muxed tools --include schema",
 	info: (n) => `npx muxed info ${n}`,
+	infoDepth: (n, d) => `npx muxed info ${n} --depth ${d}`,
+	infoPath: (n, p) => `npx muxed info ${n} --path ${p}`,
 	call: (n, j) => `npx muxed call ${n} '${j}'`,
 	callStdin: (n) => `npx muxed call ${n} -`,
 	callDryRun: (n, j) => `npx muxed call ${n} '${j}' --dry-run`,
@@ -3856,7 +4482,10 @@ const toolFragments = {
 	intro: "You have access to a `muxed:exec` MCP tool for interacting with MCP (Model Context Protocol) servers. This tool allows you to discover and call MCP tools on demand. Prioritize the use of skills over MCP tools.",
 	grep: (p) => `muxed:exec({ "command": "grep ${p}" })`,
 	tools: (s) => s ? `muxed:exec({ "command": "tools ${s}" })` : `muxed:exec({ "command": "tools" })`,
+	toolsSchema: (s) => s ? `muxed:exec({ "command": "tools ${s} --include schema" })` : `muxed:exec({ "command": "tools --include schema" })`,
 	info: (n) => `muxed:exec({ "command": "info ${n}" })`,
+	infoDepth: (n, d) => `muxed:exec({ "command": "info ${n} --depth ${d}" })`,
+	infoPath: (n, p) => `muxed:exec({ "command": "info ${n} --path ${p}" })`,
 	call: (n, j) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
 	callStdin: (n) => `muxed:exec({ "command": "call ${n}", "input": { ... } })`,
 	callDryRun: (n, j) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
@@ -3898,15 +4527,23 @@ Commands (in order of execution):
 ${f.grep("<pattern>")}                 # Search tool names and descriptions
 ${f.tools("[server]")}                 # List available tools (optionally filter by server)
 
-# STEP 2: ALWAYS CHECK SCHEMA FIRST (MANDATORY)
-${f.info("<server>/<tool>")}           # REQUIRED before ANY call - View JSON schema
+# STEP 2: GET SCHEMA (choose one approach)
+# Option A: Include schemas in tool listing (auto-collapses to fit 48k budget)
+${f.toolsSchema("[server]")}           # List tools with schemas included
+# Option B: Get full schema for a specific tool
+${f.info("<server>/<tool>")}           # View full JSON schema for one tool
+
+# STEP 2b: PROGRESSIVE SCHEMA EXPLORATION (for large schemas)
+${f.infoDepth("<server>/<tool>", 1)}   # Collapse schema at depth 1 (top-level overview)
+${f.infoPath("<server>/<tool>", "filters")}  # Extract just the 'filters' subtree
+${f.infoPath("<server>/<tool>", "filters.tags.items")}  # Drill deeper into nested schemas
 
 # STEP 3: OPTIONAL - Validate arguments before calling (dry-run)
 ${f.callDryRun("<server>/<tool>", "<json>")}  # Validate args without executing
 
-# STEP 4: Only after checking schema, make the call
-${f.call("<server>/<tool>", "<json>")}  # Only run AFTER info
-${f.callStdin("<server>/<tool>")}       # Invoke with JSON input (AFTER info)
+# STEP 4: Only after getting the schema, make the call
+${f.call("<server>/<tool>", "<json>")}  # Only run AFTER getting schema
+${f.callStdin("<server>/<tool>")}       # Invoke with JSON input
 ${f.callFields("<server>/<tool>", "<json>", "field1,field2")}  # Extract specific fields from response
 
 # Discovery commands (use these to find tools)
@@ -3984,8 +4621,15 @@ Example usage:
 ${f.tools()}                          # See all available MCP tools
 ${f.grep("weather")}                  # Find tools by description
 
-# Get tool details
-${f.info("<server>/<tool>")}          # View JSON schema for input and output if available
+# Get tool schemas (choose the approach that fits)
+${f.toolsSchema()}                    # All tools with schemas (auto-collapses large schemas)
+${f.toolsSchema("slack")}             # Schemas for one server
+${f.info("<server>/<tool>")}          # Full schema for one tool
+
+# Progressive schema exploration (for complex tools)
+${f.infoDepth("<server>/<tool>", 0)}  # Top-level structure only
+${f.infoPath("<server>/<tool>", "filters")}  # Drill into a subtree
+${f.infoPath("<server>/<tool>", "filters.tags.items")}  # Drill deeper
 
 # Simple tool call (no parameters)
 ${f.call("weather/get_location", "{}")}
@@ -4025,6 +4669,22 @@ function parseCommand(command) {
 		args: trimmed.slice(spaceIndex + 1).trim()
 	};
 }
+function parseFlags(args) {
+	const flags = {};
+	const positionalParts = [];
+	const parts = args.split(/\s+/);
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (part.startsWith("--") && i + 1 < parts.length) {
+			const key = part.slice(2);
+			flags[key] = parts[++i];
+		} else positionalParts.push(part);
+	}
+	return {
+		positional: positionalParts.join(" "),
+		flags
+	};
+}
 function textResult(data) {
 	return { content: [{
 		type: "text",
@@ -4046,16 +4706,31 @@ async function handleToolCommand(command, input) {
 		switch (subcommand) {
 			case "servers": return textResult(await sendRequest("servers/list"));
 			case "tools": {
+				const { positional, flags } = parseFlags(args);
 				const params = {};
-				if (args) params.server = args;
+				if (positional) params.server = positional;
+				if (flags.include === "schema") params.includeSchema = true;
+				if (flags.depth) params.schemaDepth = parseInt(flags.depth, 10);
 				return textResult(await sendRequest("tools/list", params));
 			}
-			case "grep":
+			case "grep": {
 				if (!args) return errorResult("Usage: grep <pattern>");
-				return textResult(await sendRequest("tools/grep", { pattern: args }));
-			case "info":
-				if (!args) return errorResult("Usage: info <server/tool>");
-				return textResult(await sendRequest("tools/info", { name: args }));
+				const { positional, flags } = parseFlags(args);
+				if (!positional) return errorResult("Usage: grep <pattern>");
+				const params = { pattern: positional };
+				if (flags.include === "schema") params.includeSchema = true;
+				if (flags.depth) params.schemaDepth = parseInt(flags.depth, 10);
+				return textResult(await sendRequest("tools/grep", params));
+			}
+			case "info": {
+				if (!args) return errorResult("Usage: info <server/tool> [--path <path>] [--depth <n>]");
+				const { positional, flags } = parseFlags(args);
+				if (!positional) return errorResult("Usage: info <server/tool>");
+				const params = { name: positional };
+				if (flags.path) params.path = flags.path;
+				if (flags.depth) params.schemaDepth = parseInt(flags.depth, 10);
+				return textResult(await sendRequest("tools/info", params));
+			}
 			case "call": {
 				if (!args) return errorResult("Usage: call <server/tool>");
 				const result = await sendRequest("tools/call", {
@@ -4390,7 +5065,7 @@ const telemetryCommand = new Command("telemetry").description("Manage anonymous
 });
 async function runCli() {
 	const program = new Command();
-	program.name("muxed").description("The optimization layer for MCP").version("0.1.0");
+	program.name("muxed").description("The optimization layer for MCP").version(getVersion());
 	program.enablePositionalOptions();
 	program.option("--config <path>", "Path to config file");
 	program.commandsGroup("Servers:");