efaimo 0.1.0

package/dist/check/check.js

@@ -0,0 +1,77 @@
+import path from "node:path";
+import { countBySeverity, gradeFindings, sortFindings } from "../core/grade.js";
+import { runMcpRules, runRules } from "../core/engine.js";
+import { isReadinessRuleId } from "../rules/mcp/index.js";
+import { SKILL_RULES } from "../rules/skill/index.js";
+import { introspectServer } from "../clients/introspect.js";
+import { runProbes } from "../clients/rawprobe.js";
+import { scanRepo } from "../targets/repoScan.js";
+import { findSkills } from "../skills/parse.js";
+import { weighServer, weighSkills } from "../weigh/weigh.js";
+import { VERSION } from "../version.js";
+function buildReport(surface, target, findings, notes) {
+    // MCP readiness findings (E101-E118) are a migration diff for a spec that is
+    // not final until 2026-07-28; they are reported separately and never graded.
+    const readinessAll = [];
+    const gradedAll = [];
+    for (const f of findings) {
+        (surface === "mcp" && isReadinessRuleId(f.ruleId) ? readinessAll : gradedAll).push(f);
+    }
+    const graded = sortFindings(gradedAll);
+    const readiness = sortFindings(readinessAll);
+    return {
+        tool: "efaimo",
+        version: VERSION,
+        surface,
+        target,
+        findings: graded,
+        counts: countBySeverity(graded),
+        grade: gradeFindings(graded),
+        ...(surface === "mcp" ? { readiness: { findings: readiness, counts: countBySeverity(readiness) } } : {}),
+        notes,
+    };
+}
+export async function checkMcpTarget(target, opts = {}) {
+    const intro = await introspectServer(target, { timeoutMs: opts.timeoutMs });
+    const weigh = await weighServer(intro, { anthropicApiKey: opts.anthropicApiKey });
+    const probes = opts.probe === false ? undefined : await runProbes(target, { timeoutMs: opts.timeoutMs });
+    const repo = opts.repoPath ? scanRepo(opts.repoPath) : undefined;
+    const findings = runMcpRules({ intro, probes, repo, weigh });
+    const notes = [...intro.notes];
+    if (opts.probe === false)
+        notes.push("readiness probes skipped (--no-probe)");
+    if (repo)
+        notes.push(`repo scan: ${repo.filesScanned} files in ${repo.root}`);
+    return { report: buildReport("mcp", target.label, findings, notes), intro, weigh, probes };
+}
+export function checkMcpRepoOnly(repoPath, label) {
+    const repo = scanRepo(repoPath);
+    const emptyIntro = {
+        targetLabel: label,
+        transport: "stdio",
+        tools: [],
+        resources: [],
+        prompts: [],
+        notes: [],
+    };
+    const findings = runMcpRules({ intro: emptyIntro, repo });
+    return buildReport("mcp", label, findings, [
+        `static repo scan only (${repo.filesScanned} files); run against the live server for transport, probe, and quality checks`,
+    ]);
+}
+export async function checkSkillSet(pathInput, label) {
+    const set = findSkills(pathInput);
+    if (!set.skills.length) {
+        throw new Error(`no SKILL.md found under "${pathInput}"`);
+    }
+    const weigh = await weighSkills(set);
+    const perSkillRules = SKILL_RULES.filter((r) => r.id !== "S103");
+    const setRules = SKILL_RULES.filter((r) => r.id === "S103");
+    const perSkill = set.skills.map((skill) => {
+        const name = skill.name ?? path.basename(skill.dir);
+        const findings = runRules(perSkillRules, { skill, set, weigh });
+        return { name, dir: skill.dir, report: buildReport("skill", name, findings, []) };
+    });
+    const setFindings = set.skills.flatMap((skill) => runRules(setRules, { skill, set, weigh }));
+    return { label, root: set.root, perSkill, setFindings, weigh };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import crossSpawn from "cross-spawn";
+import { Command } from "commander";
+import pc from "picocolors";
+import { VERSION } from "./version.js";
+import { resolveTarget } from "./targets/resolve.js";
+import { loadClientServers, SUPPORTED_CLIENTS } from "./targets/clientConfigs.js";
+import { introspectServer } from "./clients/introspect.js";
+import { weighServer, weighSkills } from "./weigh/weigh.js";
+import { findSkills } from "./skills/parse.js";
+import { diffServerWeigh } from "./weigh/diff.js";
+import { checkMcpRepoOnly, checkMcpTarget, checkSkillSet } from "./check/check.js";
+import { renderCheckPretty, renderDiffPretty, renderScenarioPlan, renderServerWeighPretty, renderSkillSetPretty, renderSkillWeighPretty, renderTestReportPretty, setColor, } from "./reporters/pretty.js";
+import { parseScenario, runScenario } from "./testing/harness.js";
+import { anthropicRunner } from "./testing/anthropicRunner.js";
+import { openaiRunner, providerForModel } from "./testing/openaiRunner.js";
+import { toJsonEnvelope } from "./reporters/json.js";
+import { renderCheckMarkdown, renderDiffMarkdown, renderSkillSetMarkdown, renderWeighMarkdown } from "./reporters/markdown.js";
+import { gradeBadgeSpec, makeBadgeSvg, toShieldsEndpoint, weighBadgeSpec } from "./reporters/badge.js";
+import { loadDotEnv } from "./util/dotenv.js";
+// Load a local .env before any command reads a key. Shell env always wins.
+const dotEnvKeys = new Set(loadDotEnv());
+const program = new Command();
+program
+    .name("efaimo")
+    .description("Audit what your agent loads: quality and context cost for MCP servers and Agent Skills")
+    .version(VERSION)
+    .addHelpText("after", `
+examples:
+  $ npx efaimo weigh "npx -y @modelcontextprotocol/server-everything"
+  $ npx efaimo weigh https://mcp.example.com/mcp
+  $ npx efaimo weigh ./my-skill
+  $ npx efaimo weigh --client claude-code
+  $ npx efaimo check --mcp "npx -y my-mcp-server"      # incl. 2026-07-28 readiness
+  $ npx efaimo check --skill ./skills/
+  $ npx efaimo weigh "npx -y my-server" --out base.json && npx efaimo weigh "npx -y my-server" --diff base.json
+`);
+function collectPairs(sep) {
+    return (value, prev = {}) => {
+        const idx = value.indexOf(sep);
+        if (idx === -1)
+            throw new Error(`expected "KEY${sep}VALUE", got "${value}"`);
+        return { ...prev, [value.slice(0, idx).trim()]: value.slice(idx + 1).trim() };
+    };
+}
+function colorSetup(opts) {
+    setColor(opts.color !== false && process.env.NO_COLOR === undefined);
+}
+function fail(message) {
+    console.error(pc.red(`error: ${message}`));
+    process.exit(2);
+}
+function writeBadge(fileArg, spec) {
+    if (!fileArg)
+        return;
+    const file = typeof fileArg === "string" ? fileArg : "efaimo-badge.svg";
+    fs.writeFileSync(file, makeBadgeSvg(spec.label, spec.message, spec.color));
+    const jsonFile = file.replace(/\.svg$/i, "") + ".json";
+    fs.writeFileSync(jsonFile, toShieldsEndpoint(spec));
+    console.error(pc.dim(`badge written: ${file}, ${jsonFile}`));
+}
+function seconds(value, label = "--timeout") {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        fail(`${label} must be a positive number of seconds, got "${value}"`);
+    return n;
+}
+function parseNumberOpt(value, label) {
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        fail(`${label} must be a number, got "${value}"`);
+    return n;
+}
+function anthropicKeyFor(opts) {
+    if (!opts.anthropic)
+        return {};
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+        fail("--anthropic needs ANTHROPIC_API_KEY in the environment or a .env file");
+    return { apiKey, model: typeof opts.anthropic === "string" ? opts.anthropic : undefined };
+}
+program
+    .command("weigh")
+    .description("measure the context cost of MCP tool definitions or Agent Skills")
+    .argument("[target]", "stdio command | http(s) URL | skill path")
+    .option("--client <name>", `weigh every server configured for a client (${SUPPORTED_CLIENTS.join(", ")})`)
+    .option("--stdio", "treat target as a stdio command string")
+    .option("--skill", "treat target as a skill path")
+    .option("--header <header>", 'HTTP header "Key: Value" (repeatable)', collectPairs(":"))
+    .option("--env <pair>", "KEY=VALUE for stdio servers (repeatable)", collectPairs("="))
+    .option("--timeout <seconds>", "connect timeout in seconds", "45")
+    .option("--json", "print JSON")
+    .option("--md", "print Markdown")
+    .option("--out <file>", "write the JSON result to a file (usable as a --diff baseline)")
+    .option("--diff <baseline>", "compare against a baseline JSON from --out")
+    .option("--max-tokens <n>", "exit 1 if the primary total exceeds n tokens")
+    .option("--allow-increase <pct>", "with --diff: exit 1 if the increase exceeds pct percent")
+    .option("--badge [file]", "write an SVG badge + shields endpoint JSON")
+    .option("--anthropic [model]", "also measure exact Claude tokens via the count_tokens API (needs ANTHROPIC_API_KEY)")
+    .option("--no-color", "disable colors")
+    .action(async (targetArg, opts) => {
+    colorSetup(opts);
+    const timeoutMs = seconds(opts.timeout) * 1000;
+    const maxTokens = parseNumberOpt(opts.maxTokens, "--max-tokens");
+    const allowIncreasePct = parseNumberOpt(opts.allowIncrease, "--allow-increase");
+    const anthropic = anthropicKeyFor(opts);
+    const targets = [];
+    if (opts.client) {
+        const conf = loadClientServers(opts.client);
+        if (!conf.entries.length) {
+            fail(`no MCP servers found for client "${opts.client}" (checked: ${[...conf.sources, ...conf.missing].join(", ")})`);
+        }
+        console.error(pc.dim(`config: ${conf.sources.join(", ")}`));
+        targets.push(...conf.entries.map((e) => e.target));
+    }
+    if (targetArg) {
+        targets.push(resolveTarget(targetArg, {
+            forceStdio: opts.stdio,
+            forceSkill: opts.skill,
+            env: opts.env,
+            headers: opts.header,
+        }));
+    }
+    if (!targets.length)
+        fail("nothing to weigh: pass a target or --client <name> (see --help)");
+    const results = [];
+    const skipped = [];
+    for (const target of targets) {
+        if (target.kind === "skillset") {
+            const set = findSkills(target.path);
+            if (!set.skills.length)
+                fail(`no SKILL.md found under "${target.label}"`);
+            results.push(await weighSkills(set));
+        }
+        else if (target.kind === "repo") {
+            fail(`"${target.label}" is a source directory; weigh needs a live server (stdio command or URL) or a skill path. For repo checks use: efaimo check --mcp ${target.label}`);
+        }
+        else {
+            console.error(pc.dim(`connecting to ${target.label} ...`));
+            try {
+                const intro = await introspectServer(target, { timeoutMs });
+                results.push(await weighServer(intro, { anthropicApiKey: anthropic.apiKey, anthropicModel: anthropic.model }));
+            }
+            catch (e) {
+                // One broken/auth-gated server must not abort a multi-server run
+                // (--client weighs everything an editor loads; some entries need auth).
+                if (targets.length === 1)
+                    throw e;
+                const reason = (e instanceof Error ? e.message : String(e)).split("\n")[0].trim();
+                skipped.push({ label: target.label, reason });
+                console.error(pc.yellow(`skipped ${target.label}: ${reason}`));
+            }
+        }
+    }
+    if (!results.length) {
+        fail(`no server could be weighed (${skipped.length} of ${targets.length} failed; see reasons above)`);
+    }
+    // "Single" means the user asked for exactly one target, not that exactly
+    // one target survived: a multi-target run with skips must not silently
+    // write/diff a baseline or emit a single-object JSON for whichever server
+    // happened to work.
+    const single = targets.length === 1 && results.length === 1 ? results[0] : undefined;
+    const budgetTotal = results.reduce((s, r) => s + (r.kind === "mcp" ? r.totals.claudeStyle : r.totals.metadata + r.totals.body), 0);
+    if (opts.out && single) {
+        fs.writeFileSync(opts.out, toJsonEnvelope("weigh", single));
+        console.error(pc.dim(`baseline written: ${opts.out}`));
+    }
+    else if (opts.out) {
+        console.error(pc.yellow("--out skipped: it writes a single baseline, but multiple targets were requested"));
+    }
+    if (opts.json) {
+        console.log(toJsonEnvelope("weigh", single ?? results));
+    }
+    else if (opts.md) {
+        console.log(results.map(renderWeighMarkdown).join("\n\n---\n\n"));
+    }
+    else {
+        console.log(results
+            .map((r) => (r.kind === "mcp" ? renderServerWeighPretty(r) : renderSkillWeighPretty(r)))
+            .join("\n\n"));
+        if (results.length > 1) {
+            const mcpTotals = results
+                .filter((r) => r.kind === "mcp")
+                .reduce((s, r) => s + r.totals.claudeStyle, 0);
+            if (mcpTotals > 0) {
+                console.log(pc.bold(`\ncombined MCP context cost (Claude-style, o200k est.): ${mcpTotals.toLocaleString("en-US")} tokens (~${((mcpTotals / 200000) * 100).toFixed(1)}% of a 200k window)`));
+            }
+        }
+    }
+    if (skipped.length) {
+        console.error(pc.yellow(`weighed ${results.length} of ${targets.length} servers; skipped: ${skipped.map((s) => s.label).join(", ")}`));
+    }
+    if (opts.diff) {
+        if (!single || single.kind !== "mcp")
+            fail("--diff works on a single MCP server result");
+        const baselineRaw = JSON.parse(fs.readFileSync(opts.diff, "utf8"));
+        const baseline = ("data" in baselineRaw && baselineRaw.data ? baselineRaw.data : baselineRaw);
+        if (!baseline?.totals)
+            fail(`"${opts.diff}" is not a weigh baseline (write one with --out)`);
+        const d = diffServerWeigh(baseline, single);
+        console.log("");
+        console.log(opts.md ? renderDiffMarkdown(d) : renderDiffPretty(d, { maxTokens, allowIncreasePct }));
+        if ((allowIncreasePct !== undefined && d.pct > allowIncreasePct) ||
+            (maxTokens !== undefined && d.after > maxTokens)) {
+            process.exitCode = 1;
+        }
+    }
+    else if (maxTokens !== undefined && budgetTotal > maxTokens) {
+        const scope = single ? "" : " (combined)";
+        console.error(pc.red(`budget exceeded${scope}: ${budgetTotal.toLocaleString("en-US")} > --max-tokens ${maxTokens}`));
+        process.exitCode = 1;
+    }
+    if (single)
+        writeBadge(opts.badge, weighBadgeSpec(single));
+});
+program
+    .command("check")
+    .description("audit quality and 2026-07-28 readiness of an MCP server, or lint Agent Skills")
+    .argument("[target]", "stdio command | http(s) URL | skill path | repo dir")
+    .option("--mcp", "treat target as an MCP server / server repo")
+    .option("--skill", "treat target as a skill path")
+    .option("--stdio", "treat target as a stdio command string")
+    .option("--repo <path>", "additionally scan this source repo for deprecated API usage")
+    .option("--no-probe", "skip live readiness probes (bare request, server/discover, ordering)")
+    .option("--strict", "exit 1 on warnings too")
+    .option("--conformance", "after the audit, run the official MCP conformance suite (http targets)")
+    .option("--header <header>", 'HTTP header "Key: Value" (repeatable)', collectPairs(":"))
+    .option("--env <pair>", "KEY=VALUE for stdio servers (repeatable)", collectPairs("="))
+    .option("--timeout <seconds>", "connect timeout in seconds", "45")
+    .option("--json", "print JSON")
+    .option("--md", "print Markdown")
+    .option("--badge [file]", "write a grade badge SVG + shields endpoint JSON")
+    .option("--anthropic [model]", "use exact Claude token counts where relevant")
+    .option("--no-color", "disable colors")
+    .action(async (targetArg, opts) => {
+    colorSetup(opts);
+    if (!targetArg)
+        fail("nothing to check: pass a target (see --help)");
+    if (opts.mcp && opts.skill)
+        fail("--mcp and --skill are mutually exclusive");
+    const timeoutMs = seconds(opts.timeout) * 1000;
+    const anthropic = anthropicKeyFor(opts);
+    let target = resolveTarget(targetArg, {
+        forceStdio: opts.stdio,
+        forceSkill: opts.skill,
+        forceRepo: false,
+        env: opts.env,
+        headers: opts.header,
+    });
+    if (opts.mcp && target.kind === "skillset") {
+        target = { kind: "repo", path: target.path, label: target.label };
+    }
+    let report;
+    let skillSet;
+    if (target.kind === "skillset") {
+        const res = await checkSkillSet(target.path, target.label);
+        // A single skill shows a full report; a set shows per-skill grades.
+        if (res.perSkill.length === 1 && res.setFindings.length === 0)
+            report = res.perSkill[0].report;
+        else
+            skillSet = res;
+    }
+    else if (target.kind === "repo") {
+        report = checkMcpRepoOnly(target.path, target.label);
+    }
+    else {
+        console.error(pc.dim(`connecting to ${target.label} ...`));
+        const res = await checkMcpTarget(target, {
+            timeoutMs,
+            probe: opts.probe,
+            repoPath: opts.repo,
+            anthropicApiKey: anthropic.apiKey,
+        });
+        report = res.report;
+    }
+    if (skillSet) {
+        if (opts.json)
+            console.log(toJsonEnvelope("check", skillSet));
+        else if (opts.md)
+            console.log(renderSkillSetMarkdown(skillSet));
+        else
+            console.log(renderSkillSetPretty(skillSet));
+        const errs = skillSet.perSkill.reduce((n, s) => n + s.report.counts.error, 0) +
+            skillSet.setFindings.filter((f) => f.severity === "error").length;
+        const warns = skillSet.perSkill.reduce((n, s) => n + s.report.counts.warn, 0) +
+            skillSet.setFindings.filter((f) => f.severity === "warn").length;
+        if (errs > 0 || (opts.strict && warns > 0))
+            process.exitCode = 1;
+        return;
+    }
+    if (!report)
+        return;
+    if (opts.json)
+        console.log(toJsonEnvelope("check", report));
+    else if (opts.md)
+        console.log(renderCheckMarkdown(report));
+    else
+        console.log(renderCheckPretty(report));
+    writeBadge(opts.badge, gradeBadgeSpec(report));
+    if (opts.conformance) {
+        if (target.kind !== "http") {
+            console.error(pc.yellow("note: the official conformance suite drives http targets (--url); skipping for this target"));
+        }
+        else {
+            console.error(pc.dim("\nrunning official MCP conformance suite (npx @modelcontextprotocol/conformance)...\n"));
+            // cross-spawn resolves npx(.cmd) without a shell, so target.url is passed
+            // as a literal argument (never interpreted by cmd.exe).
+            const r = crossSpawn.sync("npx", ["-y", "@modelcontextprotocol/conformance", "server", "--url", target.url], {
+                stdio: "inherit",
+            });
+            if (r.status !== 0)
+                console.error(pc.yellow(`conformance suite exited with code ${r.status ?? "unknown"}`));
+        }
+    }
+    if (report.counts.error > 0 || (opts.strict && report.counts.warn > 0)) {
+        process.exitCode = 1;
+    }
+});
+program
+    .command("test")
+    .description("does a skill actually improve task completion? (experimental A/B outcome harness)")
+    .argument("<scenario>", "a scenario YAML file (see examples/scenario.example.yaml)")
+    .option("--live", "run for real (spends tokens; Claude models need ANTHROPIC_API_KEY, GPT models need OPENAI_API_KEY)")
+    .option("--model <model>", "override the scenario's model (e.g. gpt-4o-mini, claude-sonnet-5)")
+    .option("--json", "print JSON")
+    .option("--no-color", "disable colors")
+    .addHelpText("after", "\nWithout --live this validates the scenario and prints the plan, making no API calls.")
+    .action(async (file, opts) => {
+    colorSetup(opts);
+    const parsed = parseScenario(file);
+    const scenario = opts.model ? { ...parsed, model: opts.model } : parsed;
+    if (!opts.live) {
+        console.log(renderScenarioPlan(scenario));
+        return;
+    }
+    const provider = providerForModel(scenario.model);
+    if (provider === "unknown") {
+        fail(`model "${scenario.model}" is not supported: efaimo test runs Claude (claude-*) and OpenAI (gpt-*, o*) models`);
+    }
+    const envVar = provider === "openai" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY";
+    const apiKey = process.env[envVar];
+    if (!apiKey)
+        fail(`model "${scenario.model}" needs ${envVar} in the environment or a .env file`);
+    if (dotEnvKeys.has(envVar))
+        console.error(pc.dim(`using ${envVar} from .env`));
+    const runner = provider === "openai" ? openaiRunner(apiKey) : anthropicRunner(apiKey);
+    console.error(pc.dim(`running ~${scenario.trials * 4} ${provider} API calls against ${scenario.model} ...`));
+    const report = await runScenario(scenario, runner);
+    if (opts.json)
+        console.log(toJsonEnvelope("test", report));
+    else
+        console.log(renderTestReportPretty(report));
+    if (report.verdict === "hurts")
+        process.exitCode = 1;
+});
+program
+    .command("mcp")
+    .description("run efaimo as a read-only MCP server (exposes the skill checks to an agent over stdio)")
+    .addHelpText("after", "\nStarts a stdio MCP server with two read-only tools, efaimo_check_skill and efaimo_weigh_skill,\n" +
+    "so an agent can lint or weigh a skill mid-session. It reads files only: no process is spawned,\n" +
+    "no socket is opened, and `test` (which spends tokens) is not exposed.")
+    .action(async () => {
+    const { runMcpServer } = await import("./mcp/server.js");
+    await runMcpServer();
+});
+program.parseAsync(process.argv).catch((e) => {
+    console.error(pc.red(`error: ${e instanceof Error ? e.message : String(e)}`));
+    process.exitCode = 2;
+});

package/dist/clients/introspect.d.ts

@@ -0,0 +1,8 @@
+import type { ServerIntrospection } from "../core/types.js";
+import type { ResolvedTarget } from "../targets/resolve.js";
+export interface IntrospectOptions {
+    timeoutMs?: number;
+}
+export declare function introspectServer(target: Extract<ResolvedTarget, {
+    kind: "stdio" | "http";
+}>, opts?: IntrospectOptions): Promise<ServerIntrospection>;

package/dist/clients/introspect.js

@@ -0,0 +1,198 @@
+import crossSpawn from "cross-spawn";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { introspectStateless } from "./stateless.js";
+import { minimalChildEnv } from "../util/childEnv.js";
+import { truncate, withTimeout } from "../util/misc.js";
+import { VERSION } from "../version.js";
+const MAX_PAGES = 20;
+export async function introspectServer(target, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 45000;
+    const notes = [];
+    let stderrTail = "";
+    let transport;
+    let httpTransport;
+    const client = new Client({ name: "efaimo", version: VERSION }, { capabilities: {} });
+    if (target.kind === "stdio") {
+        const stdio = new StdioClientTransport({
+            command: target.command,
+            args: target.args,
+            env: target.env ? { ...minimalChildEnv(), ...target.env } : undefined,
+            stderr: "pipe",
+        });
+        transport = stdio;
+        try {
+            await withTimeout(client.connect(stdio), timeoutMs, "connect (stdio)");
+        }
+        catch (e) {
+            await safeClose(client, stdio);
+            // A 2026-07-28 stateless server has no initialize, so the SDK handshake
+            // fails by design; try bare stateless requests before giving up.
+            const rc = await introspectStateless(target, { timeoutMs });
+            if (rc)
+                return rc;
+            throw connectError(e, target.label, stderrTail);
+        }
+        // The child is spawned by connect(); its stderr stream only exists now.
+        const errStream = stdio.stderr;
+        errStream?.on("data", (chunk) => {
+            if (stderrTail.length < 2048)
+                stderrTail += chunk.toString("utf8");
+        });
+    }
+    else {
+        const url = new URL(target.url);
+        // redirect:"error" so a hostile target cannot bounce an authenticated request
+        // to an internal host and replay the user's --header credentials.
+        const requestInit = { redirect: "error", ...(target.headers ? { headers: target.headers } : {}) };
+        const streamable = new StreamableHTTPClientTransport(url, { requestInit });
+        try {
+            await withTimeout(client.connect(streamable), timeoutMs, "connect (streamable http)");
+            transport = streamable;
+            httpTransport = "streamable";
+        }
+        catch (streamableErr) {
+            await safeClose(client, streamable);
+            const sse = new SSEClientTransport(url, { requestInit });
+            const sseClient = new Client({ name: "efaimo", version: VERSION }, { capabilities: {} });
+            try {
+                await withTimeout(sseClient.connect(sse), timeoutMs, "connect (legacy sse)");
+            }
+            catch {
+                await safeClose(sseClient, sse);
+                // Neither SDK transport connected; a stateless RC server rejects the
+                // initialize both send. Try bare stateless requests before giving up.
+                const rc = await introspectStateless(target, { timeoutMs });
+                if (rc)
+                    return rc;
+                throw connectError(streamableErr, target.label, "");
+            }
+            notes.push("connected via legacy HTTP+SSE transport (deprecated; Streamable HTTP failed)");
+            return finishIntrospection(sseClient, sse, target.label, "http", "sse-legacy", notes, timeoutMs);
+        }
+        return finishIntrospection(client, transport, target.label, "http", httpTransport, notes, timeoutMs);
+    }
+    if (stderrTail.trim())
+        notes.push(`server stderr: ${truncate(stderrTail.trim(), 300)}`);
+    return finishIntrospection(client, transport, target.label, "stdio", undefined, notes, timeoutMs);
+}
+async function finishIntrospection(client, transport, label, kind, httpTransport, notes, timeoutMs) {
+    try {
+        const tools = [];
+        let rawToolsListResult;
+        let cursor;
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const res = await withTimeout(client.listTools(cursor ? { cursor } : undefined), timeoutMs, "tools/list");
+            if (page === 0)
+                rawToolsListResult = res;
+            for (const t of res.tools) {
+                tools.push({
+                    name: t.name,
+                    title: t.title,
+                    description: t.description,
+                    inputSchema: t.inputSchema,
+                    outputSchema: t.outputSchema,
+                    annotations: t.annotations,
+                });
+            }
+            cursor = res.nextCursor;
+            if (!cursor)
+                break;
+            if (page === MAX_PAGES - 1)
+                notes.push(`tools/list pagination stopped at ${MAX_PAGES} pages`);
+        }
+        const serverInfo = client.getServerVersion();
+        const capabilities = client.getServerCapabilities();
+        const instructions = client.getInstructions();
+        // Only call resources/prompts when the server declares them, and surface a
+        // note (rather than silently swallowing) if a declared capability fails.
+        const resources = [];
+        if (capabilities?.resources) {
+            try {
+                let rCursor;
+                for (let page = 0; page < MAX_PAGES; page++) {
+                    const res = await withTimeout(client.listResources(rCursor ? { cursor: rCursor } : undefined), timeoutMs, "resources/list");
+                    for (const r of res.resources) {
+                        resources.push({ uri: r.uri, name: r.name, description: r.description, mimeType: r.mimeType });
+                    }
+                    rCursor = res.nextCursor;
+                    if (!rCursor)
+                        break;
+                }
+            }
+            catch (e) {
+                notes.push(`resources/list failed: ${e.message}`);
+            }
+        }
+        const prompts = [];
+        if (capabilities?.prompts) {
+            try {
+                let pCursor;
+                for (let page = 0; page < MAX_PAGES; page++) {
+                    const res = await withTimeout(client.listPrompts(pCursor ? { cursor: pCursor } : undefined), timeoutMs, "prompts/list");
+                    for (const p of res.prompts) {
+                        prompts.push({ name: p.name, title: p.title, description: p.description });
+                    }
+                    pCursor = res.nextCursor;
+                    if (!pCursor)
+                        break;
+                }
+            }
+            catch (e) {
+                notes.push(`prompts/list failed: ${e.message}`);
+            }
+        }
+        return {
+            targetLabel: label,
+            transport: kind,
+            httpTransport,
+            serverInfo: serverInfo
+                ? { name: serverInfo.name, version: serverInfo.version, title: serverInfo.title }
+                : undefined,
+            instructions,
+            capabilities,
+            tools,
+            resources,
+            prompts,
+            rawToolsListResult,
+            notes,
+        };
+    }
+    finally {
+        // On Windows the SDK's close() kills only the cmd.exe wrapper for npx/.cmd
+        // servers; tree-kill the child first so the real server is not orphaned.
+        const pid = transport.pid;
+        if (pid && process.platform === "win32") {
+            try {
+                crossSpawn.sync("taskkill", ["/PID", String(pid), "/T", "/F"], { stdio: "ignore" });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        await safeClose(client, transport);
+    }
+}
+async function safeClose(client, transport) {
+    try {
+        await client.close();
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        await transport.close();
+    }
+    catch {
+        /* ignore */
+    }
+}
+function connectError(e, label, stderrTail) {
+    const base = e instanceof Error ? e.message : String(e);
+    const hint = stderrTail.trim()
+        ? `\n  server stderr: ${truncate(stderrTail.trim(), 400)}`
+        : "";
+    return new Error(`could not connect to "${label}": ${base}${hint}\n  hints: check the command/URL, required env vars or auth headers; try --timeout for slow cold starts (npx downloads on first run).`);
+}