@ait-co/devtools 0.1.43 → 0.1.44

package/dist/mcp/cli.js

@@ -53,6 +53,98 @@ var ChiiAitSource = class {
 	}
 };
 //#endregion
+//#region src/mcp/log.ts
+/**
+* Allowed field keys that may pass through to a log line.
+* Unknown keys are dropped. Values are still redact-scanned.
+*/
+const ALLOWED_KEYS = new Set([
+	"ts",
+	"level",
+	"event",
+	"msg",
+	"port",
+	"totpEnabled",
+	"env",
+	"tool",
+	"deploymentId",
+	"errorKind",
+	"reason",
+	"prevTargetId",
+	"mode"
+]);
+/**
+* Patterns that match secret values.
+* Match order matters — more-specific patterns first.
+*
+* #268 redact script covers: relay=wss://…, at=<TOTP>, _deploymentId=<uuid>.
+* Here we extend to in-process value-level patterns used in server logs.
+*/
+const SECRET_PATTERNS = [
+	/^\d{6}$/,
+	/^(aitcc_|AITCC_)/i,
+	/^[A-Za-z0-9_-]+=.{4,}/,
+	/^wss:\/\//,
+	/(?:^|[?&])at=[A-Z0-9]{6}/i
+];
+/**
+* Returns `true` when the string value matches any known-secret pattern.
+* Only string values are tested — numbers/booleans are always safe.
+*/
+function isSecretValue(value) {
+	return SECRET_PATTERNS.some((re) => re.test(value));
+}
+/**
+* Redacts a single scalar value.
+* - strings: return "***" if the value matches a secret pattern.
+* - other: return as-is.
+*/
+function redactValue(value) {
+	if (typeof value === "string" && isSecretValue(value)) return "***";
+	return value;
+}
+/**
+* Builds a safe log payload from raw fields.
+*
+* - Only keys in `ALLOWED_KEYS` are included.
+* - String values are scanned for secret patterns and replaced with "***".
+* - `ts` and `level` and `event` are always included (they are injected by the
+*   logger functions below, not by callers).
+*/
+function buildPayload(level, event, fields) {
+	const out = {
+		ts: (/* @__PURE__ */ new Date()).toISOString(),
+		level,
+		event
+	};
+	for (const [key, value] of Object.entries(fields)) {
+		if (!ALLOWED_KEYS.has(key)) continue;
+		if (key === "ts" || key === "level" || key === "event") continue;
+		out[key] = redactValue(value);
+	}
+	return out;
+}
+/**
+* Writes a single JSON log line to stderr.
+* MCP stdio transport uses stdout; all diagnostics go to stderr.
+*/
+function writeLog(level, event, fields = {}) {
+	const payload = buildPayload(level, event, fields);
+	process.stderr.write(`${JSON.stringify(payload)}\n`);
+}
+/** Log an informational structured event. */
+function logInfo(event, fields = {}) {
+	writeLog("info", event, fields);
+}
+/** Log a warning structured event. */
+function logWarn(event, fields = {}) {
+	writeLog("warn", event, fields);
+}
+/** Log an error structured event. */
+function logError(event, fields = {}) {
+	writeLog("error", event, fields);
+}
+//#endregion
 //#region src/mcp/chii-connection.ts
 /**
 * Production `CdpConnection` backed by the local Chii relay.
@@ -176,7 +268,7 @@ var ChiiCdpConnection = class {
 		}
 		if (newestTargetId !== null && this.activeTargetId !== null && newestTargetId !== this.activeTargetId) {
 			const prevId = this.activeTargetId;
-			process.stderr.write(`[ait-debug] 이전 page 세션 종료 — 새 attach로 교체 (prev=${prevId})\n`);
+			logInfo("page.detached", { prevTargetId: prevId });
 			this.evictTarget(prevId);
 		}
 		this.targets.clear();
@@ -824,6 +916,88 @@ function getEnvironmentReason(input = {}) {
 	return "default-mock";
 }
 //#endregion
+//#region src/mcp/errors.ts
+/**
+* 한국어 한 줄 "원인 + 다음 행동" 포맷으로 에러 결과를 빌드한다.
+*
+* @param message - 사용자에게 보여줄 에러 본문 (원인 + 다음 행동 포함).
+*/
+function mcpError(message) {
+	return {
+		content: [{
+			type: "text",
+			text: message
+		}],
+		isError: true
+	};
+}
+/**
+* Tier A/B 환경 불일치 거부 메시지.
+*
+* @param toolName    - 거부된 tool 이름.
+* @param requiredEnv - 해당 tool이 요구하는 환경 ('mock' | 'relay').
+* @param currentEnv  - 현재 세션 환경.
+* @param reason      - 환경이 결정된 근거 (EnvironmentReason 문자열).
+*/
+function tierRejectionError(toolName, requiredEnv, currentEnv, reason) {
+	return mcpError(`${`${toolName}은 ${requiredEnv === "relay" ? "relay (실기기 연결)" : "mock (로컬 브라우저)"} 환경에서만 사용할 수 있습니다. 현재 환경: ${currentEnv === "relay" ? "relay" : "mock"} (${reason}). ${requiredEnv === "relay" ? "build_attach_url → QR 스캔으로 실기기를 attach하세요." : "MCP_ENV=mock 또는 relay 환경변수를 확인하세요."}`}\n\n${`tool ${toolName} is available only in ${requiredEnv}. Current environment is ${currentEnv} (${reason}).`}`);
+}
+/**
+* 상태 1: tunnel 미가동 — cloudflared 터널이 아직 뜨지 않았다.
+*
+* `build_attach_url` 호출 시 tunnel.up === false 인 경우.
+*/
+function tunnelDownError() {
+	return mcpError("cloudflared 터널이 안 떠 있습니다. MCP 서버를 재시작하거나 잠시 후 list_pages로 터널 상태를 다시 확인하세요.");
+}
+/**
+* 상태 2: page 미attach — 터널은 살아 있으나 아직 페이지가 연결되지 않았다.
+*
+* enableDomains()가 "No mini-app page attached" 에러를 던질 때.
+*/
+function pageMissingError(toolName) {
+	return mcpError(`${toolName ? `${toolName}: ` : ""}페이지가 attach 안 됨. build_attach_url로 deep link를 생성하고 QR을 스캔해 미니앱을 attach하세요.`);
+}
+/**
+* 상태 3: page crash — 연결됐던 페이지가 crash/destroy됐다.
+*
+* chii-connection 이 'replaced-by-new-attach' / 'targetCrashed' / 'targetDestroyed' 를
+* 던질 때 이 메시지를 사용한다.
+*/
+function pageCrashError(toolName) {
+	return mcpError(`${toolName ? `${toolName}: ` : ""}페이지가 crash됐습니다. 토스 앱을 재실행한 뒤 build_attach_url → QR 스캔으로 재attach하세요.`);
+}
+/**
+* 상태 4: SDK 부재 — window.__sdkCall이 주입되지 않았다 (dogfood 빌드가 아님).
+*
+* call_sdk 호출 시 브리지가 없을 때.
+*/
+function sdkAbsentError(toolName) {
+	return mcpError(`${toolName ? `${toolName}: ` : ""}window.__sdkCall이 주입되지 않았습니다 (dogfood 빌드가 아닙니다). dogfood 채널(intoss-private)로 번들을 재배포한 뒤 재시도하세요.`);
+}
+/**
+* relay WebSocket 연결이 끊겼을 때 — 크래시가 아닌 네트워크/프로세스 종료.
+*/
+function relayDisconnectError(toolName) {
+	return mcpError(`${toolName ? `${toolName}: ` : ""}relay 연결이 끊겼습니다. list_pages로 상태를 확인하고, 필요하면 앱을 재실행 후 재attach하세요.`);
+}
+/**
+* CDP/AIT 명령 중 발생한 예외를 4상태로 분류해 적절한 에러 결과를 반환한다.
+*
+* - SDK 부재 패턴 (`window.__sdkCall is not available`) → sdkAbsentError
+* - crash 패턴 (`replaced-by-new-attach`, `targetCrashed`, `targetDestroyed`) → pageCrashError
+* - 연결 끊김 패턴 (`relay에 연결되어 있지 않습니다`, `relay WebSocket`) → relayDisconnectError
+* - 그 외 (일반 에러) → 원본 메시지를 포함한 mcpError
+*/
+function classifyToolError(err, toolName) {
+	const message = err instanceof Error ? err.message : String(err);
+	if (message.startsWith("tunnel-down:") || message.includes("터널이 안 떠 있습니다")) return tunnelDownError();
+	if (message.startsWith("sdk-absent:") || message.includes("__sdkCall이 주입되지 않았습니다") || message.includes("window.__sdkCall is not available") || message.includes("__sdkCall") && message.includes("not available")) return sdkAbsentError(toolName);
+	if (message.includes("replaced-by-new-attach") || message.includes("targetCrashed") || message.includes("targetDestroyed") || message.includes("detachedFromTarget")) return pageCrashError(toolName);
+	if (message.includes("relay에 연결되어 있지 않습니다") || message.includes("relay WebSocket")) return relayDisconnectError(toolName);
+	return mcpError(`${toolName} 실패: ${message}\nlist_pages로 미니앱이 relay에 attach됐는지 확인하세요.`);
+}
+//#endregion
 //#region src/mcp/local-connection.ts
 /**
 * Local-browser `CdpConnection` — attaches directly to a Chromium instance
@@ -1427,6 +1601,15 @@ function removeLock(lockPath) {
 	} catch {}
 }
 /**
+* Reads the current lock file without acquiring it. Returns the parsed
+* `LockData` when the file exists and is valid, otherwise `null`. Used by
+* `get_diagnostics` to surface the `serverLockHolder` field without
+* interfering with the running lock owner.
+*/
+function readServerLock() {
+	return readLock(lockFilePath());
+}
+/**
 * Attempts to acquire the server lock.
 *
 * - If no lock exists (or the lock is stale): writes a new lock and returns a
@@ -1757,7 +1940,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "list_pages",
-		description: "Returns the single active page (at most one) the relay sees attached. When a second page attaches, the previous one is evicted (last-attach wins — single-attach model). The result includes `singleAttachModel: true` so the agent knows the array is always 0 or 1 entries. Also returns whether the cloudflared tunnel is up and the public wss relay URL. Each page entry includes a `lastSeenAt` ISO timestamp (last inbound CDP message from that target — useful to detect stale entries when the phone app backgrounded). The result also includes `crashDetectedAt` (ISO timestamp or null): when non-null, a page crash was detected via Inspector.targetCrashed / Target.targetDestroyed since the last attach, the pages list will be empty, and `crashWarning` shows a Korean hint to re-attach. Call this first to confirm a page is attached before reading console/network.",
+		description: "Returns the single active page (at most one) the relay sees attached. When a second page attaches, the previous one is evicted (last-attach wins — single-attach model). The result includes `singleAttachModel: true` so the agent knows the array is always 0 or 1 entries. Also returns whether the cloudflared tunnel is up and the public wss relay URL. The `tunnel` field includes `droppedAt` (ISO timestamp or null/undefined): when non-null the tunnel has permanently dropped after 3 failed reissue attempts — restart the debug server with `npx @ait-co/devtools devtools-mcp`. Each page entry includes a `lastSeenAt` ISO timestamp (last inbound CDP message from that target — useful to detect stale entries when the phone app backgrounded). The result also includes `crashDetectedAt` (ISO timestamp or null): when non-null, a page crash was detected via Inspector.targetCrashed / Target.targetDestroyed since the last attach, the pages list will be empty, and `crashWarning` shows a Korean hint to re-attach. Call this first to confirm a page is attached before reading console/network.",
 		inputSchema: {
 			type: "object",
 			properties: {},
@@ -1903,6 +2086,19 @@ const DEBUG_TOOL_DEFINITIONS = [
 			required: []
 		},
 		availableIn: "both"
+	},
+	{
+		name: "get_diagnostics",
+		description: "Returns a single-call server status snapshot so the agent can diagnose \"why is this not working?\" without calling multiple tools. Fields: mcpVersion (MCP SDK version), devtoolsVersion (@ait-co/devtools package version), tunnel (up/wssUrl/pid/startedAt), pages (list_pages result + lastSeenAt stats), lastAttachAt, lastDetachAt, recentErrors (last N server-side errors, PII/secret redacted), environment (getEnvironment() result + reason), serverLockHolder (pid + startedAt from the lock file, or null). All fields are nullable — missing data is null, not an error. Tier C (both mock and relay). Call this first when debugging session state.",
+		inputSchema: {
+			type: "object",
+			properties: { recent_errors_limit: {
+				type: "number",
+				description: "Maximum number of recent server-side errors to include (default 10, max 50)."
+			} },
+			required: []
+		},
+		availableIn: "both"
 	}
 ];
 const DEBUG_TOOL_NAMES = new Set(DEBUG_TOOL_DEFINITIONS.map((t) => t.name));
@@ -1946,7 +2142,11 @@ function filterToolsByEnvironment(tools, env) {
 * 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"]);
+const BOOTSTRAP_TOOL_NAMES = new Set([
+	"build_attach_url",
+	"get_diagnostics",
+	"list_pages"
+]);
 /** Renders a CDP `RemoteObject` console arg to a stable display string. */
 function renderRemoteObject(arg) {
 	if (arg.value !== void 0) {
@@ -2058,7 +2258,7 @@ function listPages(connection, tunnel) {
 * 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.");
+	if (!tunnel.up || tunnel.wssUrl === null) throw new Error("tunnel-down: cloudflared 터널이 안 떠 있습니다. MCP 서버를 재시작하거나 잠시 후 list_pages로 터널 상태를 다시 확인하세요.");
 	const authorityWarning = validateSchemeAuthority(schemeUrl) ?? void 0;
 	return {
 		attachUrl: buildDeepLinkAttachUrl(schemeUrl, tunnel.wssUrl),
@@ -2173,8 +2373,9 @@ function isLaunchFailureStderr(stderr) {
 /**
 * 로컬 HTTP 서버 URL(`http://127.0.0.1:<port>/attach?u=...`)을 OS 기본 브라우저로 연다.
 *
-* platform별 fallback chain으로 시도하며, 모두 실패해도 `opened: false` + `httpUrl`을
-* 반환해 사용자가 직접 브라우저에 붙여넣을 수 있게 한다.
+* platform별 fallback chain으로 시도하며, 모두 실패하면 1회 retry를 수행한다
+* (ephemeral process launch 타이밍 문제 대응). retry까지 실패해도 `opened: false` +
+* `httpUrl`을 반환해 사용자가 직접 브라우저에 붙여넣을 수 있게 한다.
 *
 * SECRET-HANDLING:
 *   - tmp 파일을 만들지 않는다 (HTML/PNG는 HTTP 서버가 메모리에서 응답).
@@ -2187,25 +2388,39 @@ function isLaunchFailureStderr(stderr) {
 */
 async function openQrInBrowser(httpUrl, pngUrl) {
 	const { spawnSync } = await import("node:child_process");
-	const candidates = getBrowserCandidates(httpUrl);
-	const stderrLines = [];
-	for (const { cmd, args } of candidates) {
-		const result = spawnSync(cmd, args, {
-			encoding: "utf8",
-			timeout: 5e3
-		});
-		if (result.error) {
-			stderrLines.push(`${cmd}: ${result.error.message}`);
-			continue;
+	/**
+	* 한 번의 fallback chain 시도. 성공하면 열린 후보 cmd를 반환, 실패하면 null.
+	* stderrLines에 각 후보의 stderr를 누적한다.
+	*/
+	function tryOnce(stderrLines) {
+		const candidates = getBrowserCandidates(httpUrl);
+		for (const { cmd, args } of candidates) {
+			const result = spawnSync(cmd, args, {
+				encoding: "utf8",
+				timeout: 5e3
+			});
+			if (result.error) {
+				stderrLines.push(`${cmd}: ${result.error.message}`);
+				continue;
+			}
+			const stderr = typeof result.stderr === "string" ? result.stderr : "";
+			if (stderr) stderrLines.push(`${cmd}: ${redactSecrets(stderr.trim())}`);
+			if (result.status === 0 && !isLaunchFailureStderr(stderr)) return true;
 		}
-		const stderr = typeof result.stderr === "string" ? result.stderr : "";
-		if (stderr) stderrLines.push(`${cmd}: ${redactSecrets(stderr.trim())}`);
-		if (result.status === 0 && !isLaunchFailureStderr(stderr)) return {
-			opened: true,
-			httpUrl,
-			pngUrl
-		};
+		return false;
 	}
+	const stderrLines = [];
+	if (tryOnce(stderrLines)) return {
+		opened: true,
+		httpUrl,
+		pngUrl
+	};
+	if (tryOnce(stderrLines)) return {
+		opened: true,
+		httpUrl,
+		pngUrl,
+		retried: true
+	};
 	return {
 		opened: false,
 		httpUrl,
@@ -2451,7 +2666,7 @@ async function evaluate(connection, expression) {
 * 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)}); }})()`;
+	return `(async () => { if (typeof window.__sdkCall !== 'function') {  return JSON.stringify({ok:false,error:'sdk-absent: window.__sdkCall이 주입되지 않았습니다 (dogfood 빌드가 아닙니다). dogfood 채널로 재배포하세요.'}); } 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.
@@ -2570,6 +2785,145 @@ function getMockState(source) {
 function getOperationalEnvironment(source) {
 	return source.get("AIT.getOperationalEnvironment");
 }
+/** Secret-redaction patterns applied before error messages enter the buffer. */
+const SECRET_REDACT_PATTERNS = [
+	[/\bat=([^&\s"']+)/g, "at=<redacted>"],
+	[/((?:set-)?cookie)\s*:\s*.+/gi, "$1: <redacted>"],
+	[/AITCC_API_KEY\s*=\s*\S+/gi, "AITCC_API_KEY=<redacted>"],
+	[/Authorization\s*:\s*.+/gi, "Authorization: <redacted>"],
+	[/\bBearer\s+\S+/g, "Bearer <redacted>"]
+];
+/**
+* Applies all secret-redaction patterns to an error message string.
+* Used before storing errors in the `DiagnosticsCollector` ring buffer.
+*
+* SECRET-HANDLING: this is the single bottleneck for redaction — all error
+* strings must pass through here before reaching the buffer.
+*/
+function redactErrorMessage(message) {
+	let result = message;
+	for (const [pattern, replacement] of SECRET_REDACT_PATTERNS) result = result.replace(pattern, replacement);
+	return result;
+}
+/** Default max buffer size for the error ring buffer. */
+const DEFAULT_ERROR_BUFFER_SIZE = 50;
+/**
+* In-memory implementation of `DiagnosticsCollector`. Thread-safe in the
+* single-threaded Node.js sense (synchronous mutations only).
+*/
+var InMemoryDiagnosticsCollector = class {
+	buffer = [];
+	maxSize;
+	lastAttachAt = null;
+	lastDetachAt = null;
+	constructor(maxSize = DEFAULT_ERROR_BUFFER_SIZE) {
+		this.maxSize = maxSize;
+	}
+	recordError(message, category) {
+		const entry = {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			message: redactErrorMessage(message),
+			...category !== void 0 ? { category } : {}
+		};
+		this.buffer.push(entry);
+		if (this.buffer.length > this.maxSize) this.buffer.shift();
+	}
+	getRecentErrors(limit) {
+		const cap = Math.min(Math.max(1, limit), DEFAULT_ERROR_BUFFER_SIZE);
+		return this.buffer.length > cap ? this.buffer.slice(this.buffer.length - cap) : [...this.buffer];
+	}
+	recordAttach() {
+		this.lastAttachAt = (/* @__PURE__ */ new Date()).toISOString();
+	}
+	recordDetach() {
+		this.lastDetachAt = (/* @__PURE__ */ new Date()).toISOString();
+	}
+	getLastAttachAt() {
+		return this.lastAttachAt;
+	}
+	getLastDetachAt() {
+		return this.lastDetachAt;
+	}
+};
+/**
+* Reads the `@modelcontextprotocol/sdk` package version from the installed
+* package's `package.json`. Returns `null` on any error (missing file, JSON
+* parse failure, etc.) — diagnostics must never throw.
+*
+* Node-only — uses dynamic `import()` so it does not pollute the browser
+* module graph.
+*/
+async function readMcpSdkVersion() {
+	try {
+		const { createRequire } = await import("node:module");
+		const pkgPath = createRequire(import.meta.url).resolve("@modelcontextprotocol/sdk/package.json");
+		const { readFileSync } = await import("node:fs");
+		const raw = readFileSync(pkgPath, "utf8");
+		const parsed = JSON.parse(raw);
+		return typeof parsed.version === "string" ? parsed.version : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Returns the `@ait-co/devtools` package version injected at build time via
+* the `__VERSION__` define. Returns `null` when the global is absent (e.g. in
+* some test environments that skip the build step).
+*/
+function readDevtoolsVersion() {
+	try {
+		const v = globalThis.__VERSION__;
+		return typeof v === "string" && v.length > 0 ? v : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Builds the `get_diagnostics` response. Pure — does not throw; missing data
+* fields are `null`. Async because `readMcpSdkVersion` needs `import()`.
+*
+* SECRET-HANDLING:
+*   - `recentErrors` messages are already redacted by `recordError` (via
+*     `redactErrorMessage`). No additional redaction needed here.
+*   - `tunnel.wssUrl` is a public cloudflared hostname — not a secret.
+*   - Lock file data contains only pid + startedAt + wssUrl — no secrets.
+*/
+async function getDiagnostics(input) {
+	const { tunnel, connection, env, envReason, collector, readLock: readLockFn, recentErrorsLimit = 10, getMcpVersion = readMcpSdkVersion } = input;
+	const [mcpVersion, devtoolsVersion] = await Promise.all([getMcpVersion(), Promise.resolve(readDevtoolsVersion())]);
+	const lockData = readLockFn();
+	const serverLockHolder = lockData ? {
+		pid: lockData.pid,
+		startedAt: lockData.startedAt,
+		wssUrl: lockData.wssUrl
+	} : null;
+	const tunnelInfo = {
+		up: tunnel.up,
+		wssUrl: tunnel.wssUrl,
+		pid: lockData?.pid ?? null,
+		startedAt: lockData?.startedAt ?? null
+	};
+	let pages = null;
+	if (connection !== void 0) try {
+		pages = listPages(connection, tunnel);
+	} catch {}
+	const limit = Math.min(Math.max(1, recentErrorsLimit), 50);
+	const recentErrors = collector.getRecentErrors(limit);
+	return {
+		mcpVersion,
+		devtoolsVersion,
+		tunnel: tunnelInfo,
+		pages,
+		lastAttachAt: collector.getLastAttachAt(),
+		lastDetachAt: collector.getLastDetachAt(),
+		recentErrors,
+		environment: {
+			env,
+			reason: envReason
+		},
+		serverLockHolder
+	};
+}
 //#endregion
 //#region src/mcp/totp.ts
 /**
@@ -2660,6 +3014,15 @@ function verifyTotp(secret, code, when = Date.now(), skew = 1) {
 * and would be stale by the time a human scans. The in-app deep-link builder
 * splices the live code at attach time.
 *
+* Tunnel health probe (`TunnelHealthProbe`):
+*   After the tunnel is up, a periodic HTTP HEAD probe hits the tunnel's
+*   `https://` URL every `probeIntervalMs` (default 60 s). Two consecutive
+*   failures trigger a reissue attempt (spawn a new cloudflared quick tunnel
+*   and redirect traffic). After `MAX_REISSUE_ATTEMPTS` (3) consecutive
+*   reissue failures, the probe gives up and marks the tunnel permanently
+*   dropped — `tunnelStatus.up` becomes false with `droppedAt` set. The caller
+*   should surface this to the agent so the user knows to restart the server.
+*
 * SECRET-HANDLING: The TOTP secret and computed code values MUST NOT appear
 * in any output from this module.
 *
@@ -2782,6 +3145,118 @@ async function printAttachBanner(input) {
 	const banner = await renderAttachBanner(input);
 	process.stderr.write(`${banner}\n`);
 }
+/**
+* Probes `https://` URL with an HTTP HEAD request.
+* Returns `true` when the server responds (any HTTP status), `false` on
+* network error or timeout.
+*
+* We treat any HTTP response (including 4xx/5xx) as "tunnel alive" because
+* cloudflared itself responds to the HEAD — if the tunnel process died, the
+* request fails at the network level rather than returning a status code.
+*
+* @param httpsUrl - The `https://` tunnel URL to probe.
+* @param timeoutMs - Abort timeout in ms. Default 10 000.
+*/
+async function probeTunnel(httpsUrl, timeoutMs = 1e4) {
+	const { default: https } = await import("node:https");
+	return new Promise((resolve) => {
+		const url = new URL(httpsUrl);
+		const timer = setTimeout(() => {
+			req.destroy();
+			resolve(false);
+		}, timeoutMs);
+		const req = https.request({
+			hostname: url.hostname,
+			port: 443,
+			path: url.pathname || "/",
+			method: "HEAD"
+		}, (_res) => {
+			clearTimeout(timer);
+			_res.resume();
+			resolve(true);
+		});
+		req.on("error", () => {
+			clearTimeout(timer);
+			resolve(false);
+		});
+		req.end();
+	});
+}
+/**
+* Starts a periodic health probe for a cloudflared quick tunnel.
+*
+* Every `probeIntervalMs` the probe sends an HTTP HEAD request to the tunnel's
+* `https://` URL. When `failuresBeforeReissue` consecutive failures are
+* detected, it attempts to spawn a new tunnel (up to `MAX_REISSUE_ATTEMPTS`
+* times). On success the caller is notified via `onReissue`; on permanent
+* failure via `onPermanentDrop`.
+*
+* @returns `stop` — call during server shutdown to clear the probe interval.
+*/
+function startTunnelHealthProbe(initialTunnel, localPort, options) {
+	const { probeIntervalMs = 6e4, failuresBeforeReissue = 2, onReissue, onPermanentDrop, log = (msg) => process.stderr.write(msg), probe = probeTunnel, spawnTunnel = startQuickTunnel } = options;
+	let currentTunnel = initialTunnel;
+	let consecutiveFailures = 0;
+	let reissueAttempts = 0;
+	let stopped = false;
+	const handle = setInterval(() => {
+		(async () => {
+			if (stopped) return;
+			const httpsUrl = currentTunnel.url;
+			if (await probe(httpsUrl)) {
+				if (consecutiveFailures > 0) log("[ait-debug] tunnel health probe: tunnel recovered\n");
+				consecutiveFailures = 0;
+				reissueAttempts = 0;
+				return;
+			}
+			consecutiveFailures += 1;
+			log(`[ait-debug] tunnel health probe: failure ${consecutiveFailures}/${failuresBeforeReissue} (url=${httpsUrl})\n`);
+			if (consecutiveFailures < failuresBeforeReissue) return;
+			reissueAttempts += 1;
+			if (reissueAttempts > 3) return;
+			log(`[ait-debug] tunnel drop detected — reissuing (attempt ${reissueAttempts}/3)\n`);
+			try {
+				const newTunnel = await spawnTunnel(localPort);
+				try {
+					currentTunnel.stop();
+				} catch {}
+				currentTunnel = newTunnel;
+				consecutiveFailures = 0;
+				log(`[ait-debug] tunnel reissued — new relay: ${newTunnel.wssUrl}\n`);
+				onReissue(newTunnel);
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				log(`[ait-debug] tunnel reissue attempt ${reissueAttempts} failed: ${message}\n`);
+				if (reissueAttempts >= 3) {
+					clearInterval(handle);
+					stopped = true;
+					const droppedAt = (/* @__PURE__ */ new Date()).toISOString();
+					log(`[ait-debug] tunnel permanently dropped after 3 reissue attempts — restart the debug server to continue (npx @ait-co/devtools devtools-mcp).
+`);
+					onPermanentDrop(droppedAt);
+				}
+			}
+		})();
+	}, probeIntervalMs);
+	return { stop() {
+		stopped = true;
+		clearInterval(handle);
+	} };
+}
+/**
+* Builds a `TunnelStatus` snapshot that includes drop state.
+*
+* Convenience helper for callers (debug-server) that maintain a mutable
+* `tunnelStatus` object — keeps the shape construction in one place.
+*/
+function makeTunnelStatus(up, wssUrl, droppedAt = null, reissueAttempts = 0) {
+	return {
+		up,
+		wssUrl,
+		droppedAt,
+		reissueAttempts
+	};
+}
 //#endregion
 //#region src/mcp/debug-server.ts
 /**
@@ -2899,12 +3374,13 @@ function waitForAttachWithEvents(connection, filterFn, timeoutMs, pollIntervalMs
 * naturally via `enableDomains`). The tier only controls visibility.
 */
 function createDebugServer(deps) {
-	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep } = deps;
+	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep } = deps;
 	const resolveEnvironment = getEnvDep ?? (() => getEnvironment({ connection }));
 	const resolveEnvironmentReason = getEnvReasonDep ?? (() => getEnvironmentReason({ connection }));
+	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.43"
+		version: "0.1.44"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const env = resolveEnvironment();
@@ -2923,15 +3399,16 @@ function createDebugServer(deps) {
 		};
 		const env = resolveEnvironment();
 		if (!isToolAvailableIn(name, env)) {
-			const reason = `tool ${name} is available only in ${getToolAvailability(name)}. Current environment is ${env} (${resolveEnvironmentReason()}).`;
-			process.stderr.write(`[ait-debug] tier-filter rejected ${name}: ${reason}\n`);
-			return {
-				content: [{
-					type: "text",
-					text: reason
-				}],
-				isError: true
-			};
+			const requiredEnv = getToolAvailability(name) ?? "unknown";
+			const envReason = resolveEnvironmentReason();
+			logWarn("tool.error", {
+				tool: name,
+				errorKind: "tier-filter",
+				requiredEnv,
+				currentEnv: env,
+				envReason
+			});
+			return tierRejectionError(name, requiredEnv, env, envReason);
 		}
 		if (isAitToolName(name)) try {
 			await connection.enableDomains();
@@ -2944,19 +3421,31 @@ function createDebugServer(deps) {
 		} catch (err) {
 			return errorResult(err, name);
 		}
+		if (name === "get_diagnostics") try {
+			const rawLimit = request.params.arguments?.recent_errors_limit;
+			const recentErrorsLimit = typeof rawLimit === "number" && rawLimit > 0 ? rawLimit : 10;
+			return jsonResult$1(await getDiagnostics({
+				tunnel: getTunnelStatus(),
+				connection,
+				env: resolveEnvironment(),
+				envReason: resolveEnvironmentReason(),
+				collector,
+				readLock: readServerLock,
+				recentErrorsLimit
+			}));
+		} catch (err) {
+			return errorResult(err, name);
+		}
 		if (name === "build_attach_url") {
 			const schemeUrl = request.params.arguments?.scheme_url;
-			if (typeof schemeUrl !== "string" || schemeUrl === "") return {
-				content: [{
-					type: "text",
-					text: "build_attach_url requires a non-empty scheme_url."
-				}],
-				isError: true
-			};
+			if (typeof schemeUrl !== "string" || schemeUrl === "") return mcpError("build_attach_url: scheme_url이 비어 있습니다. `ait deploy --scheme-only`가 출력하는 intoss-private:// URL을 인자로 전달하세요.");
 			const waitForAttach = request.params.arguments?.wait_for_attach === true;
 			const openInBrowser = request.params.arguments?.open_in_browser !== false;
 			const deploymentId = extractDeploymentId(schemeUrl);
-			if (!deploymentId) process.stderr.write("[ait-debug] build_attach_url: no _deploymentId in scheme_url; matching on presence only\n");
+			if (!deploymentId) logInfo("tool.call", {
+				tool: "build_attach_url",
+				msg: "no _deploymentId in scheme_url; matching on presence only"
+			});
 			/** Returns true when the page list satisfies the attach condition. */
 			const isMatchingPage = (pages) => {
 				if (pages.length === 0) return false;
@@ -2973,10 +3462,50 @@ function createDebugServer(deps) {
 				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() && qrHttpServer) {
+				const guiAvailable = canOpenBrowser();
+				if (openInBrowser && !guiAvailable) {
+					const headlessNote = "[open_in_browser] GUI 환경이 감지되지 않았습니다 (headless/remote 환경). open_in_browser=false로 자동 폴백합니다. 텍스트 QR을 폰 카메라로 스캔하거나, 로컬 GUI 환경에서 실행하세요.\n\n";
+					const qrHeadless = await renderQr(attachUrl);
+					const headlessText = `${warningPrefix}${headlessNote}${header}\n${JSON.stringify({
+						attachUrl,
+						relayUrl
+					}, null, 2)}\n\n${qrHeadless}`;
+					if (!waitForAttach) return { content: [{
+						type: "text",
+						text: headlessText
+					}] };
+					let attachedPagesHl = [];
+					try {
+						attachedPagesHl = await waitForAttachWithEvents(connection, isMatchingPage, waitForAttachTimeoutMs);
+					} catch {
+						attachedPagesHl = connection.listTargets();
+						return {
+							content: [{
+								type: "text",
+								text: buildTimeoutError(headlessText, waitForAttachTimeoutMs / 1e3, attachedPagesHl)
+							}],
+							isError: true
+						};
+					}
+					const pagesResultHl = listPages(connection, getTunnelStatus());
+					return { content: [{
+						type: "text",
+						text: `${headlessText}\n\n${JSON.stringify(pagesResultHl, null, 2)}`
+					}] };
+				}
+				if (openInBrowser && guiAvailable && qrHttpServer) {
 					const browserResult = await openQrInBrowser(qrHttpServer.buildAttachPageUrl(attachUrl), `http://127.0.0.1:${qrHttpServer.port}/qr.png?u=${encodeURIComponent(attachUrl)}`);
 					if (browserResult.opened) {
-						const shortText = `${warningPrefix}${header}\n${JSON.stringify({ relayUrl }, null, 2)}\n\n브라우저에서 QR을 열었습니다. 폰 카메라로 스캔하세요.\nURL: ${browserResult.httpUrl}`;
+						const retriedNote = browserResult.retried ? " (1회 retry 후 성공)" : "";
+						const openResult = {
+							attempted: true,
+							succeeded: true,
+							...browserResult.retried ? { retried: true } : {}
+						};
+						const shortText = `${warningPrefix}${header}\n${JSON.stringify({
+							relayUrl,
+							openResult
+						}, null, 2)}\n\n브라우저에서 QR을 열었습니다${retriedNote}. 폰 카메라로 스캔하세요.\nURL: ${browserResult.httpUrl}`;
 						if (!waitForAttach) return { content: [{
 							type: "text",
 							text: shortText
@@ -3000,12 +3529,21 @@ function createDebugServer(deps) {
 							text: `${shortText}\n\n${JSON.stringify(pagesResult, null, 2)}`
 						}] };
 					}
+					const openResult = {
+						attempted: true,
+						succeeded: false,
+						failureReason: browserResult.error ?? "브라우저 실행 후보 모두 실패",
+						pngUrl: browserResult.pngUrl,
+						...browserResult.stderrSummary ? { stderrSummary: browserResult.stderrSummary } : {}
+					};
 					const stderrNote = browserResult.stderrSummary ? `\nstderr: ${browserResult.stderrSummary}` : "";
-					const fallbackNote = `브라우저 자동 열기에 실패했습니다. 다음 URL을 직접 브라우저에서 여세요:\n${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stderrNote + "\n\n";
+					const fallbackNote = `[open_in_browser] 브라우저 자동 열기에 실패했습니다. 다음 URL을 직접 브라우저에서 여세요:
+${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stderrNote + "\n\n";
 					const qr = await renderQr(attachUrl);
 					const baseText = `${warningPrefix}${fallbackNote}${header}\n${JSON.stringify({
 						attachUrl,
-						relayUrl
+						relayUrl,
+						openResult
 					}, null, 2)}\n\n${qr}`;
 					if (!waitForAttach) return { content: [{
 						type: "text",
@@ -3064,20 +3602,13 @@ function createDebugServer(deps) {
 		try {
 			await connection.enableDomains();
 		} catch (err) {
-			const message = err instanceof Error ? err.message : String(err);
 			if (name === "list_pages") {
 				if (connection instanceof ChiiCdpConnection) try {
 					await connection.refreshTargets();
 				} catch {}
 				return jsonResult$1(listPages(connection, getTunnelStatus()));
 			}
-			return {
-				content: [{
-					type: "text",
-					text: `${message}\nCall list_pages to confirm a mini-app has attached over the relay.`
-				}],
-				isError: true
-			};
+			return classifyEnableDomainError(err, name);
 		}
 		try {
 			switch (name) {
@@ -3105,26 +3636,16 @@ function createDebugServer(deps) {
 				case "measure_safe_area": return jsonResult$1(await measureSafeArea(connection, resolveEnvironment()));
 				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
-					};
+					if (typeof expression !== "string" || expression === "") return mcpError("evaluate: expression 인자가 비어 있습니다. 평가할 JavaScript 표현식을 전달하세요.");
 					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
-					};
+					if (typeof sdkName !== "string" || sdkName === "") return mcpError("call_sdk: name 인자가 비어 있습니다. 호출할 SDK 메서드 이름을 전달하세요.");
 					const rawArgs = request.params.arguments?.args;
-					return jsonResult$1(await callSdk(connection, sdkName, Array.isArray(rawArgs) ? rawArgs : []));
+					const sdkResult = await callSdk(connection, sdkName, Array.isArray(rawArgs) ? rawArgs : []);
+					if (!sdkResult.ok && typeof sdkResult.error === "string" && sdkResult.error.startsWith("sdk-absent:")) return sdkAbsentError("call_sdk");
+					return jsonResult$1(sdkResult);
 				}
 				default: return unknownTool(name);
 			}
@@ -3141,33 +3662,29 @@ function jsonResult$1(value) {
 	}] };
 }
 function unknownTool(name) {
-	return {
-		content: [{
-			type: "text",
-			text: `Unknown tool: ${name}`
-		}],
-		isError: true
-	};
+	return mcpError(`알 수 없는 tool: ${name}`);
 }
 /**
-* Detects whether an error is a relay/websocket disconnect error.
-* These are distinguished from "no page attached yet" errors because they
-* require enableDomains() to be called again (re-establish the websocket),
-* not just waiting for a target to appear.
+* enableDomains()가 던진 에러를 4상태로 분류해 적절한 메시지를 반환한다.
+*
+* - "No mini-app page attached" → page 미attach (상태 2)
+* - crash/destroy/replaced 패턴 → page crash (상태 3)
+* - relay disconnect 패턴 → relay 연결 끊김
+* - 그 외 → 원본 메시지 + list_pages 안내
 */
-function isDisconnectError(err) {
-	if (!(err instanceof Error)) return false;
-	const msg = err.message;
-	return msg.includes("relay에 연결되어 있지 않습니다") || msg.includes("relay WebSocket") || msg.includes("replaced-by-new-attach") || msg.includes("Chii relay connection closed");
+function classifyEnableDomainError(err, toolName) {
+	const message = err instanceof Error ? err.message : String(err);
+	if (message.includes("No mini-app page attached") || message.includes("페이지가 attach 안")) return pageMissingError(toolName);
+	if (message.includes("replaced-by-new-attach") || message.includes("targetCrashed") || message.includes("targetDestroyed") || message.includes("detachedFromTarget")) return pageCrashError(toolName);
+	if (message.includes("relay에 연결되어 있지 않습니다") || message.includes("relay WebSocket") || message.includes("Chii relay connection closed")) return relayDisconnectError(toolName);
+	return classifyToolError(err, toolName);
 }
+/**
+* CDP/AIT 명령 실행 중 catch된 에러를 4상태로 분류해 tool 결과로 반환한다.
+* debug-server 내부 try/catch 블록에서 공통으로 사용한다.
+*/
 function errorResult(err, name) {
-	return {
-		content: [{
-			type: "text",
-			text: `${name} failed: ${err instanceof Error ? err.message : String(err)}${isDisconnectError(err) ? "\n\nrelay 연결이 끊겼습니다. list_pages → enableDomains() 재호출로 재연결하세요. 폰이 백그라운드로 내려갔거나 미니앱이 종료됐을 수 있습니다." : "\nCall list_pages to confirm a mini-app has attached over the relay."}`
-		}],
-		isError: true
-	};
+	return classifyToolError(err, name);
 }
 /**
 * Starts a polling watcher that detects the first 0→N target transition on
@@ -3247,27 +3764,45 @@ async function runDebugServer(options = {}) {
 		port: relayPort,
 		verifyAuth
 	});
+	logInfo("server.start", {
+		port: relay.port,
+		totpEnabled
+	});
 	let tunnel = null;
-	let tunnelStatus = {
-		up: false,
-		wssUrl: null
-	};
+	let tunnelStatus = makeTunnelStatus(false, null);
 	generateAttachToken();
+	let tunnelProbe = null;
 	startQuickTunnel(relay.port).then((t) => {
 		tunnel = t;
-		tunnelStatus = {
-			up: true,
-			wssUrl: t.wssUrl
-		};
+		tunnelStatus = makeTunnelStatus(true, t.wssUrl);
 		lockHandle.updateWssUrl(t.wssUrl);
+		logInfo("tunnel.up", { totpEnabled });
+		tunnelProbe = startTunnelHealthProbe(t, relay.port, {
+			onReissue: (newTunnel) => {
+				tunnel = newTunnel;
+				tunnelStatus = makeTunnelStatus(true, newTunnel.wssUrl, null, 0);
+				lockHandle.updateWssUrl(newTunnel.wssUrl);
+				printAttachBanner({
+					wssUrl: newTunnel.wssUrl,
+					totpEnabled
+				}).then(() => {
+					logInfo("tunnel.up", {
+						totpEnabled,
+						reissued: true
+					});
+				});
+			},
+			onPermanentDrop: (droppedAt) => {
+				tunnelStatus = makeTunnelStatus(false, null, droppedAt, 3);
+				logError("tunnel.down", { msg: `tunnel permanently dropped (${droppedAt}). Restart: npx @ait-co/devtools devtools-mcp` });
+			}
+		});
 		return printAttachBanner({
 			wssUrl: t.wssUrl,
 			totpEnabled
 		});
 	}, (err) => {
-		const message = err instanceof Error ? err.message : String(err);
-		process.stderr.write(`[ait-debug] Failed to open cloudflared quick tunnel: ${message}\n[ait-debug] The relay is up locally; attach over the public URL is unavailable until the tunnel starts.
-`);
+		logError("tunnel.down", { msg: `Failed to open cloudflared quick tunnel: ${err instanceof Error ? err.message : String(err)}. The relay is up locally; attach over the public URL is unavailable until the tunnel starts.` });
 	});
 	const connection = new ChiiCdpConnection({ relayBaseUrl: relay.baseUrl });
 	const aitSource = new ChiiAitSource(connection);
@@ -3275,17 +3810,18 @@ async function runDebugServer(options = {}) {
 	try {
 		qrServer = await startQrHttpServer();
 	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		process.stderr.write(`[ait-debug] QR HTTP 서버 시작 실패 (text QR fallback 사용): ${message}\n`);
+		logWarn("server.start", { msg: `QR HTTP 서버 시작 실패 (text QR fallback 사용): ${err instanceof Error ? err.message : String(err)}` });
 	}
 	const devtoolsOpener = new AutoDevtoolsOpener();
+	const diagnosticsCollector = new InMemoryDiagnosticsCollector();
 	const server = createDebugServer({
 		connection,
 		aitSource,
 		getTunnelStatus: () => tunnelStatus,
 		get qrHttpServer() {
 			return qrServer;
-		}
+		},
+		diagnosticsCollector
 	});
 	const transport = new StdioServerTransport();
 	let closed = false;
@@ -3294,6 +3830,7 @@ async function runDebugServer(options = {}) {
 		if (closed) return;
 		closed = true;
 		attachWatcher?.stop();
+		tunnelProbe?.stop();
 		connection.close();
 		tunnel?.stop();
 		relay.close();
@@ -3308,22 +3845,30 @@ async function runDebugServer(options = {}) {
 		if (!closed) {
 			closed = true;
 			attachWatcher?.stop();
+			tunnelProbe?.stop();
 			tunnel?.stop();
 			lockHandle.release();
 		}
 	});
 	process.on("uncaughtException", (err) => {
-		process.stderr.write(`[ait-debug] uncaughtException: ${String(err)}\n`);
+		logError("tool.error", {
+			msg: `uncaughtException: ${String(err)}`,
+			errorKind: "uncaught"
+		});
 		shutdown();
 		process.exit(1);
 	});
 	process.on("unhandledRejection", (reason) => {
-		process.stderr.write(`[ait-debug] unhandledRejection: ${String(reason)}\n`);
+		logError("tool.error", {
+			msg: `unhandledRejection: ${String(reason)}`,
+			errorKind: "unhandled-rejection"
+		});
 		shutdown();
 		process.exit(1);
 	});
 	await server.connect(transport);
 	attachWatcher = startAttachWatcher(connection, server, 1e3, () => {
+		diagnosticsCollector.recordAttach();
 		devtoolsOpener.open(tunnelStatus.wssUrl, getEnvironment({ connection }));
 	});
 }
@@ -3387,12 +3932,20 @@ async function runLocalDebugServer(options = {}) {
 		}
 	});
 	process.on("uncaughtException", (err) => {
-		process.stderr.write(`[ait-local-debug] uncaughtException: ${String(err)}\n`);
+		logError("tool.error", {
+			msg: `uncaughtException: ${String(err)}`,
+			errorKind: "uncaught",
+			mode: "local"
+		});
 		shutdown();
 		process.exit(1);
 	});
 	process.on("unhandledRejection", (reason) => {
-		process.stderr.write(`[ait-local-debug] unhandledRejection: ${String(reason)}\n`);
+		logError("tool.error", {
+			msg: `unhandledRejection: ${String(reason)}`,
+			errorKind: "unhandled-rejection",
+			mode: "local"
+		});
 		shutdown();
 		process.exit(1);
 	});
@@ -3528,47 +4081,23 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.43"
+		version: "0.1.44"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
 		const name = request.params.name;
-		if (!DEV_TOOL_NAMES.has(name)) return {
-			content: [{
-				type: "text",
-				text: `Unknown tool: ${name}`
-			}],
-			isError: true
-		};
+		if (!DEV_TOOL_NAMES.has(name)) return mcpError(`알 수 없는 tool: ${name}`);
 		try {
 			const effective = name === "devtools_get_mock_state" ? "AIT.getMockState" : name;
-			if (!isAitToolName(effective)) return {
-				content: [{
-					type: "text",
-					text: `Unknown tool: ${name}`
-				}],
-				isError: true
-			};
+			if (!isAitToolName(effective)) return mcpError(`알 수 없는 tool: ${name}`);
 			switch (effective) {
 				case "AIT.getMockState": return jsonResult(await getMockState(aitSource));
 				case "AIT.getOperationalEnvironment": return jsonResult(await getOperationalEnvironment(aitSource));
 				case "AIT.getSdkCallHistory": return jsonResult(await getSdkCallHistory(aitSource));
-				default: return {
-					content: [{
-						type: "text",
-						text: `Unknown tool: ${name}`
-					}],
-					isError: true
-				};
+				default: return mcpError(`알 수 없는 tool: ${name}`);
 			}
 		} catch (err) {
-			return {
-				content: [{
-					type: "text",
-					text: `${err instanceof Error ? err.message : String(err)}\nIs the Vite dev server running with the @ait-co/devtools unplugin option \`mcp: true\`? Is AIT_DEVTOOLS_URL set correctly?`
-				}],
-				isError: true
-			};
+			return mcpError(`${name} 실패: ${err instanceof Error ? err.message : String(err)}\nVite dev 서버가 @ait-co/devtools unplugin \`mcp: true\` 옵션으로 실행 중인지 확인하세요. AIT_DEVTOOLS_URL 환경변수가 올바르게 설정됐는지도 확인하세요.`);
 		}
 	});
 	return server;