@ait-co/devtools 0.1.33 → 0.1.35

package/dist/mcp/cli.js

@@ -8,27 +8,30 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { EventEmitter } from "node:events";
 import { WebSocket } from "ws";
 import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import net from "node:net";
+import { platform } from "node:os";
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { Tunnel, bin, install } from "cloudflared";
-import qrcode from "qrcode-terminal";
 //#region src/mcp/ait-chii-source.ts
-function isObject$2(value) {
+function isObject$3(value) {
 	return typeof value === "object" && value !== null;
 }
 /** Narrows an `AIT.getSdkCallHistory` response, tolerating a missing array. */
 function asSdkCallHistory(raw) {
-	if (isObject$2(raw) && Array.isArray(raw.calls)) return { calls: raw.calls };
+	if (isObject$3(raw) && Array.isArray(raw.calls)) return { calls: raw.calls };
 	return { calls: [] };
 }
 /** Narrows an `AIT.getMockState` response to an opaque record. */
 function asMockState(raw) {
-	return isObject$2(raw) ? raw : {};
+	return isObject$3(raw) ? raw : {};
 }
 /** Narrows an `AIT.getOperationalEnvironment` response. */
 function asOperationalEnvironment(raw) {
 	return {
-		environment: isObject$2(raw) && typeof raw.environment === "string" ? raw.environment : "unknown",
-		sdkVersion: isObject$2(raw) && typeof raw.sdkVersion === "string" ? raw.sdkVersion : null
+		environment: isObject$3(raw) && typeof raw.environment === "string" ? raw.environment : "unknown",
+		sdkVersion: isObject$3(raw) && typeof raw.sdkVersion === "string" ? raw.sdkVersion : null
 	};
 }
 var ChiiAitSource = class {
@@ -61,27 +64,27 @@ var ChiiAitSource = class {
 * Node-only: imports `ws`. Never bundled into the browser/in-app entries.
 */
 /** Max events retained per domain ring buffer. */
-const DEFAULT_BUFFER_SIZE = 500;
-function isObject$1(value) {
+const DEFAULT_BUFFER_SIZE$1 = 500;
+function isObject$2(value) {
 	return typeof value === "object" && value !== null;
 }
-function parseInbound(raw) {
+function parseInbound$1(raw) {
 	let parsed;
 	try {
 		parsed = JSON.parse(raw);
 	} catch {
 		return null;
 	}
-	if (!isObject$1(parsed)) return null;
+	if (!isObject$2(parsed)) return null;
 	const message = {};
 	if (typeof parsed.id === "number") message.id = parsed.id;
 	if (typeof parsed.method === "string") message.method = parsed.method;
 	if ("params" in parsed) message.params = parsed.params;
 	if ("result" in parsed) message.result = parsed.result;
-	if (isObject$1(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
+	if (isObject$2(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
 	return message;
 }
-const PHASE_1_EVENTS = [
+const PHASE_1_EVENTS$1 = [
 	"Runtime.consoleAPICalled",
 	"Network.requestWillBeSent",
 	"Network.responseReceived"
@@ -104,8 +107,8 @@ var ChiiCdpConnection = class {
 	pending = /* @__PURE__ */ new Map();
 	constructor(options) {
 		this.relayBaseUrl = options.relayBaseUrl.replace(/\/$/, "");
-		this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;
-		for (const event of PHASE_1_EVENTS) this.buffers.set(event, []);
+		this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE$1;
+		for (const event of PHASE_1_EVENTS$1) this.buffers.set(event, []);
 		this.emitter.setMaxListeners(0);
 	}
 	/** Refresh the attached-target list from the relay's `GET /targets`. */
@@ -113,10 +116,10 @@ var ChiiCdpConnection = class {
 		const res = await fetch(`${this.relayBaseUrl}/targets`);
 		if (!res.ok) throw new Error(`Chii relay /targets returned HTTP ${res.status} ${res.statusText}`);
 		const body = await res.json();
-		const list = isObject$1(body) && Array.isArray(body.targets) ? body.targets : [];
+		const list = isObject$2(body) && Array.isArray(body.targets) ? body.targets : [];
 		this.targets.clear();
 		for (const item of list) {
-			if (!isObject$1(item) || typeof item.id !== "string") continue;
+			if (!isObject$2(item) || typeof item.id !== "string") continue;
 			this.targets.set(item.id, {
 				id: item.id,
 				title: typeof item.title === "string" ? item.title : "",
@@ -194,7 +197,7 @@ var ChiiCdpConnection = class {
 		});
 	}
 	handleMessage(raw) {
-		const message = parseInbound(raw);
+		const message = parseInbound$1(raw);
 		if (!message) return;
 		if (typeof message.id === "number" && this.pending.has(message.id)) {
 			const waiter = this.pending.get(message.id);
@@ -263,9 +266,24 @@ function loadChiiServer() {
 	if (typeof mod === "object" && mod !== null && "start" in mod && typeof mod.start === "function") return mod;
 	throw new Error("chii server module did not expose start()");
 }
-/** Starts the Chii relay on the given port and resolves once listening. */
+/**
+* Starts the Chii relay and resolves once listening.
+*
+* Default port is 0 (OS-assigned). With port 0 the OS picks a free ephemeral
+* port on every start, so a stale cloudflared orphan holding any particular
+* port cannot cause EADDRINUSE. The resolved `ChiiRelay.port` and `baseUrl`
+* always reflect the actual bound port.
+*
+* chii.start() is called with `server` (our pre-created httpServer) BEFORE
+* httpServer.listen(). This is intentional: chii attaches its Koa handler and
+* WS upgrade listener to the server object, but the actual TCP bind is
+* performed by our httpServer.listen() call below. The `port`/`domain` values
+* passed to chii.start() are used for display/banner purposes inside chii and
+* do not affect which port the server binds. The connection path (clients
+* connecting to `relay.baseUrl`) always uses the post-listen confirmed port.
+*/
 async function startChiiRelay(options = {}) {
-	const port = options.port ?? 9100;
+	const requestedPort = options.port ?? 0;
 	const host = options.host ?? "127.0.0.1";
 	const { verifyAuth } = options;
 	const httpServer = createServer();
@@ -278,26 +296,423 @@ async function startChiiRelay(options = {}) {
 	});
 	await loadChiiServer().start({
 		server: httpServer,
-		domain: `${host}:${port}`,
-		port
+		domain: `${host}:${requestedPort}`,
+		port: requestedPort
 	});
-	await new Promise((resolve, reject) => {
+	const actualPort = await new Promise((resolve, reject) => {
 		httpServer.once("error", reject);
-		httpServer.listen(port, host, () => {
+		httpServer.listen(requestedPort, host, () => {
 			httpServer.off("error", reject);
-			resolve();
+			resolve(httpServer.address().port);
 		});
 	});
 	return {
-		port,
-		baseUrl: `http://${host}:${port}`,
+		port: actualPort,
+		baseUrl: `http://${host}:${actualPort}`,
 		close: () => new Promise((resolve) => {
 			httpServer.close(() => resolve());
 		})
 	};
 }
 //#endregion
+//#region src/mcp/local-connection.ts
+/**
+* Local-browser `CdpConnection` — attaches directly to a Chromium instance
+* started with `--remote-debugging-port=<port>`.
+*
+* Topology (local debug mode, env 1):
+*   Chromium  --CDP WS-->  this connection  <--stdio-->  MCP host
+*
+* The core insight: local Chromium and the phone's Toss WebView both speak
+* Chrome DevTools Protocol. The only difference is the attach strategy — how
+* you reach the CDP endpoint. Here we hit the Chromium DevTools HTTP endpoint
+* (`GET /json`) to discover per-target websocket URLs, then connect directly.
+* The Chii relay (env 2/3) uses `GET /targets` + `/client/<id>?target=<id>`.
+* Every tool (list_console_messages, get_dom_document, take_screenshot, …)
+* reads only the `CdpConnection` interface and works unchanged on both.
+*
+* Node-only: imports `ws`. Never bundled into the browser/in-app entries.
+*/
+/** Max events retained per domain ring buffer. */
+const DEFAULT_BUFFER_SIZE = 500;
+function isObject$1(value) {
+	return typeof value === "object" && value !== null;
+}
+function parseInbound(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!isObject$1(parsed)) return null;
+	const message = {};
+	if (typeof parsed.id === "number") message.id = parsed.id;
+	if (typeof parsed.method === "string") message.method = parsed.method;
+	if ("params" in parsed) message.params = parsed.params;
+	if ("result" in parsed) message.result = parsed.result;
+	if (isObject$1(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
+	return message;
+}
+const PHASE_1_EVENTS = [
+	"Runtime.consoleAPICalled",
+	"Network.requestWillBeSent",
+	"Network.responseReceived"
+];
+/**
+* `CdpConnection` that attaches directly to a local Chromium over its built-in
+* CDP websocket. Mirrors `ChiiCdpConnection`'s buffering/command-routing/event
+* logic — same `parseInbound`, ring-buffer, `pending` map patterns — but the
+* attach strategy differs:
+*
+*   Chii relay: `GET /targets` → open `/client/<id>?target=<id>` WS
+*   Local CDP:  `GET /json`    → open `webSocketDebuggerUrl` per target directly
+*
+* Target selection: first `type === 'page'` target whose URL is not
+* `about:blank`, `about:newtab`, or a devtools:// URL.
+*/
+var LocalCdpConnection = class {
+	devtoolsHttpUrl;
+	bufferSize;
+	emitter = new EventEmitter();
+	buffers = /* @__PURE__ */ new Map();
+	targets = /* @__PURE__ */ new Map();
+	ws = null;
+	nextCommandId = 1;
+	/** In-flight enableDomains() promise — concurrent callers share it. */
+	enablingPromise = null;
+	/** Pending request→response commands keyed by CDP message id. */
+	pending = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.devtoolsHttpUrl = options.devtoolsHttpUrl.replace(/\/$/, "");
+		this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;
+		for (const event of PHASE_1_EVENTS) this.buffers.set(event, []);
+		this.emitter.setMaxListeners(0);
+	}
+	/**
+	* Fetch the target list from the Chromium DevTools `/json` (or `/json/list`)
+	* endpoint and pick the first non-blank page target.
+	*
+	* Returns the selected target's `webSocketDebuggerUrl` alongside the
+	* normalized `CdpTarget` list (all page targets visible to the server).
+	*/
+	async fetchTargets() {
+		const res = await fetch(`${this.devtoolsHttpUrl}/json`);
+		if (!res.ok) throw new Error(`Chromium DevTools /json returned HTTP ${res.status} ${res.statusText}. Is the browser running with --remote-debugging-port?`);
+		const body = await res.json();
+		const list = Array.isArray(body) ? body : [];
+		this.targets.clear();
+		let selected = null;
+		for (const item of list) {
+			if (!isObject$1(item) || typeof item.id !== "string") continue;
+			const cdpTarget = {
+				id: item.id,
+				title: typeof item.title === "string" ? item.title : "",
+				url: typeof item.url === "string" ? item.url : ""
+			};
+			this.targets.set(item.id, cdpTarget);
+			if (selected === null && item.type === "page" && typeof item.webSocketDebuggerUrl === "string" && !isBlankOrDevtoolsUrl(item.url)) selected = item;
+		}
+		return {
+			selected,
+			all: [...this.targets.values()]
+		};
+	}
+	listTargets() {
+		return [...this.targets.values()];
+	}
+	/**
+	* Discover the target, open a direct CDP websocket to its
+	* `webSocketDebuggerUrl`, and enable Phase 1+2 domains. Resolves once the
+	* socket is open and domain-enable commands are sent. Idempotent — concurrent
+	* callers share the in-flight promise.
+	*/
+	async enableDomains() {
+		if (this.ws && this.ws.readyState === WebSocket.OPEN) return;
+		if (this.enablingPromise) return this.enablingPromise;
+		this.enablingPromise = this._doEnableDomains().finally(() => {
+			this.enablingPromise = null;
+		});
+		return this.enablingPromise;
+	}
+	async _doEnableDomains() {
+		const { selected } = await this.fetchTargets();
+		if (!selected) throw new Error("No suitable page target found in the local Chromium instance. Ensure the browser has a non-blank page open and was started with --remote-debugging-port matching devtoolsHttpUrl.");
+		const wsUrl = selected.webSocketDebuggerUrl;
+		const ws = new WebSocket(wsUrl);
+		this.ws = ws;
+		await new Promise((resolve, reject) => {
+			ws.once("open", () => resolve());
+			ws.once("error", (err) => reject(err));
+		});
+		ws.on("message", (data) => this.handleMessage(data.toString()));
+		this.sendFireAndForget("Runtime.enable");
+		this.sendFireAndForget("Network.enable");
+		this.sendFireAndForget("DOM.enable");
+		this.sendFireAndForget("Page.enable");
+	}
+	/** Fire-and-forget CDP message (used for `*.enable`, no result awaited). */
+	sendFireAndForget(method, params = {}) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+		const id = this.nextCommandId++;
+		this.ws.send(JSON.stringify({
+			id,
+			method,
+			params
+		}));
+	}
+	/**
+	* Issue a CDP command and resolve with its typed result. Rejects on a CDP
+	* error frame or when no websocket is open.
+	*/
+	send(method, params) {
+		return this.sendCommand(method, params ?? {});
+	}
+	/**
+	* Issue an arbitrary request→response command and resolve with its raw
+	* result. Both the typed CDP `send` and any AIT domain commands build on this.
+	*/
+	sendCommand(method, params = {}) {
+		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return Promise.reject(/* @__PURE__ */ new Error("No local Chromium page attached yet. Call enableDomains() first and ensure the browser is running with --remote-debugging-port."));
+		const id = this.nextCommandId++;
+		const ws = this.ws;
+		return new Promise((resolve, reject) => {
+			this.pending.set(id, {
+				resolve,
+				reject
+			});
+			ws.send(JSON.stringify({
+				id,
+				method,
+				params
+			}));
+		});
+	}
+	handleMessage(raw) {
+		const message = parseInbound(raw);
+		if (!message) return;
+		if (typeof message.id === "number" && this.pending.has(message.id)) {
+			const waiter = this.pending.get(message.id);
+			this.pending.delete(message.id);
+			if (waiter) if (message.error) waiter.reject(new Error(message.error.message));
+			else waiter.resolve(message.result);
+			return;
+		}
+		if (typeof message.method !== "string") return;
+		if (!this.buffers.has(message.method)) return;
+		const event = message.method;
+		const buffer = this.buffers.get(event);
+		if (!buffer) return;
+		buffer.push(message.params);
+		if (buffer.length > this.bufferSize) buffer.shift();
+		this.emitter.emit(event, message.params);
+	}
+	getBufferedEvents(event) {
+		return this.buffers.get(event) ?? [];
+	}
+	on(event, listener) {
+		this.emitter.on(event, listener);
+		return () => this.emitter.off(event, listener);
+	}
+	/** Close the local CDP websocket and reject any in-flight commands. */
+	close() {
+		this.ws?.close();
+		this.ws = null;
+		for (const waiter of this.pending.values()) waiter.reject(/* @__PURE__ */ new Error("Local Chromium CDP connection closed."));
+		this.pending.clear();
+	}
+};
+/** True for URLs that should be skipped when selecting a page target. */
+function isBlankOrDevtoolsUrl(url) {
+	return url === "" || url === "about:blank" || url === "about:newtab" || url.startsWith("devtools://") || url.startsWith("chrome://") || url.startsWith("chrome-extension://");
+}
+//#endregion
+//#region src/mcp/local-launcher.ts
+/**
+* Chromium launcher for the local debug mode (env 1).
+*
+* Launch decision rationale:
+*   - `chrome-launcher` (npm) is purpose-built and finds installed Chrome, but
+*     adds a runtime dependency to the MCP bundle. The repo already has a clear
+*     "external dependency minimization" policy; `chrome-launcher` is not worth
+*     pulling in for what is essentially `spawn(chromeBin, [...flags])`.
+*   - Playwright is a devDependency used for E2E only — pulling `chromium.launch`
+*     into the runtime MCP path would add ~100 MB of bundled Chromium to the
+*     production install and break the "devDep = e2e only" boundary.
+*   - `child_process.spawn` with a platform-aware binary search is the lightest
+*     option: zero new dependencies, portable across macOS/Linux/Windows, and
+*     trivially testable by injecting a `spawnFn`.
+*
+* The launcher finds an installed Chrome/Chromium using a prioritized list of
+* well-known binary paths per platform, then spawns it with:
+*   --remote-debugging-port=<port>
+*   --no-first-run
+*   --no-default-browser-check
+*   <devUrl>
+*
+* `pnpm dev` is started by the user; the MCP only launches the browser pointing
+* at it.
+*
+* Node-only.
+*/
+/**
+* Find an ephemeral free TCP port by briefly binding a server on port 0.
+* Resolves with the OS-assigned port number.
+*/
+function findFreePort() {
+	return new Promise((resolve, reject) => {
+		const server = net.createServer();
+		server.listen(0, "127.0.0.1", () => {
+			const addr = server.address();
+			const port = typeof addr === "object" && addr !== null ? addr.port : null;
+			server.close(() => {
+				if (port === null) reject(/* @__PURE__ */ new Error("Failed to determine free port from net.Server."));
+				else resolve(port);
+			});
+		});
+		server.once("error", reject);
+	});
+}
+/**
+* Returns an ordered list of Chromium/Chrome binary paths to try for the
+* current platform.
+*/
+function candidateChromePaths() {
+	const os = platform();
+	if (os === "darwin") return [
+		"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+		"/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+		"/Applications/Chromium.app/Contents/MacOS/Chromium",
+		"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+	];
+	if (os === "linux") return [
+		"/usr/bin/google-chrome",
+		"/usr/bin/google-chrome-stable",
+		"/usr/bin/chromium",
+		"/usr/bin/chromium-browser",
+		"/usr/local/bin/google-chrome",
+		"/usr/local/bin/chromium",
+		"/snap/bin/chromium"
+	];
+	if (os === "win32") {
+		const programFiles = process.env.PROGRAMFILES ?? "C:\\Program Files";
+		const programFilesX86 = process.env["PROGRAMFILES(X86)"] ?? "C:\\Program Files (x86)";
+		return [
+			`${programFiles}\\Google\\Chrome\\Application\\chrome.exe`,
+			`${programFilesX86}\\Google\\Chrome\\Application\\chrome.exe`,
+			`${programFiles}\\Chromium\\Application\\chrome.exe`
+		];
+	}
+	return [];
+}
+/** Find the first Chrome/Chromium binary that exists on this machine. */
+function findChromeBinary() {
+	for (const p of candidateChromePaths()) if (existsSync(p)) return p;
+	return null;
+}
+/**
+* Launch a local Chromium instance with CDP remote debugging enabled.
+*
+* The caller is responsible for calling `handle.stop()` when done.
+*
+* @throws if no Chrome/Chromium binary is found on the system.
+*/
+async function launchChromium(options = {}) {
+	const spawnImpl = options.spawnFn ?? spawn;
+	const requestedPort = options.port ?? 0;
+	const port = requestedPort === 0 ? await findFreePort() : requestedPort;
+	const devUrl = options.devUrl ?? process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173";
+	const binary = findChromeBinary();
+	if (binary === null) throw new Error("No Chrome/Chromium binary found on this system. Install Google Chrome or Chromium and try again. Searched: " + candidateChromePaths().join(", "));
+	const child = spawnImpl(binary, [
+		`--remote-debugging-port=${port}`,
+		"--no-first-run",
+		"--no-default-browser-check",
+		"--user-data-dir=/tmp/ait-devtools-chromium-profile",
+		...options.extraArgs ?? [],
+		devUrl
+	], {
+		stdio: "ignore",
+		detached: false
+	});
+	child.unref();
+	const devtoolsUrl = `http://127.0.0.1:${port}`;
+	process.stderr.write(`[ait-local-debug] Launched Chromium: ${binary}\n[ait-local-debug] CDP endpoint: ${devtoolsUrl}\n[ait-local-debug] Opening: ${devUrl}\n`);
+	return {
+		port,
+		devtoolsUrl,
+		stop() {
+			try {
+				child.kill();
+			} catch {}
+		}
+	};
+}
+//#endregion
 //#region src/mcp/deeplink.ts
+/**
+* Build a self-attaching dogfood deep link.
+*
+* `ait deploy --scheme-only` prints an `intoss-private://…?_deploymentId=<uuid>`
+* URL that opens a dogfood bundle on a phone. The in-app debug gate
+* (`src/in-app/gate.ts`) auto-attaches when the entry URL also carries
+* `debug=1` and `relay=<wss-url>`. This helper splices those params (plus
+* `at=<code>` when TOTP is enabled) into the scheme URL; rendering the result
+* as a QR code and scanning it with the phone camera opens the mini-app and
+* attaches it to the live Chii relay. QR is the single entry path — it needs
+* no USB cable, platform CLI, or driver, and works the same on iOS/Android.
+*
+* The Toss app propagates extra query params from the entry deep link into the
+* mini-app WebView's `location.search` (confirmed behavior), so the gate reads
+* them at attach time.
+*
+* TOTP `at=` param:
+*   When a TOTP secret is active, `buildDeepLinkAttachUrl` accepts an optional
+*   `totpCode` argument and splices `at=<code>` alongside `debug` and `relay`.
+*   The code must be computed by the caller at call time — do NOT pre-compute
+*   and cache it, because the 30-second window expires quickly. The in-app gate
+*   (`src/in-app/gate.ts` Layer C) validates this code against the baked secret.
+*
+* Why not `URL`/`URLSearchParams`: `intoss-private:` is a non-special scheme.
+* The WHATWG `URL` parser treats such schemes opaquely (no host/path/query
+* decomposition you can rely on across runtimes), so query manipulation via
+* `url.searchParams` is not portable here. We splice the query string directly
+* on the raw string instead, which keeps the scheme, authority, path, and any
+* pre-existing params (notably `_deploymentId`) byte-for-byte intact.
+*/
+/**
+* Suspicious/generic authority values that indicate a malformed or placeholder
+* scheme URL. These are host strings that will almost certainly cause the Toss
+* app to fail with "bundle not found" silently.
+*
+* The expected form from `ait deploy --scheme-only` is:
+*   intoss-private://<appName>?_deploymentId=<uuid>
+* where `<appName>` is a non-generic string like `aitc-sdk-example`.
+*/
+const SUSPICIOUS_AUTHORITIES = new Set([
+	"",
+	"web",
+	"localhost",
+	"127.0.0.1",
+	"app"
+]);
+/**
+* Validates the authority (host) portion of a scheme URL.
+*
+* Returns a warning message if the authority is missing or looks like a
+* placeholder, or `null` if the authority looks valid.
+*
+* Expected form: `intoss-private://<appName>?_deploymentId=<uuid>`
+* The authority must be a non-empty, non-generic app name (e.g. `aitc-sdk-example`).
+*/
+function validateSchemeAuthority(schemeUrl) {
+	const afterScheme = schemeUrl.replace(/^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//, "");
+	if (afterScheme === schemeUrl) return "scheme_url does not look like a scheme URL (expected `intoss-private://<appName>?_deploymentId=<uuid>`). Use the URL printed by `ait deploy --scheme-only`.";
+	const authorityEnd = afterScheme.search(/[/?#]/);
+	const authority = authorityEnd === -1 ? afterScheme : afterScheme.slice(0, authorityEnd);
+	if (SUSPICIOUS_AUTHORITIES.has(authority.toLowerCase())) return `scheme_url authority ${authority === "" ? "(empty)" : `"${authority}"`} looks like a placeholder. Expected an app name like \`intoss-private://aitc-sdk-example?_deploymentId=<uuid>\`. Use the URL printed by \`ait deploy --scheme-only\` — it includes the correct app name as the host.`;
+	return null;
+}
 function stripExisting(query, key) {
 	if (query === "") return "";
 	return query.split("&").filter((pair) => pair !== "" && pair.split("=")[0] !== key).join("&");
@@ -378,13 +793,23 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "build_attach_url",
-		description: "Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Opening the result on the phone (e.g. `adb shell am start -d \"<url>\"`) attaches the mini-app to this debug session with no QR scan. Requires the tunnel to be up — call list_pages first.",
+		description: "The tool result already shows the QR to the user directly (Claude Code renders MCP tool output to the user's screen; they press Ctrl+O to expand if it's collapsed). Do NOT re-print or re-render the QR in your reply — that just wastes output tokens. Simply tell the user to scan the QR shown in this tool's output with their phone camera. Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Returns the deep link JSON and a unicode QR of that deep link. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Requires the tunnel to be up — call list_pages first. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 90 s), then returns the attached page info too. When open_in_browser=true (default), saves the QR as a PNG and opens it in the OS default browser — only works when the MCP server runs on a local GUI machine (not headless/remote containers).",
 		inputSchema: {
 			type: "object",
-			properties: { scheme_url: {
-				type: "string",
-				description: "The intoss-private:// scheme URL from `ait deploy --scheme-only` (must carry _deploymentId)."
-			} },
+			properties: {
+				scheme_url: {
+					type: "string",
+					description: "The intoss-private:// scheme URL from `ait deploy --scheme-only` (must carry _deploymentId). The authority (host) must be the app name (e.g. intoss-private://aitc-sdk-example?_deploymentId=…). Generic values like \"web\" or an empty host indicate a malformed URL."
+				},
+				wait_for_attach: {
+					type: "boolean",
+					description: "If true, block after returning the QR until a page attaches to the relay (polls listTargets ~1 s interval, timeout 90 s). On attach, the response includes the attached page list. On timeout, returns an error with a list_pages retry hint."
+				},
+				open_in_browser: {
+					type: "boolean",
+					description: "If true (default), render the QR as a PNG and open it in the OS default browser. Only works when the MCP server is running on a local GUI machine — headless or remote container environments should set this to false to use the text QR fallback."
+				}
+			},
 			required: ["scheme_url"]
 		}
 	},
@@ -424,6 +849,37 @@ const DEBUG_TOOL_DEFINITIONS = [
 			required: []
 		}
 	},
+	{
+		name: "evaluate",
+		description: "Evaluates an arbitrary JavaScript expression on the attached mini-app page via CDP Runtime.evaluate (returnByValue: true) and returns the result. NOT read-only — the expression can have side effects (DOM mutations, SDK calls, state changes). Requires the relay to be attached — call list_pages first. Throws if the evaluation throws an exception on the page.",
+		inputSchema: {
+			type: "object",
+			properties: { expression: {
+				type: "string",
+				description: "JavaScript expression to evaluate in the page context."
+			} },
+			required: ["expression"]
+		}
+	},
+	{
+		name: "call_sdk",
+		description: "Calls a dogfood SDK method via the window.__sdkCall bridge (exported by @apps-in-toss/web-framework only in __DEBUG_BUILD__ bundles). NOT read-only — SDK calls have side effects (navigation, payments, permissions, etc.). On env 2/3 (real device relay) this hits the real SDK; on env 1 (local mock) it hits the mock SDK. Requires the relay to be attached — call list_pages first. Returns {ok: true, value} on success or {ok: false, error} on failure. Returns a clear error if window.__sdkCall is not available (non-dogfood bundle).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				name: {
+					type: "string",
+					description: "SDK method name to call (e.g. \"getOperationalEnvironment\")."
+				},
+				args: {
+					type: "array",
+					description: "Arguments to pass to the SDK method (optional, default []).",
+					items: {}
+				}
+			},
+			required: ["name"]
+		}
+	},
 	{
 		name: "AIT.getSdkCallHistory",
 		description: "Returns the recent Apps In Toss SDK call trace (method, args, result/error, timestamp) that raw CDP cannot observe. Read-only. Use to confirm an SDK call fired and how it resolved (e.g. a saveBase64Data permission regression).",
@@ -456,6 +912,16 @@ const DEBUG_TOOL_NAMES = new Set(DEBUG_TOOL_DEFINITIONS.map((t) => t.name));
 function isDebugToolName(name) {
 	return DEBUG_TOOL_NAMES.has(name);
 }
+/**
+* Tool names that are available before any page attaches (bootstrap tier).
+*
+* `build_attach_url` — pure URL synthesis, no attach needed.
+* `list_pages`       — reports tunnel status + empty pages even pre-attach.
+*
+* All other tools require an attached page (`enableDomains` must succeed) and
+* are only advertised in `tools/list` once a target appears.
+*/
+const BOOTSTRAP_TOOL_NAMES = new Set(["build_attach_url", "list_pages"]);
 /** Renders a CDP `RemoteObject` console arg to a stable display string. */
 function renderRemoteObject(arg) {
 	if (arg.value !== void 0) {
@@ -510,12 +976,135 @@ function listPages(connection, tunnel) {
 * Builds a self-attaching dogfood deep link from an `ait deploy --scheme-only`
 * URL plus this session's live relay. Throws if the tunnel is not up yet (no
 * relay URL to splice in) — the caller surfaces that as a tool error.
+*
+* Also validates the scheme URL's authority. A suspicious authority (empty,
+* "web", "localhost", etc.) is surfaced as a non-fatal `authorityWarning` on
+* the result so the caller can show a helpful hint without blocking the link
+* generation (the warning is consistent with how other validation in
+* `buildDeepLinkAttachUrl` works — hard errors for relay, soft warning for
+* the scheme authority which is in the caller's input, not ours to own).
 */
 function buildAttachUrl(schemeUrl, tunnel) {
 	if (!tunnel.up || tunnel.wssUrl === null) throw new Error("No relay URL yet — the cloudflared quick tunnel is not up. Call list_pages to check tunnel status.");
+	const authorityWarning = validateSchemeAuthority(schemeUrl) ?? void 0;
 	return {
 		attachUrl: buildDeepLinkAttachUrl(schemeUrl, tunnel.wssUrl),
-		relayUrl: tunnel.wssUrl
+		relayUrl: tunnel.wssUrl,
+		...authorityWarning !== void 0 ? { authorityWarning } : {}
+	};
+}
+/**
+* Heuristic: can this process open a GUI browser?
+*
+* Returns `true` when we think a GUI is available:
+*   - On macOS (`darwin`) we assume yes (MCP normally runs on the user's Mac).
+*   - On Linux we check for `DISPLAY` or `WAYLAND_DISPLAY`.
+*   - On Windows we assume yes.
+*   - In a CI environment (`CI=true`) we assume no.
+*/
+function canOpenBrowser() {
+	if (process.env.CI === "true" || process.env.CI === "1") return false;
+	const platform = process.platform;
+	if (platform === "darwin" || platform === "win32") return true;
+	if (platform === "linux") return Boolean(process.env.DISPLAY ?? process.env.WAYLAND_DISPLAY);
+	return false;
+}
+/**
+* Writes the attach URL as a QR PNG + a wrapper HTML page to the OS temp
+* directory, then opens the HTML in the OS default browser.
+*
+* SECRET-HANDLING:
+*   - File names are derived from a short timestamp, NOT from the attach URL or
+*     any token/code value. The `at=` code is NOT in the file name.
+*   - The attach URL (which may carry `at=`) is embedded inside the HTML page
+*     body — that is the intended delivery channel for the QR.
+*   - This function must NOT write the attach URL, deploymentId, or any
+*     TOTP code to stdout, stderr, or any log.
+*
+* @param attachUrl - The deep link to encode as a QR. May contain `at=<code>`.
+* @param deploymentId - Optional human-readable label for the HTML page (e.g. UUID substring).
+*   Must NOT be derived from the `at=` code value.
+* @returns `OpenQrInBrowserResult` — never throws (errors are returned in `.error`).
+*/
+async function openQrInBrowser(attachUrl, deploymentId) {
+	const { tmpdir } = await import("node:os");
+	const { writeFileSync } = await import("node:fs");
+	const { join } = await import("node:path");
+	const { spawnSync } = await import("node:child_process");
+	const { default: QRCode } = await import("qrcode");
+	const stamp = Date.now();
+	const pngPath = join(tmpdir(), `ait-qr-${stamp}.png`);
+	const htmlPath = join(tmpdir(), `ait-qr-${stamp}.html`);
+	try {
+		await QRCode.toFile(pngPath, attachUrl, {
+			type: "png",
+			errorCorrectionLevel: "M"
+		});
+	} catch (err) {
+		return {
+			opened: false,
+			htmlPath,
+			pngPath,
+			error: `QR PNG write failed: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	const htmlContent = `<!DOCTYPE html>
+<html lang="ko">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>AIT Debug — QR</title>
+  <style>
+    body { font-family: monospace; background: #111; color: #eee; display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 100vh; margin: 0; gap: 1.5rem; padding: 2rem; box-sizing: border-box; }
+    img { width: min(90vw, 400px); height: auto; image-rendering: pixelated; background: #fff; padding: 1rem; border-radius: 8px; }
+    .label { font-size: 0.85rem; opacity: 0.6; }
+    .url { font-size: 0.75rem; word-break: break-all; max-width: 60ch; opacity: 0.5; }
+  </style>
+</head>
+<body>
+  <img src="${pngPath}" alt="QR code" />
+  <p class="label">deployment: ${deploymentId ? deploymentId.replace(/[<>&"']/g, (c) => `&#${c.charCodeAt(0)};`) : "attach"}</p>
+</body>
+</html>`;
+	try {
+		writeFileSync(htmlPath, htmlContent, "utf8");
+	} catch (err) {
+		return {
+			opened: false,
+			htmlPath,
+			pngPath,
+			error: `HTML write failed: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	const platform = process.platform;
+	let openCmd;
+	let openArgs;
+	if (platform === "darwin") {
+		openCmd = "open";
+		openArgs = [htmlPath];
+	} else if (platform === "win32") {
+		openCmd = "cmd";
+		openArgs = [
+			"/c",
+			"start",
+			"",
+			htmlPath
+		];
+	} else {
+		openCmd = "xdg-open";
+		openArgs = [htmlPath];
+	}
+	const spawnResult = spawnSync(openCmd, openArgs, { timeout: 5e3 });
+	if (spawnResult.error) return {
+		opened: false,
+		htmlPath,
+		pngPath,
+		error: `Browser open failed (${openCmd}): ${spawnResult.error.message}`
+	};
+	return {
+		opened: true,
+		htmlPath,
+		pngPath
 	};
 }
 /** Returns the DOM tree of the attached page (`DOM.getDocument`). */
@@ -538,7 +1127,21 @@ async function takeScreenshot(connection) {
 		mimeType: "image/png"
 	};
 }
-`
+/**
+* The JS probe injected via `Runtime.evaluate`. It reads:
+*   1. `env(safe-area-inset-*)` via a temporary element with padding set to
+*      those CSS env vars, then `getComputedStyle`.
+*   2. `SafeAreaInsets.get()` if the native SDK object is available.
+*   3. nav bar geometry (first `.ait-navbar` element height, if present).
+*   4. `innerWidth`, `innerHeight`, `devicePixelRatio`, `navigator.userAgent`.
+*
+* Returns a plain JSON-serialisable object so `returnByValue: true` works.
+*
+* NOTE: This expression is evaluated in the page context on the real device.
+* It does not mutate any page state — the temporary element is removed after
+* reading. No secret or auth token is read or returned.
+*/
+const SAFE_AREA_PROBE_EXPRESSION = `
 (function() {
   var el = document.createElement('div');
   el.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;visibility:hidden;' +
@@ -577,6 +1180,157 @@ async function takeScreenshot(connection) {
   });
 })()
 `.trim();
+/**
+* Parses a raw `Runtime.evaluate` result value into a `SafeAreaMeasurement`.
+* The probe returns a JSON string (because `returnByValue:true` with a plain
+* object works unreliably across Chii relay versions — stringifying is safer).
+*
+* Throws if the result is missing, contains an exception, or cannot be parsed.
+*/
+function normalizeSafeAreaResult(rawValue) {
+	if (typeof rawValue !== "string") throw new Error(`measure_safe_area: probe returned unexpected type "${typeof rawValue}" — expected JSON string`);
+	let parsed;
+	try {
+		parsed = JSON.parse(rawValue);
+	} catch {
+		throw new Error(`measure_safe_area: probe returned non-JSON string: ${rawValue}`);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("measure_safe_area: parsed result is not an object");
+	const obj = parsed;
+	function requireInsets(key) {
+		const v = obj[key];
+		if (v === null || v === void 0) return null;
+		if (typeof v !== "object") return null;
+		const r = v;
+		return {
+			top: typeof r.top === "number" ? r.top : 0,
+			right: typeof r.right === "number" ? r.right : 0,
+			bottom: typeof r.bottom === "number" ? r.bottom : 0,
+			left: typeof r.left === "number" ? r.left : 0
+		};
+	}
+	return {
+		cssEnv: requireInsets("cssEnv") ?? {
+			top: 0,
+			right: 0,
+			bottom: 0,
+			left: 0
+		},
+		sdkInsets: requireInsets("sdkInsets"),
+		navBarHeight: typeof obj.navBarHeight === "number" ? obj.navBarHeight : null,
+		innerWidth: typeof obj.innerWidth === "number" ? obj.innerWidth : 0,
+		innerHeight: typeof obj.innerHeight === "number" ? obj.innerHeight : 0,
+		devicePixelRatio: typeof obj.devicePixelRatio === "number" ? obj.devicePixelRatio : 1,
+		userAgent: typeof obj.userAgent === "string" ? obj.userAgent : ""
+	};
+}
+/**
+* Runs the safe-area probe on the attached page and returns a normalized
+* `SafeAreaMeasurement`. Read-only — does not mutate page state.
+*
+* Throws on CDP error, probe exception, or result parse failure.
+*/
+async function measureSafeArea(connection) {
+	const result = await connection.send("Runtime.evaluate", {
+		expression: SAFE_AREA_PROBE_EXPRESSION,
+		returnByValue: true,
+		awaitPromise: false
+	});
+	if (result.exceptionDetails) {
+		const msg = result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Runtime.evaluate threw an exception";
+		throw new Error(`measure_safe_area: probe threw — ${msg}`);
+	}
+	return normalizeSafeAreaResult(result.result.value);
+}
+/**
+* Evaluates an arbitrary JS expression on the attached page via
+* `Runtime.evaluate`. NOT read-only — the expression may have side effects.
+*
+* Throws if the evaluation produced a CDP exception.
+*
+* SECRET-HANDLING: expression and result value are NOT written to any log.
+*/
+async function evaluate(connection, expression) {
+	const result = await connection.send("Runtime.evaluate", {
+		expression,
+		returnByValue: true,
+		awaitPromise: false
+	});
+	if (result.exceptionDetails) {
+		const msg = result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Runtime.evaluate threw an exception";
+		throw new Error(`evaluate failed: ${msg}`);
+	}
+	return {
+		value: result.result.value,
+		type: result.result.type
+	};
+}
+/**
+* Builds the Runtime.evaluate expression that calls `window.__sdkCall` with
+* the given method name and args, awaits the promise, and returns a JSON
+* envelope `{ok, value/error}` as a string.
+*
+* Name and args are embedded via `JSON.stringify` so they are safely escaped.
+* The expression checks for `window.__sdkCall` and returns a clear error if
+* it is absent (non-dogfood bundle).
+*
+* SECRET-HANDLING: the expression is built here and MUST NOT be written to
+* any log or stderr by the caller.
+*/
+function buildCallSdkExpression(name, args) {
+	return `(async () => { if (typeof window.__sdkCall !== 'function') {  return JSON.stringify({ok:false,error:'window.__sdkCall is not available — is this a dogfood (__DEBUG_BUILD__) bundle?'}); } try {  const r = await window.__sdkCall(${JSON.stringify(name)}, ...${JSON.stringify(args)});  return JSON.stringify({ok:true,value:r}); } catch(e) {  return JSON.stringify({ok:false,error:String(e && e.message || e)}); }})()`;
+}
+/**
+* Parses the JSON envelope string returned by the `call_sdk` expression.
+* Returns a typed `CallSdkResult`.
+*
+* Throws only on parse failure (not on ok:false — that is a normal result).
+*/
+function normalizeCallSdkResult(rawValue) {
+	if (typeof rawValue !== "string") throw new Error(`call_sdk: bridge returned unexpected type "${typeof rawValue}" — expected JSON string`);
+	let parsed;
+	try {
+		parsed = JSON.parse(rawValue);
+	} catch {
+		throw new Error("call_sdk: bridge returned non-JSON string");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("call_sdk: parsed result is not an object");
+	const obj = parsed;
+	if (obj.ok === true) return {
+		ok: true,
+		value: obj.value
+	};
+	if (obj.ok === false) return {
+		ok: false,
+		error: typeof obj.error === "string" ? obj.error : String(obj.error)
+	};
+	throw new Error("call_sdk: bridge result missing \"ok\" field");
+}
+/**
+* Calls a dogfood SDK method via `window.__sdkCall` on the attached page.
+* NOT read-only — SDK calls may have side effects.
+*
+* On env 2/3 (real device relay) this hits the real SDK; on env 1 (local
+* mock) it hits the mock SDK.
+*
+* Throws on CDP error or result parse failure. Returns `{ok:false, error}`
+* for bridge-level errors (method not found, SDK threw, bridge absent).
+*
+* SECRET-HANDLING: name, args, and the result value are NOT written to any log.
+*/
+async function callSdk(connection, name, args) {
+	const expression = buildCallSdkExpression(name, args);
+	const result = await connection.send("Runtime.evaluate", {
+		expression,
+		returnByValue: true,
+		awaitPromise: true
+	});
+	if (result.exceptionDetails) {
+		const msg = result.exceptionDetails.exception?.description ?? result.exceptionDetails.text ?? "Runtime.evaluate threw an exception";
+		throw new Error(`call_sdk threw: ${msg}`);
+	}
+	return normalizeCallSdkResult(result.result.value);
+}
 /** Set of tool names served by the AIT source rather than the CDP connection. */
 const AIT_TOOL_NAMES = new Set([
 	"AIT.getSdkCallHistory",
@@ -683,10 +1437,10 @@ function verifyTotp(secret, code, when = Date.now(), skew = 1) {
 *
 * On spawn, the debug server opens an accountless `*.trycloudflare.com` quick
 * tunnel to the local Chii relay so the phone can attach over a public wss URL,
-* then prints an ASCII QR + attach instructions. When TOTP auth is enabled
-* (`AIT_DEBUG_TOTP_SECRET` is set), the QR encodes only the base relay URL —
-* the TOTP code (`at=`) is NOT included because it rotates every 30 s and
-* would be stale by the time a human scans. The in-app deep-link builder
+* then prints a unicode half-block QR + attach instructions. When TOTP auth is
+* enabled (`AIT_DEBUG_TOTP_SECRET` is set), the QR encodes only the base relay
+* URL — the TOTP code (`at=`) is NOT included because it rotates every 30 s
+* and would be stale by the time a human scans. The in-app deep-link builder
 * splices the live code at attach time.
 *
 * SECRET-HANDLING: The TOTP secret and computed code values MUST NOT appear
@@ -741,6 +1495,45 @@ async function startQuickTunnel(localPort) {
 	};
 }
 /**
+* Renders a pure unicode half-block QR string for the given text.
+*
+* Uses `qrcode` (Node full lib) to get the raw bit matrix, then encodes every
+* two vertical modules into a single half-block character:
+*   - both dark  → `█`
+*   - top only   → `▀`
+*   - bottom only → `▄`
+*   - both light → ` ` (space)
+*
+* The output contains **zero ANSI escape codes**, so it renders correctly in
+* every surface (terminal, VS Code, JetBrains, web) and can be scanned by a
+* phone camera when shown verbatim in an agent response.
+*
+* Shared by `renderAttachBanner` (relay wssUrl QR) and the `build_attach_url`
+* MCP tool response (attach deep-link QR).
+*/
+async function renderQr(text) {
+	const { default: QRCode } = await import("qrcode");
+	const qr = QRCode.create(text, { errorCorrectionLevel: "M" });
+	const size = qr.modules.size;
+	const data = qr.modules.data;
+	const isDark = (x, y) => {
+		if (x < 0 || y < 0 || x >= size || y >= size) return false;
+		return data[y * size + x] === 1;
+	};
+	const QUIET = 1;
+	const lines = [];
+	for (let y = -QUIET; y < size + QUIET; y += 2) {
+		let line = "";
+		for (let x = -QUIET; x < size + QUIET; x++) {
+			const top = isDark(x, y);
+			const bot = isDark(x, y + 1);
+			line += top && bot ? "█" : top ? "▀" : bot ? "▄" : " ";
+		}
+		lines.push(line);
+	}
+	return `${lines.join("\n")}\n`;
+}
+/**
 * Renders the attach banner (relay URL + ASCII QR) as a string.
 *
 * The QR encodes the base `wssUrl` only. When `totpEnabled` is true, a note
@@ -751,9 +1544,7 @@ async function startQuickTunnel(localPort) {
 * included in this output.
 */
 async function renderAttachBanner(input) {
-	const qr = await new Promise((resolve) => {
-		qrcode.generate(input.wssUrl, { small: true }, (rendered) => resolve(rendered));
-	});
+	const qr = await renderQr(input.wssUrl);
 	const authNote = input.totpEnabled ? "  auth:          TOTP enabled — attach URLs include a rotating code (at=)." : "  auth:          none (set AIT_DEBUG_TOTP_SECRET to enable TOTP).";
 	return [
 		"",
@@ -782,31 +1573,64 @@ async function printAttachBanner(input) {
 * Lets an AI coding agent attach to a running mini-app (real Toss WebView, or a
 * browser in dev mode) and read its console/network/DOM/screenshot over CDP plus
 * the AIT.* domain, without a human watching a phone. Transport is CDP-via-Chii:
-* a local Chii relay :9100 exposed through a cloudflared quick tunnel; the phone
-* attaches over the public wss URL.
+* a local Chii relay on an OS-assigned port (default 0) exposed through a
+* cloudflared quick tunnel; the phone attaches over the public wss URL.
 *
-*   AI host  --stdio-->  this server  --CDP client WS-->  Chii relay :9100
+*   AI host  --stdio-->  this server  --CDP client WS-->  Chii relay :<OS-port>
 *                                                          ^-- target WS -- phone
 *
+* Port 0 (default): the OS picks a free ephemeral port on every startup.
+* This prevents EADDRINUSE when a stale cloudflared child (orphaned after
+* SIGKILL, PPID 1) still holds a fixed port — which previously caused the MCP
+* handshake to fail with -32000. With port 0 any orphaned cloudflared is
+* harmless; the new relay always gets a fresh port.
+*
+* Best-effort child cleanup: SIGINT/SIGTERM/SIGHUP handlers call shutdown() to
+* stop cloudflared and the relay. uncaughtException/unhandledRejection also
+* call shutdown() before exit. SIGKILL cannot be intercepted by Node, so
+* cloudflared orphans from SIGKILL remain (port 0 makes them harmless). Users
+* can clean up manually: `pkill -f 'cloudflared.*trycloudflare'`.
+*
 * The tool layer reads from an injectable `CdpConnection` (CDP) and `AitSource`
 * (AIT.*), so every tool is unit-testable with a fake (no phone). This module
 * wires the live pieces (relay + tunnel + production connection); the phone
 * roundtrip is fully wired and pending only on-device acceptance.
 *
+* Dynamic tool registration (issue #208):
+* The server advertises `listChanged: true` so MCP clients can subscribe to
+* `notifications/tools/list_changed`. Before any page attaches, only bootstrap
+* tools (`build_attach_url`, `list_pages`) are listed. Once a target appears,
+* the full attach-dependent tool set is added and a `list_changed` notification
+* is sent — without requiring a session restart. `runDebugServer` and
+* `runLocalDebugServer` start a polling watcher that detects the 0→N target
+* transition and calls `server.sendToolListChanged()`.
+*
+* Note: `src/mcp/server.ts` (dev mode, HTTP mock-state) is NOT subject to this
+* model — it has no attach concept and always exposes the full tool surface.
+*
 * Node-only.
 */
 /**
 * Builds the debug-mode MCP server around an injected CDP connection + AIT
 * source + tunnel status getter. Pure wiring — does not start a relay or
 * tunnel, which is what makes the tool surface unit-testable.
+*
+* `tools/list` is two-tiered (issue #208):
+*   - bootstrap (always): `build_attach_url`, `list_pages`
+*   - attach-dependent (after `connection.listTargets().length > 0`): all others
+*
+* `CallTool` is NOT tiered — hidden tools still execute (attach errors surface
+* naturally via `enableDomains`). The tier only controls visibility.
 */
 function createDebugServer(deps) {
-	const { connection, aitSource, getTunnelStatus } = deps;
+	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4 } = deps;
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.33"
-	}, { capabilities: { tools: {} } });
-	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEBUG_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
+		version: "0.1.35"
+	}, { capabilities: { tools: { listChanged: true } } });
+	server.setRequestHandler(ListToolsRequestSchema, () => {
+		return { tools: connection.listTargets().length > 0 ? DEBUG_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) : DEBUG_TOOL_DEFINITIONS.filter((tool) => BOOTSTRAP_TOOL_NAMES.has(tool.name)).map((tool) => ({ ...tool })) };
+	});
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const name = request.params.name;
 		if (!isDebugToolName(name)) return {
@@ -836,8 +1660,109 @@ function createDebugServer(deps) {
 				}],
 				isError: true
 			};
+			const waitForAttach = request.params.arguments?.wait_for_attach === true;
+			const openInBrowser = request.params.arguments?.open_in_browser !== false;
 			try {
-				return jsonResult$1(buildAttachUrl(schemeUrl, getTunnelStatus()));
+				const { attachUrl, relayUrl, authorityWarning } = buildAttachUrl(schemeUrl, getTunnelStatus());
+				const warningPrefix = authorityWarning ? `⚠️  scheme_url 경고: ${authorityWarning}\n\n` : "";
+				const header = "This tool result is shown to the user directly — do NOT re-print the QR below in your reply (it wastes output tokens). Just tell the user to scan the QR in this output (Ctrl+O to expand if collapsed).";
+				if (openInBrowser && canOpenBrowser()) {
+					let deploymentIdLabel;
+					try {
+						const dpMatch = attachUrl.match(/[?&]_deploymentId=([^&]+)/);
+						if (dpMatch?.[1]) deploymentIdLabel = decodeURIComponent(dpMatch[1]).slice(0, 36);
+					} catch {}
+					const browserResult = await openQrInBrowser(attachUrl, deploymentIdLabel);
+					if (browserResult.opened) {
+						const shortText = `${warningPrefix}${header}\n${JSON.stringify({ relayUrl }, null, 2)}\n\nブラウザにQRを表示しました。\nQR画像: ${browserResult.pngPath}\nHTMLページ: ${browserResult.htmlPath}\n\n브라우저에 QR을 띄웠습니다. 스마트폰 카메라로 스캔하세요.\nPNG: ${browserResult.pngPath}`;
+						if (!waitForAttach) return { content: [{
+							type: "text",
+							text: shortText
+						}] };
+						const POLL_INTERVAL_MS = 1e3;
+						const TIMEOUT_MS = waitForAttachTimeoutMs;
+						const deadline = Date.now() + TIMEOUT_MS;
+						let attachedPages = [];
+						while (Date.now() < deadline) {
+							attachedPages = connection.listTargets();
+							if (attachedPages.length > 0) break;
+							await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+						}
+						if (attachedPages.length === 0) return {
+							content: [{
+								type: "text",
+								text: `${shortText}\n\nNo page attached within ${TIMEOUT_MS / 1e3}s — call list_pages to retry.`
+							}],
+							isError: true
+						};
+						const pagesResult = listPages(connection, getTunnelStatus());
+						return { content: [{
+							type: "text",
+							text: `${shortText}\n\n${JSON.stringify(pagesResult, null, 2)}`
+						}] };
+					}
+					const fallbackNote = `(브라우저 열기 실패: ${browserResult.error ?? "unknown"} — 텍스트 QR로 대체)\n`;
+					const qr = await renderQr(attachUrl);
+					const baseText = `${warningPrefix}${fallbackNote}${header}\n${JSON.stringify({
+						attachUrl,
+						relayUrl
+					}, null, 2)}\n\n${qr}`;
+					if (!waitForAttach) return { content: [{
+						type: "text",
+						text: baseText
+					}] };
+					const POLL_INTERVAL_MS_FB = 1e3;
+					const TIMEOUT_MS_FB = waitForAttachTimeoutMs;
+					const deadline2 = Date.now() + TIMEOUT_MS_FB;
+					let attachedPagesFb = [];
+					while (Date.now() < deadline2) {
+						attachedPagesFb = connection.listTargets();
+						if (attachedPagesFb.length > 0) break;
+						await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS_FB));
+					}
+					if (attachedPagesFb.length === 0) return {
+						content: [{
+							type: "text",
+							text: `${baseText}\n\nNo page attached within ${TIMEOUT_MS_FB / 1e3}s — call list_pages to retry.`
+						}],
+						isError: true
+					};
+					const pagesResultFb = listPages(connection, getTunnelStatus());
+					return { content: [{
+						type: "text",
+						text: `${baseText}\n\n${JSON.stringify(pagesResultFb, null, 2)}`
+					}] };
+				}
+				const qr = await renderQr(attachUrl);
+				const baseText = `${warningPrefix}${header}\n${JSON.stringify({
+					attachUrl,
+					relayUrl
+				}, null, 2)}\n\n${qr}`;
+				if (!waitForAttach) return { content: [{
+					type: "text",
+					text: baseText
+				}] };
+				const POLL_INTERVAL_MS = 1e3;
+				const TIMEOUT_MS = waitForAttachTimeoutMs;
+				const deadline = Date.now() + TIMEOUT_MS;
+				let attachedPages = [];
+				while (Date.now() < deadline) {
+					attachedPages = connection.listTargets();
+					if (attachedPages.length > 0) break;
+					await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+				}
+				if (attachedPages.length === 0) return {
+					content: [{
+						type: "text",
+						text: `${baseText}\n\nNo page attached within ${TIMEOUT_MS / 1e3}s — call list_pages to retry.`
+					}],
+					isError: true
+				};
+				const pagesResult = listPages(connection, getTunnelStatus());
+				return { content: [{
+					type: "text",
+					text: `${baseText}\n\n${JSON.stringify(pagesResult, null, 2)}`
+				}] };
 			} catch (err) {
 				return errorResult(err, name);
 			}
@@ -870,6 +1795,30 @@ function createDebugServer(deps) {
 						mimeType: shot.mimeType
 					}] };
 				}
+				case "measure_safe_area": return jsonResult$1(await measureSafeArea(connection));
+				case "evaluate": {
+					const expression = request.params.arguments?.expression;
+					if (typeof expression !== "string" || expression === "") return {
+						content: [{
+							type: "text",
+							text: "evaluate requires a non-empty expression."
+						}],
+						isError: true
+					};
+					return jsonResult$1(await evaluate(connection, expression));
+				}
+				case "call_sdk": {
+					const sdkName = request.params.arguments?.name;
+					if (typeof sdkName !== "string" || sdkName === "") return {
+						content: [{
+							type: "text",
+							text: "call_sdk requires a non-empty name."
+						}],
+						isError: true
+					};
+					const rawArgs = request.params.arguments?.args;
+					return jsonResult$1(await callSdk(connection, sdkName, Array.isArray(rawArgs) ? rawArgs : []));
+				}
 				default: return unknownTool(name);
 			}
 		} catch (err) {
@@ -903,6 +1852,35 @@ function errorResult(err, name) {
 	};
 }
 /**
+* Starts a polling watcher that detects the first 0→N target transition on
+* `connection.listTargets()` and sends a `notifications/tools/list_changed`
+* notification on the given server.
+*
+* The watcher polls every `intervalMs` (default 1 000 ms). It fires
+* `server.sendToolListChanged()` exactly once — on the first transition — then
+* clears itself. Shutdown calls `stop()` to clear the interval.
+*
+* SECRET-HANDLING: target `id`/`title`/`url` are not written to any log here.
+* Only an attach-detected stderr line is emitted (no target details).
+*
+* @returns `stop` — call this during shutdown to clear the interval.
+*/
+function startAttachWatcher(connection, server, intervalMs = 1e3) {
+	let wasAttached = connection.listTargets().length > 0;
+	if (wasAttached) server.sendToolListChanged();
+	const handle = setInterval(() => {
+		const isAttached = connection.listTargets().length > 0;
+		if (!wasAttached && isAttached) {
+			wasAttached = true;
+			server.sendToolListChanged();
+			clearInterval(handle);
+		}
+	}, intervalMs);
+	return { stop() {
+		clearInterval(handle);
+	} };
+}
+/**
 * Reads `AIT_DEBUG_TOTP_SECRET` from `process.env` at runtime and builds a
 * `verifyAuth` predicate for the Chii relay's WebSocket upgrade gate.
 *
@@ -927,13 +1905,14 @@ function buildRelayVerifyAuth() {
 }
 /**
 * Boots the live debug stack and serves it over stdio:
-*   1. start the Chii relay (with TOTP auth if AIT_DEBUG_TOTP_SECRET is set),
-*   2. open a cloudflared quick tunnel to it,
+*   1. start the Chii relay on an OS-assigned port (with TOTP auth if
+*      AIT_DEBUG_TOTP_SECRET is set),
+*   2. open a cloudflared quick tunnel to the relay's confirmed port,
 *   3. print relay URL + attach instructions,
 *   4. expose the debug tools backed by a `ChiiCdpConnection` + `ChiiAitSource`.
 */
 async function runDebugServer(options = {}) {
-	const relayPort = options.relayPort ?? 9100;
+	const relayPort = options.relayPort ?? 0;
 	const verifyAuth = buildRelayVerifyAuth();
 	const totpEnabled = verifyAuth !== void 0;
 	const relay = await startChiiRelay({
@@ -947,7 +1926,7 @@ async function runDebugServer(options = {}) {
 	};
 	generateAttachToken();
 	try {
-		tunnel = await startQuickTunnel(relayPort);
+		tunnel = await startQuickTunnel(relay.port);
 		tunnelStatus = {
 			up: true,
 			wssUrl: tunnel.wssUrl
@@ -968,7 +1947,12 @@ async function runDebugServer(options = {}) {
 		getTunnelStatus: () => tunnelStatus
 	});
 	const transport = new StdioServerTransport();
+	let closed = false;
+	let attachWatcher = null;
 	const shutdown = () => {
+		if (closed) return;
+		closed = true;
+		attachWatcher?.stop();
 		connection.close();
 		tunnel?.stop();
 		relay.close();
@@ -976,7 +1960,95 @@ async function runDebugServer(options = {}) {
 	};
 	process.once("SIGINT", shutdown);
 	process.once("SIGTERM", shutdown);
+	process.once("SIGHUP", shutdown);
+	process.on("exit", () => {
+		if (!closed) {
+			closed = true;
+			attachWatcher?.stop();
+			tunnel?.stop();
+		}
+	});
+	process.on("uncaughtException", (err) => {
+		process.stderr.write(`[ait-debug] uncaughtException: ${String(err)}\n`);
+		shutdown();
+		process.exit(1);
+	});
+	process.on("unhandledRejection", (reason) => {
+		process.stderr.write(`[ait-debug] unhandledRejection: ${String(reason)}\n`);
+		shutdown();
+		process.exit(1);
+	});
+	await server.connect(transport);
+	attachWatcher = startAttachWatcher(connection, server);
+}
+/**
+* Boots the local-browser debug stack and serves it over stdio:
+*   1. launch a local Chromium with `--remote-debugging-port=<port>`,
+*   2. attach a `LocalCdpConnection` to the first non-blank page target,
+*   3. expose the debug tools backed by that connection + a `ChiiAitSource`.
+*
+* `build_attach_url` (relay-specific, generates a deep-link + QR for the phone)
+* is not applicable in local mode because there is no relay or tunnel. The tool
+* is still listed (it is part of `DEBUG_TOOL_DEFINITIONS`) but will return a
+* clear "not applicable" message via the tunnel-down path (wssUrl is null).
+*
+* The AIT.* tools (`AIT.getSdkCallHistory`, `AIT.getMockState`,
+* `AIT.getOperationalEnvironment`) ride the same CDP channel via
+* `ChiiAitSource` → `LocalCdpConnection.sendCommand`. They will succeed once
+* the sdk-example dev-bridge (`window.__sdkCall` install) lands in sdk-example;
+* until then they return the sdk-example "bridge absent" message — which is
+* expected and noted in the PR as an explicit out-of-scope follow-up.
+*/
+async function runLocalDebugServer(options = {}) {
+	const chromium = await launchChromium({
+		port: options.cdpPort ?? 0,
+		devUrl: options.devUrl ?? process.env.AIT_DEVTOOLS_URL ?? "http://localhost:5173"
+	});
+	await new Promise((r) => setTimeout(r, 800));
+	const connection = new LocalCdpConnection({ devtoolsHttpUrl: chromium.devtoolsUrl });
+	const aitSource = new ChiiAitSource(connection);
+	const tunnelStatus = {
+		up: false,
+		wssUrl: null
+	};
+	const server = createDebugServer({
+		connection,
+		aitSource,
+		getTunnelStatus: () => tunnelStatus
+	});
+	const transport = new StdioServerTransport();
+	let closed = false;
+	let attachWatcher = null;
+	const shutdown = () => {
+		if (closed) return;
+		closed = true;
+		attachWatcher?.stop();
+		connection.close();
+		chromium.stop();
+		server.close();
+	};
+	process.once("SIGINT", shutdown);
+	process.once("SIGTERM", shutdown);
+	process.once("SIGHUP", shutdown);
+	process.on("exit", () => {
+		if (!closed) {
+			closed = true;
+			attachWatcher?.stop();
+			chromium.stop();
+		}
+	});
+	process.on("uncaughtException", (err) => {
+		process.stderr.write(`[ait-local-debug] uncaughtException: ${String(err)}\n`);
+		shutdown();
+		process.exit(1);
+	});
+	process.on("unhandledRejection", (reason) => {
+		process.stderr.write(`[ait-local-debug] unhandledRejection: ${String(reason)}\n`);
+		shutdown();
+		process.exit(1);
+	});
 	await server.connect(transport);
+	attachWatcher = startAttachWatcher(connection, server);
 }
 //#endregion
 //#region src/mcp/ait-http-source.ts
@@ -1097,7 +2169,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.33"
+		version: "0.1.35"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1159,11 +2231,18 @@ async function runDevServer() {
 /**
 * `devtools-mcp` bin entry.
 *
-* Single bin, two transports selected by `--mode`:
-*   - (default, no flag) debug mode — CDP/Chii relay + cloudflared quick tunnel.
-*     Attach a running mini-app (real Toss WebView or a browser) and read its
-*     console + network over CDP without a human watching a phone.
-*   - `--mode=dev` — dev mode — reads the live browser mock state from a running
+* Single bin, two modes selected by `--mode` and one target selected by
+* `--target`:
+*
+*   --mode=debug (default)
+*     --target=relay (default) — CDP/Chii relay + cloudflared quick tunnel.
+*       Attach a running mini-app (real Toss WebView, env 2/3) and read its
+*       console + network over CDP without a human watching a phone.
+*     --target=local — CDP direct-attach to a local Chromium launched by the
+*       MCP server (env 1). No relay or tunnel; the browser is launched
+*       pointing at AIT_DEVTOOLS_URL (default http://localhost:5173).
+*
+*   --mode=dev — dev mode — reads the live browser mock state from a running
 *     Vite dev server (the devtools#130 `devtools_get_mock_state` surface).
 *
 * Node-only stdio process.
@@ -1182,13 +2261,40 @@ function parseMode(argv) {
 	}
 	return "debug";
 }
+/**
+* Parses `--target=<value>` / `--target <value>` from argv; default `relay`.
+*
+* Only meaningful when `--mode=debug`:
+*   - `relay`  — phone/WebView attach over Chii relay + cloudflared tunnel (env 2/3).
+*   - `local`  — local Chromium CDP attach (env 1, no relay needed).
+*/
+function parseTarget(argv) {
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === void 0) continue;
+		if (arg.startsWith("--target=")) return normalizeTarget(arg.slice(9));
+		if (arg === "--target") {
+			const next = argv[i + 1];
+			if (next === void 0) throw new Error("--target requires a value: 'relay' (default) or 'local'.");
+			return normalizeTarget(next);
+		}
+	}
+	return "relay";
+}
 function normalizeMode(value) {
 	if (value === "dev") return "dev";
 	if (value === "debug") return "debug";
 	throw new Error(`Unknown --mode '${value}'. Expected 'debug' (default) or 'dev'.`);
 }
+function normalizeTarget(value) {
+	if (value === "relay") return "relay";
+	if (value === "local") return "local";
+	throw new Error(`Unknown --target '${value}'. Expected 'relay' (default) or 'local'.`);
+}
 async function main() {
-	if (parseMode(process.argv.slice(2)) === "dev") await runDevServer();
+	const args = process.argv.slice(2);
+	if (parseMode(args) === "dev") await runDevServer();
+	else if (parseTarget(args) === "local") await runLocalDebugServer();
 	else await runDebugServer();
 }
 /** True when this file is the process entry (the bin), not an import. */
@@ -1207,6 +2313,6 @@ if (isEntrypoint()) main().catch((err) => {
 	process.exitCode = 1;
 });
 //#endregion
-export { parseMode };
+export { parseMode, parseTarget };
 
 //# sourceMappingURL=cli.js.map