@ait-co/devtools 0.1.45 → 0.1.46

package/README.en.md

@@ -101,6 +101,10 @@ The page on the phone died (OOM, JS exception, or native bridge crash). Relaunch
 
 When `call_sdk` returns `ok: false, error: "window.__sdkCall is not available"`, a non-dogfood bundle is loaded. Redeploy through the dogfood channel with the `__DEBUG_BUILD__` flag enabled and try again. This error is the expected result in environment 2 (PWA). (Related: [#285](https://github.com/apps-in-toss-community/devtools/issues/285))
 
+**"QR scanned but auth rejected" — TOTP code expired**
+
+When `AIT_DEBUG_TOTP_SECRET` is set, `build_attach_url` automatically splices the current one-time TOTP code (`at=`) into the returned `attachUrl`. The code is valid for a 30-second step. Scanning after `totp.expiresAt` causes the relay to reject the request. Fix: call `build_attach_url` again to get a fresh URL and QR, then scan within 30 seconds.
+
 ---
 
 ## Install

package/README.md

@@ -101,6 +101,10 @@ cloudflared quick tunnel은 수 시간 후 drop될 수 있습니다. `devtools-m
 
 `call_sdk` 호출 시 `ok: false, error: "window.__sdkCall is not available"` 에러가 뜨면 dogfood 빌드가 아닌 일반 번들이 로드된 것입니다. `__DEBUG_BUILD__` 플래그가 켜진 dogfood 채널로 재배포 후 다시 시도하세요. 환경 2(PWA)에서는 이 에러가 예상 결과입니다. (관련: [#285](https://github.com/apps-in-toss-community/devtools/issues/285))
 
+**"QR 스캔했는데 인증 실패" — TOTP 만료**
+
+`AIT_DEBUG_TOTP_SECRET` 설정 시 `build_attach_url`이 반환하는 attachUrl에는 30초 유효 TOTP 코드(`at=`)가 자동으로 포함됩니다. 응답의 `totp.expiresAt` 이후 스캔하면 relay가 인증을 거부합니다. 해결: `build_attach_url`을 재호출해 새 URL과 QR을 발급받은 뒤 30초 이내에 스캔하세요.
+
 ---
 
 ## 설치

package/dist/mcp/cli.js

@@ -848,6 +848,51 @@ var AutoDevtoolsOpener = class {
 	}
 };
 //#endregion
+//#region src/mcp/envelope.ts
+/**
+* Returns `true` when `AIT_MCP_COMPAT=chrome-devtools` is set, which bypasses
+* envelope wrapping and returns raw payloads (0.1.x back-compat).
+*/
+function isCompatMode() {
+	return process.env.AIT_MCP_COMPAT === "chrome-devtools";
+}
+/**
+* Maps `McpEnvironment` to `EnvelopeEnv`. After #307 these are the same
+* union (`mock | relay-dev | relay-live`), so this is identity — kept as a
+* named export for surface stability if envelope env diverges in the future.
+*/
+function toEnvelopeEnv(env) {
+	return env;
+}
+/**
+* Wraps `data` in a `ToolEnvelope<T>` **unless** compat mode is active, in
+* which case `data` is returned as-is.
+*
+* Use this at every tool call-site in `debug-server.ts` and `server.ts`.
+*
+* @example
+* ```ts
+* return jsonResult(wrapEnvelope(listPages(connection, tunnel), {
+*   tool: 'list_pages',
+*   env: resolveEnvironment(),
+*   attached: connection.listTargets().length > 0,
+* }));
+* ```
+*/
+function wrapEnvelope(data, ctx) {
+	if (isCompatMode()) return data;
+	return {
+		ok: true,
+		data,
+		meta: {
+			tool: ctx.tool,
+			env: toEnvelopeEnv(ctx.env),
+			attached: ctx.attached,
+			contentType: ctx.contentType ?? "json"
+		}
+	};
+}
+//#endregion
 //#region src/mcp/environment.ts
 /**
 * Returns `true` when the environment is any relay variant (`relay-dev` or
@@ -2013,6 +2058,83 @@ function warnPassthrough(name) {
 }
 SIGNATURES.map((s) => s.name);
 //#endregion
+//#region src/mcp/totp.ts
+/**
+* RFC 6238 TOTP implementation (Node.js, node:crypto only).
+*
+* External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used
+* to keep the dependency surface minimal. This hand-roll is ~30 lines and
+* covers exactly what relay-side auth needs.
+*
+* Algorithm summary (RFC 6238 + RFC 4226):
+*   T  = floor(now / 30)          — 30-second time step counter
+*   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)
+*   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)
+*   offset = MAC[19] & 0x0f
+*   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits
+*
+* Security note (keep this comment accurate):
+*   The baked-in secret in a dogfood build is extractable from the bundle by a
+*   determined reverse engineer. This mechanism raises the bar from
+*   "anyone with the URL" to "URL + bundle extraction + live TOTP calculation".
+*   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are
+*   blocked; deliberate reverse engineering is not. See threat model in
+*   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.
+*
+* SECRET-HANDLING: secret values and computed codes MUST NOT appear in any
+* log, error message, or string visible outside this module. Only boolean
+* pass/fail and reason enum values are safe to surface.
+*/
+/** Time step window in seconds (RFC 6238 default). */
+const TIME_STEP = 30;
+/** Number of digits in the generated code. */
+const DIGITS = 6;
+/**
+* Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-
+* clock time.
+*
+* @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32
+*   bytes). Must be the output of `generateAttachToken()` or compatible.
+* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
+* @returns A zero-padded 6-digit decimal string, e.g. `"042193"`.
+*/
+function generateTotp(secret, when = Date.now()) {
+	const key = Buffer.from(secret, "hex");
+	const counter = Math.max(0, Math.floor(when / 1e3 / TIME_STEP));
+	const counterBuf = Buffer.alloc(8);
+	const hi = Math.floor(counter / 4294967296);
+	const lo = counter >>> 0;
+	counterBuf.writeUInt32BE(hi, 0);
+	counterBuf.writeUInt32BE(lo, 4);
+	const mac = createHmac("sha1", key).update(counterBuf).digest();
+	const offset = mac[19] & 15;
+	return (((mac[offset] & 127) << 24 | (mac[offset + 1] & 255) << 16 | (mac[offset + 2] & 255) << 8 | mac[offset + 3] & 255) % 10 ** DIGITS).toString().padStart(DIGITS, "0");
+}
+/**
+* Verifies a TOTP code against the secret, accepting ±`skew` time steps to
+* tolerate clock drift between the relay host and the client device.
+*
+* Uses `timingSafeEqual` for constant-time comparison to prevent timing
+* side-channel attacks.
+*
+* @param secret - Hex-encoded shared secret.
+* @param code - The 6-digit code to verify (string or numeric).
+* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
+* @param skew - Number of adjacent steps to accept on either side. Default 1
+*   (accepts T-1, T, T+1 — a 90-second acceptance window).
+* @returns `true` if the code matches any accepted step, `false` otherwise.
+*/
+function verifyTotp(secret, code, when = Date.now(), skew = 1) {
+	const normalised = String(code).padStart(DIGITS, "0");
+	if (normalised.length !== DIGITS || !/^\d{6}$/.test(normalised)) return false;
+	const candidateBuf = Buffer.from(normalised, "utf8");
+	for (let delta = -skew; delta <= skew; delta++) {
+		const expected = generateTotp(secret, when + delta * TIME_STEP * 1e3);
+		if (timingSafeEqual(Buffer.from(expected, "utf8"), candidateBuf)) return true;
+	}
+	return false;
+}
+//#endregion
 //#region src/mcp/tools.ts
 /** Static MCP tool descriptors (name + JSONSchema) for the full debug tool surface. */
 const DEBUG_TOOL_DEFINITIONS = [
@@ -2048,7 +2170,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "build_attach_url",
-		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. If the tunnel is not up, restart the MCP server: `npx @ait-co/devtools devtools-mcp`. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 30 s by default), then returns the attached page info too. On timeout, call build_attach_url again to resume polling. 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). Requires MCP_ENV=relay (set automatically when a relay tunnel is detected).",
+		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. If the tunnel is not up, restart the MCP server: `npx @ait-co/devtools devtools-mcp`. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 30 s by default), then returns the attached page info too. On timeout, call build_attach_url again to resume polling. 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). Requires MCP_ENV=relay-dev or relay-live (set automatically in debug-mode default).\n\nTOTP auth: when AIT_DEBUG_TOTP_SECRET is set on the MCP server, the returned attachUrl automatically includes the current one-time code (at=<code>) — the URL is single-use for that 30-second step. The response includes a `totp` field with `expiresAt` (ISO timestamp). If the phone scan happens after expiresAt, the relay will reject the code — just call build_attach_url again to get a fresh one-time URL. Without AIT_DEBUG_TOTP_SECRET, the attachUrl has no expiry.",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -2364,20 +2486,50 @@ function listPages(connection, tunnel) {
 * 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.
 *
+* When `AIT_DEBUG_TOTP_SECRET` is set, generates the current TOTP code and
+* splices it as `at=<code>` into the attach URL. The code is valid for one
+* 30-second time step (±1 skew accepted by the relay, so the effective window
+* is up to 90 s). If the scan happens after `totp.expiresAt`, call
+* `build_attach_url` again to get a fresh code.
+*
 * 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).
+*
+* SECRET-HANDLING: `totpSecret` (if provided) is used only to compute a code
+* and must never appear in any log, error message, or output outside of the
+* spliced `at=` param in `attachUrl`.
+*
+* @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL.
+* @param tunnel - Current tunnel status from the running debug server.
+* @param totpSecret - Optional hex-encoded TOTP secret (from
+*   `AIT_DEBUG_TOTP_SECRET`). When provided, the current code is spliced into
+*   the attach URL as `at=<code>`.
 */
-function buildAttachUrl(schemeUrl, tunnel) {
+function buildAttachUrl(schemeUrl, tunnel, totpSecret) {
 	if (!tunnel.up || tunnel.wssUrl === null) throw new Error("tunnel-down: cloudflared 터널이 안 떠 있습니다. MCP 서버를 재시작하거나 잠시 후 list_pages로 터널 상태를 다시 확인하세요.");
 	const authorityWarning = validateSchemeAuthority(schemeUrl) ?? void 0;
+	let totpCode;
+	let totpMeta;
+	if (totpSecret !== void 0 && totpSecret !== "") {
+		const now = Date.now();
+		totpCode = generateTotp(totpSecret, now);
+		const STEP_SECONDS = 30;
+		const expiresAtMs = (Math.floor(now / 1e3 / STEP_SECONDS) + 1) * STEP_SECONDS * 1e3;
+		totpMeta = {
+			enabled: true,
+			ttlSeconds: STEP_SECONDS,
+			expiresAt: new Date(expiresAtMs).toISOString()
+		};
+	}
 	return {
-		attachUrl: buildDeepLinkAttachUrl(schemeUrl, tunnel.wssUrl),
+		attachUrl: buildDeepLinkAttachUrl(schemeUrl, tunnel.wssUrl, totpCode),
 		relayUrl: tunnel.wssUrl,
-		...authorityWarning !== void 0 ? { authorityWarning } : {}
+		...authorityWarning !== void 0 ? { authorityWarning } : {},
+		...totpMeta !== void 0 ? { totp: totpMeta } : {}
 	};
 }
 /**
@@ -3069,83 +3221,6 @@ async function getDiagnostics(input) {
 	};
 }
 //#endregion
-//#region src/mcp/totp.ts
-/**
-* RFC 6238 TOTP implementation (Node.js, node:crypto only).
-*
-* External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used
-* to keep the dependency surface minimal. This hand-roll is ~30 lines and
-* covers exactly what relay-side auth needs.
-*
-* Algorithm summary (RFC 6238 + RFC 4226):
-*   T  = floor(now / 30)          — 30-second time step counter
-*   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)
-*   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)
-*   offset = MAC[19] & 0x0f
-*   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits
-*
-* Security note (keep this comment accurate):
-*   The baked-in secret in a dogfood build is extractable from the bundle by a
-*   determined reverse engineer. This mechanism raises the bar from
-*   "anyone with the URL" to "URL + bundle extraction + live TOTP calculation".
-*   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are
-*   blocked; deliberate reverse engineering is not. See threat model in
-*   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.
-*
-* SECRET-HANDLING: secret values and computed codes MUST NOT appear in any
-* log, error message, or string visible outside this module. Only boolean
-* pass/fail and reason enum values are safe to surface.
-*/
-/** Time step window in seconds (RFC 6238 default). */
-const TIME_STEP = 30;
-/** Number of digits in the generated code. */
-const DIGITS = 6;
-/**
-* Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-
-* clock time.
-*
-* @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32
-*   bytes). Must be the output of `generateAttachToken()` or compatible.
-* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
-* @returns A zero-padded 6-digit decimal string, e.g. `"042193"`.
-*/
-function generateTotp(secret, when = Date.now()) {
-	const key = Buffer.from(secret, "hex");
-	const counter = Math.max(0, Math.floor(when / 1e3 / TIME_STEP));
-	const counterBuf = Buffer.alloc(8);
-	const hi = Math.floor(counter / 4294967296);
-	const lo = counter >>> 0;
-	counterBuf.writeUInt32BE(hi, 0);
-	counterBuf.writeUInt32BE(lo, 4);
-	const mac = createHmac("sha1", key).update(counterBuf).digest();
-	const offset = mac[19] & 15;
-	return (((mac[offset] & 127) << 24 | (mac[offset + 1] & 255) << 16 | (mac[offset + 2] & 255) << 8 | mac[offset + 3] & 255) % 10 ** DIGITS).toString().padStart(DIGITS, "0");
-}
-/**
-* Verifies a TOTP code against the secret, accepting ±`skew` time steps to
-* tolerate clock drift between the relay host and the client device.
-*
-* Uses `timingSafeEqual` for constant-time comparison to prevent timing
-* side-channel attacks.
-*
-* @param secret - Hex-encoded shared secret.
-* @param code - The 6-digit code to verify (string or numeric).
-* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
-* @param skew - Number of adjacent steps to accept on either side. Default 1
-*   (accepts T-1, T, T+1 — a 90-second acceptance window).
-* @returns `true` if the code matches any accepted step, `false` otherwise.
-*/
-function verifyTotp(secret, code, when = Date.now(), skew = 1) {
-	const normalised = String(code).padStart(DIGITS, "0");
-	if (normalised.length !== DIGITS || !/^\d{6}$/.test(normalised)) return false;
-	const candidateBuf = Buffer.from(normalised, "utf8");
-	for (let delta = -skew; delta <= skew; delta++) {
-		const expected = generateTotp(secret, when + delta * TIME_STEP * 1e3);
-		if (timingSafeEqual(Buffer.from(expected, "utf8"), candidateBuf)) return true;
-	}
-	return false;
-}
-//#endregion
 //#region src/mcp/tunnel.ts
 /**
 * cloudflared quick tunnel + attach banner for the debug-mode MCP server.
@@ -3518,7 +3593,7 @@ 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, diagnosticsCollector: collectorDep, defaultEnv } = deps;
+	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer, getEnvironment: getEnvDep, getEnvironmentReason: getEnvReasonDep, diagnosticsCollector: collectorDep, defaultEnv, totpSecret } = deps;
 	const resolveEnvironment = getEnvDep ?? (() => getEnvironment({
 		connection,
 		defaultEnv
@@ -3530,7 +3605,7 @@ function createDebugServer(deps) {
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.45"
+		version: "0.1.46"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const env = resolveEnvironment();
@@ -3574,7 +3649,7 @@ function createDebugServer(deps) {
 		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({
+			const result = await getDiagnostics({
 				tunnel: getTunnelStatus(),
 				connection,
 				env: resolveEnvironment(),
@@ -3582,7 +3657,9 @@ function createDebugServer(deps) {
 				collector,
 				readLock: readServerLock,
 				recentErrorsLimit
-			}));
+			});
+			const attached = connection.listTargets().length > 0;
+			return envelopeResult(result, name, resolveEnvironment(), attached);
 		} catch (err) {
 			return errorResult(err, name);
 		}
@@ -3609,7 +3686,7 @@ function createDebugServer(deps) {
 				return `${baseText}\n\nNo page${deploymentId ? ` matching deploymentId=${deploymentId}` : ""} attached within ${timeoutSec}s${observedNote} — call list_pages to retry.`;
 			};
 			try {
-				const { attachUrl, relayUrl, authorityWarning } = buildAttachUrl(schemeUrl, getTunnelStatus());
+				const { attachUrl, relayUrl, authorityWarning, totp } = buildAttachUrl(schemeUrl, getTunnelStatus(), totpSecret);
 				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).";
 				const guiAvailable = canOpenBrowser();
@@ -3618,7 +3695,8 @@ function createDebugServer(deps) {
 					const qrHeadless = await renderQr(attachUrl);
 					const headlessText = `${warningPrefix}${headlessNote}${header}\n${JSON.stringify({
 						attachUrl,
-						relayUrl
+						relayUrl,
+						...totp ? { totp } : {}
 					}, null, 2)}\n\n${qrHeadless}`;
 					if (!waitForAttach) return { content: [{
 						type: "text",
@@ -3654,7 +3732,8 @@ function createDebugServer(deps) {
 						};
 						const shortText = `${warningPrefix}${header}\n${JSON.stringify({
 							relayUrl,
-							openResult
+							openResult,
+							...totp ? { totp } : {}
 						}, null, 2)}\n\n브라우저에서 QR을 열었습니다${retriedNote}. 폰 카메라로 스캔하세요.\nURL: ${browserResult.httpUrl}`;
 						if (!waitForAttach) return { content: [{
 							type: "text",
@@ -3693,7 +3772,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					const baseText = `${warningPrefix}${fallbackNote}${header}\n${JSON.stringify({
 						attachUrl,
 						relayUrl,
-						openResult
+						openResult,
+						...totp ? { totp } : {}
 					}, null, 2)}\n\n${qr}`;
 					if (!waitForAttach) return { content: [{
 						type: "text",
@@ -3721,7 +3801,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 				const qr = await renderQr(attachUrl);
 				const baseText = `${warningPrefix}${header}\n${JSON.stringify({
 					attachUrl,
-					relayUrl
+					relayUrl,
+					...totp ? { totp } : {}
 				}, null, 2)}\n\n${qr}`;
 				if (!waitForAttach) return { content: [{
 					type: "text",
@@ -3756,7 +3837,9 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 				if (connection instanceof ChiiCdpConnection) try {
 					await connection.refreshTargets();
 				} catch {}
-				return jsonResult$1(listPages(connection, getTunnelStatus()));
+				const pagesData = listPages(connection, getTunnelStatus());
+				const attached = connection.listTargets().length > 0;
+				return envelopeResult(pagesData, name, resolveEnvironment(), attached);
 			}
 			return classifyEnableDomainError(err, name);
 		}
@@ -3768,11 +3851,14 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					return jsonResult$1({ exceptions: listExceptions(connection, typeof rawLimit === "number" && rawLimit > 0 ? rawLimit : 50) });
 				}
 				case "list_network_requests": return jsonResult$1(listNetworkRequests(connection));
-				case "list_pages":
+				case "list_pages": {
 					if (connection instanceof ChiiCdpConnection) try {
 						await connection.refreshTargets();
 					} catch {}
-					return jsonResult$1(listPages(connection, getTunnelStatus()));
+					const listPagesData = listPages(connection, getTunnelStatus());
+					const listPagesAttached = connection.listTargets().length > 0;
+					return envelopeResult(listPagesData, name, resolveEnvironment(), listPagesAttached);
+				}
 				case "get_dom_document": return jsonResult$1(await getDomDocument(connection));
 				case "take_snapshot": return jsonResult$1(await takeSnapshot(connection));
 				case "take_screenshot": {
@@ -3783,7 +3869,11 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 						mimeType: shot.mimeType
 					}] };
 				}
-				case "measure_safe_area": return jsonResult$1(await measureSafeArea(connection, resolveEnvironment()));
+				case "measure_safe_area": {
+					const safeAreaData = await measureSafeArea(connection, resolveEnvironment());
+					const safeAreaAttached = connection.listTargets().length > 0;
+					return envelopeResult(safeAreaData, name, resolveEnvironment(), safeAreaAttached);
+				}
 				case "evaluate": {
 					const expression = request.params.arguments?.expression;
 					if (typeof expression !== "string" || expression === "") return mcpError("evaluate: expression 인자가 비어 있습니다. 평가할 JavaScript 표현식을 전달하세요.");
@@ -3798,7 +3888,8 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					if (isLiveRelayEnv(env) && request.params.arguments?.confirm !== true) return liveGuardError("call_sdk");
 					const sdkResult = await callSdk(connection, sdkName, sdkArgs);
 					if (!sdkResult.ok && typeof sdkResult.error === "string" && sdkResult.error.startsWith("sdk-absent:")) return sdkAbsentError("call_sdk");
-					return jsonResult$1(sdkResult);
+					const callSdkAttached = connection.listTargets().length > 0;
+					return envelopeResult(sdkResult, name, resolveEnvironment(), callSdkAttached);
 				}
 				default: return unknownTool(name);
 			}
@@ -3814,6 +3905,22 @@ function jsonResult$1(value) {
 		text: JSON.stringify(value, null, 2)
 	}] };
 }
+/**
+* Wraps `value` in a `ToolEnvelope` (when compat mode is off) and returns it
+* as a text content block. When `AIT_MCP_COMPAT=chrome-devtools` is set the
+* envelope is skipped and the raw value is returned — identical to `jsonResult`.
+*/
+function envelopeResult(value, tool, env, attached) {
+	const wrapped = wrapEnvelope(value, {
+		tool,
+		env,
+		attached
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(wrapped, null, 2)
+	}] };
+}
 function unknownTool(name) {
 	return mcpError(`알 수 없는 tool: ${name}`);
 }
@@ -3975,7 +4082,8 @@ async function runDebugServer(options = {}) {
 			return qrServer;
 		},
 		diagnosticsCollector,
-		defaultEnv: "relay-dev"
+		defaultEnv: "relay-dev",
+		...process.env.AIT_DEBUG_TOTP_SECRET ? { totpSecret: process.env.AIT_DEBUG_TOTP_SECRET } : {}
 	});
 	const transport = new StdioServerTransport();
 	let closed = false;
@@ -4515,7 +4623,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.45"
+		version: "0.1.46"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {