@ait-co/devtools 0.1.40 → 0.1.41

package/dist/mcp/cli.js

@@ -15,23 +15,23 @@ import { platform } from "node:os";
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { Tunnel, bin, install } from "cloudflared";
 //#region src/mcp/ait-chii-source.ts
-function isObject$3(value) {
+function isObject$4(value) {
 	return typeof value === "object" && value !== null;
 }
 /** Narrows an `AIT.getSdkCallHistory` response, tolerating a missing array. */
 function asSdkCallHistory(raw) {
-	if (isObject$3(raw) && Array.isArray(raw.calls)) return { calls: raw.calls };
+	if (isObject$4(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$3(raw) ? raw : {};
+	return isObject$4(raw) ? raw : {};
 }
 /** Narrows an `AIT.getOperationalEnvironment` response. */
 function asOperationalEnvironment(raw) {
 	return {
-		environment: isObject$3(raw) && typeof raw.environment === "string" ? raw.environment : "unknown",
-		sdkVersion: isObject$3(raw) && typeof raw.sdkVersion === "string" ? raw.sdkVersion : null
+		environment: isObject$4(raw) && typeof raw.environment === "string" ? raw.environment : "unknown",
+		sdkVersion: isObject$4(raw) && typeof raw.sdkVersion === "string" ? raw.sdkVersion : null
 	};
 }
 var ChiiAitSource = class {
@@ -65,7 +65,7 @@ var ChiiAitSource = class {
 */
 /** Max events retained per domain ring buffer. */
 const DEFAULT_BUFFER_SIZE$1 = 500;
-function isObject$2(value) {
+function isObject$3(value) {
 	return typeof value === "object" && value !== null;
 }
 function parseInbound$1(raw) {
@@ -75,13 +75,13 @@ function parseInbound$1(raw) {
 	} catch {
 		return null;
 	}
-	if (!isObject$2(parsed)) return null;
+	if (!isObject$3(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$2(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
+	if (isObject$3(parsed.error) && typeof parsed.error.message === "string") message.error = { message: parsed.error.message };
 	return message;
 }
 const PHASE_1_EVENTS$1 = [
@@ -90,25 +90,67 @@ const PHASE_1_EVENTS$1 = [
 	"Network.responseReceived"
 ];
 /**
+* Ring buffer size for `Runtime.exceptionThrown`.
+*
+* Exceptions are rarer than console messages but each is heavier (stack
+* trace). 50 is generous enough to cover a crash scenario while keeping
+* memory bounded.
+*
+* **Lifecycle note**: the exception buffer intentionally survives `replaced` /
+* `crashed` / `destroyed` lifecycle events — it is NOT cleared on target
+* transitions. Rationale: an exception fired just before a crash is exactly
+* the signal we want to preserve for root-cause analysis. The buffer
+* represents "exceptions seen in this MCP session", not "exceptions in the
+* current page".
+*/
+const EXCEPTION_BUFFER_SIZE = 50;
+/** Default per-command timeout if neither option nor env var is set. */
+const DEFAULT_COMMAND_TIMEOUT_MS = 3e4;
+/**
 * Production CDP connection. Polls the relay for the first attached target,
 * opens a client websocket to it, enables Phase 1 domains, and buffers events.
 */
 var ChiiCdpConnection = class {
 	relayBaseUrl;
 	bufferSize;
+	commandTimeoutMs;
 	emitter = new EventEmitter();
 	buffers = /* @__PURE__ */ new Map();
 	targets = /* @__PURE__ */ new Map();
 	ws = null;
+	connectionState = "idle";
 	nextCommandId = 1;
+	/**
+	* The single active target id under the single-attach model.
+	* Updated by `refreshTargets()` whenever a non-null target is present.
+	* Used to detect a new (different) target attach and evict the previous one.
+	*/
+	activeTargetId = null;
 	/** In-flight enableDomains() promise — concurrent callers share it. */
 	enablingPromise = null;
 	/** Pending request→response commands keyed by CDP message id. */
 	pending = /* @__PURE__ */ new Map();
+	/**
+	* Timestamp (ms since epoch) of the most recent crash/destroy/detach event,
+	* or `null` if no crash has been detected since the last `enableDomains()`.
+	*/
+	lastCrashDetectedAt = null;
+	/**
+	* Per-target last-seen timestamp (ms since epoch). Updated on any inbound
+	* CDP message carrying data from a target. Keyed by target id.
+	*/
+	targetLastSeenAt = /* @__PURE__ */ new Map();
+	/** Active heartbeat interval handle (only when `AIT_CDP_HEARTBEAT_MS` is set). */
+	heartbeatHandle = null;
+	/** Lifecycle event listeners (crash / destroyed / detached). */
+	lifecycleListeners = [];
 	constructor(options) {
 		this.relayBaseUrl = options.relayBaseUrl.replace(/\/$/, "");
 		this.bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE$1;
+		const envMs = process.env.AIT_CDP_COMMAND_TIMEOUT_MS ? Number(process.env.AIT_CDP_COMMAND_TIMEOUT_MS) : void 0;
+		this.commandTimeoutMs = (envMs !== void 0 && Number.isFinite(envMs) && envMs > 0 ? envMs : void 0) ?? options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
 		for (const event of PHASE_1_EVENTS$1) this.buffers.set(event, []);
+		this.buffers.set("Runtime.exceptionThrown", []);
 		this.emitter.setMaxListeners(0);
 	}
 	/** Refresh the attached-target list from the relay's `GET /targets`. */
@@ -116,22 +158,57 @@ 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$2(body) && Array.isArray(body.targets) ? body.targets : [];
+		const list = isObject$3(body) && Array.isArray(body.targets) ? body.targets : [];
+		let newestTargetId = null;
+		for (const item of list) {
+			if (!isObject$3(item) || typeof item.id !== "string") continue;
+			newestTargetId = item.id;
+		}
+		if (newestTargetId !== null && this.activeTargetId !== null && newestTargetId !== this.activeTargetId) {
+			const prevId = this.activeTargetId;
+			process.stderr.write(`[ait-debug] 이전 page 세션 종료 — 새 attach로 교체 (prev=${prevId})\n`);
+			this.evictTarget(prevId);
+		}
 		this.targets.clear();
 		for (const item of list) {
-			if (!isObject$2(item) || typeof item.id !== "string") continue;
+			if (!isObject$3(item) || typeof item.id !== "string") continue;
+			if (item.id !== newestTargetId) continue;
 			this.targets.set(item.id, {
 				id: item.id,
 				title: typeof item.title === "string" ? item.title : "",
 				url: typeof item.url === "string" ? item.url : ""
 			});
 		}
+		if (newestTargetId !== null) this.activeTargetId = newestTargetId;
+		else this.activeTargetId = null;
 		return [...this.targets.values()];
 	}
 	listTargets() {
 		return [...this.targets.values()];
 	}
 	/**
+	* Timestamp (ms since epoch) of the most recent crash/destroy/detach event
+	* detected since the last `enableDomains()` call, or `null` if none.
+	*/
+	getLastCrashDetectedAt() {
+		return this.lastCrashDetectedAt;
+	}
+	/**
+	* Last-seen timestamp (ms since epoch) for a given target id, or `null` if
+	* the target is unknown / no message has been received from it yet.
+	*/
+	getTargetLastSeenAt(targetId) {
+		return this.targetLastSeenAt.get(targetId) ?? null;
+	}
+	/** Subscribe to target lifecycle events (crash / destroyed / detached). */
+	onLifecycle(listener) {
+		this.lifecycleListeners.push(listener);
+		return () => {
+			const idx = this.lifecycleListeners.indexOf(listener);
+			if (idx !== -1) this.lifecycleListeners.splice(idx, 1);
+		};
+	}
+	/**
 	* Connect a client websocket to the first attached target and enable Phase 1
 	* domains. Resolves once the socket is open and enable commands are sent.
 	*/
@@ -152,11 +229,19 @@ var ChiiCdpConnection = class {
 			ws.once("open", () => resolve());
 			ws.once("error", (err) => reject(err));
 		});
+		this.lastCrashDetectedAt = null;
+		this.targetLastSeenAt.clear();
+		this.connectionState = "connected";
 		ws.on("message", (data) => this.handleMessage(data.toString()));
+		ws.on("close", () => this.handleDisconnect("relay WebSocket 연결이 끊겼습니다"));
+		ws.on("error", (err) => this.handleDisconnect(`relay WebSocket 오류: ${err.message}`));
 		this.sendFireAndForget("Runtime.enable");
 		this.sendFireAndForget("Network.enable");
 		this.sendFireAndForget("DOM.enable");
 		this.sendFireAndForget("Page.enable");
+		this.sendFireAndForget("Inspector.enable");
+		this.sendFireAndForget("Target.setDiscoverTargets", { discover: true });
+		this.startHeartbeat(target.id);
 	}
 	/** Fire-and-forget CDP message (used for `*.enable`, no result awaited). */
 	sendFireAndForget(method, params = {}) {
@@ -179,15 +264,35 @@ var ChiiCdpConnection = class {
 	* Issue an arbitrary request→response command over the relay and resolve with
 	* its raw result. Both the typed CDP {@link send} and the AIT domain (Phase 3
 	* `AIT.*` methods, forwarded over the same Chii channel) build on this.
+	*
+	* Rejects immediately if the connection is disconnected (fail-fast — no
+	* auto-reconnect). Caller should re-run `list_pages` or `enableDomains` to
+	* reattach.
+	*
+	* Times out after `commandTimeoutMs` (default 30s, env
+	* `AIT_CDP_COMMAND_TIMEOUT_MS`). On timeout the pending entry is cleaned up
+	* and the promise rejects with a descriptive Korean error.
 	*/
 	sendCommand(method, params = {}) {
+		if (this.connectionState === "disconnected") return Promise.reject(/* @__PURE__ */ new Error(`relay에 연결되어 있지 않습니다 (${method}). list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`));
 		if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return Promise.reject(/* @__PURE__ */ new Error("No mini-app page attached to the Chii relay yet. Call enableDomains() first."));
 		const id = this.nextCommandId++;
 		const ws = this.ws;
+		const timeoutMs = this.commandTimeoutMs;
 		return new Promise((resolve, reject) => {
+			const handle = setTimeout(() => {
+				this.pending.delete(id);
+				reject(/* @__PURE__ */ new Error(`CDP 명령이 타임아웃됐습니다 (${method}, ${timeoutMs}ms). 폰 측 토스 앱이 백그라운드로 내려갔거나 미니앱이 unload됐을 수 있습니다. list_pages로 attach 상태를 확인하세요.`));
+			}, timeoutMs);
 			this.pending.set(id, {
-				resolve,
-				reject
+				resolve: (v) => {
+					clearTimeout(handle);
+					resolve(v);
+				},
+				reject: (e) => {
+					clearTimeout(handle);
+					reject(e);
+				}
 			});
 			ws.send(JSON.stringify({
 				id,
@@ -196,6 +301,117 @@ var ChiiCdpConnection = class {
 			}));
 		});
 	}
+	/**
+	* Called on WebSocket `close` or `error` after a successful connection.
+	* Rejects all pending commands and marks the connection as disconnected so
+	* subsequent `sendCommand` calls fail fast (no auto-reconnect).
+	*/
+	handleDisconnect(reason) {
+		if (this.connectionState === "disconnected") return;
+		this.connectionState = "disconnected";
+		this.ws = null;
+		this.stopHeartbeat();
+		const err = /* @__PURE__ */ new Error(`${reason}. list_pages로 attach 상태를 확인하고 enableDomains()로 재연결하세요.`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+	}
+	/**
+	* Evict a previously active target under the single-attach model.
+	* Rejects pending commands with a 'replaced-by-new-attach' reason and emits
+	* a 'replaced' lifecycle event. Does NOT clear all targets — only the specific
+	* targetId. The caller is responsible for rebuilding the targets map afterwards.
+	*
+	* The error message uses 'replaced-by-new-attach' so test assertions can match it.
+	*/
+	evictTarget(targetId) {
+		const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.targets.delete(targetId);
+		this.targetLastSeenAt.delete(targetId);
+		const err = /* @__PURE__ */ new Error(`[ait-debug] replaced-by-new-attach — 이전 page 세션이 새 attach로 교체됐습니다 (targetId=${targetId}). list_pages로 현재 attach 상태를 확인하세요.`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+		const event = {
+			kind: "replaced",
+			targetId,
+			detectedAt
+		};
+		for (const listener of this.lifecycleListeners) try {
+			listener(event);
+		} catch {}
+	}
+	/**
+	* Handle a page-level crash or target destruction event.
+	* Removes the target from the in-memory map, rejects all pending commands,
+	* and emits a lifecycle event.
+	*
+	* @param kind - Event kind: 'crashed' | 'destroyed' | 'detached'
+	* @param targetId - The target ID from the event params (may be null for
+	*   Inspector.targetCrashed which has no targetId in the params).
+	*/
+	handleTargetGone(kind, targetId) {
+		const detectedAt = (/* @__PURE__ */ new Date()).toISOString();
+		this.lastCrashDetectedAt = Date.now();
+		if (targetId !== null) {
+			this.targets.delete(targetId);
+			this.targetLastSeenAt.delete(targetId);
+			if (this.activeTargetId === targetId) this.activeTargetId = null;
+		} else {
+			this.targets.clear();
+			this.targetLastSeenAt.clear();
+			this.activeTargetId = null;
+		}
+		const err = /* @__PURE__ */ new Error(`[ait-debug] ${kind === "crashed" ? "page crash (Inspector.targetCrashed)" : kind === "destroyed" ? "target 종료 (Target.targetDestroyed)" : "target detach (Target.detachedFromTarget)"} 감지됨 — relay에서 제거됐습니다. 새 attach가 필요합니다 (list_pages로 확인 → enableDomains()로 재연결).`);
+		for (const waiter of this.pending.values()) waiter.reject(err);
+		this.pending.clear();
+		const event = {
+			kind,
+			targetId,
+			detectedAt
+		};
+		for (const listener of this.lifecycleListeners) try {
+			listener(event);
+		} catch {}
+	}
+	/**
+	* Start the optional CDP heartbeat loop.
+	*
+	* When `AIT_CDP_HEARTBEAT_MS` is set to a positive integer, every interval
+	* we send `Runtime.evaluate({expression: '1'})` to each active target. If
+	* the command times out (2 s hard deadline) or errors, we treat the target
+	* as dead and call `handleTargetGone`.
+	*
+	* This is a zombie-detector fallback: cloudflared keeps-alive the tunnel ws
+	* even when the phone app has crashed, so the ws-level disconnect (#252) won't
+	* fire. The heartbeat catches this gap.
+	*
+	* Default: OFF. Only activates when `AIT_CDP_HEARTBEAT_MS` is set.
+	*/
+	startHeartbeat(initialTargetId) {
+		this.stopHeartbeat();
+		const envMs = process.env.AIT_CDP_HEARTBEAT_MS ? Number(process.env.AIT_CDP_HEARTBEAT_MS) : void 0;
+		if (envMs === void 0 || !Number.isFinite(envMs) || envMs <= 0) return;
+		const PING_TIMEOUT_MS = 2e3;
+		this.heartbeatHandle = setInterval(() => {
+			const targetIds = this.targets.size > 0 ? [...this.targets.keys()] : [initialTargetId];
+			for (const targetId of targetIds) {
+				const pingPromise = this.sendCommand("Runtime.evaluate", {
+					expression: "1",
+					returnByValue: true,
+					timeout: PING_TIMEOUT_MS
+				});
+				const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("heartbeat timeout")), PING_TIMEOUT_MS + 500));
+				Promise.race([pingPromise, timeoutPromise]).catch(() => {
+					if (this.targets.has(targetId)) this.handleTargetGone("destroyed", targetId);
+				});
+			}
+		}, envMs);
+	}
+	stopHeartbeat() {
+		if (this.heartbeatHandle !== null) {
+			clearInterval(this.heartbeatHandle);
+			this.heartbeatHandle = null;
+		}
+	}
 	handleMessage(raw) {
 		const message = parseInbound$1(raw);
 		if (!message) return;
@@ -206,13 +422,30 @@ var ChiiCdpConnection = class {
 			else waiter.resolve(message.result);
 			return;
 		}
+		const now = Date.now();
+		for (const targetId of this.targets.keys()) this.targetLastSeenAt.set(targetId, now);
 		if (typeof message.method !== "string") return;
+		if (message.method === "Inspector.targetCrashed") {
+			this.handleTargetGone("crashed", null);
+			return;
+		}
+		if (message.method === "Target.targetDestroyed") {
+			const targetId = isObject$3(message.params) && typeof message.params.targetId === "string" ? message.params.targetId : null;
+			this.handleTargetGone("destroyed", targetId);
+			return;
+		}
+		if (message.method === "Target.detachedFromTarget") {
+			const targetId = isObject$3(message.params) && typeof message.params.targetId === "string" ? message.params.targetId : null;
+			this.handleTargetGone("detached", targetId);
+			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();
+		const cap = event === "Runtime.exceptionThrown" ? EXCEPTION_BUFFER_SIZE : this.bufferSize;
+		if (buffer.length > cap) buffer.shift();
 		this.emitter.emit(event, message.params);
 	}
 	getBufferedEvents(event) {
@@ -224,10 +457,10 @@ var ChiiCdpConnection = class {
 	}
 	/** Close the relay client 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("Chii relay connection closed."));
-		this.pending.clear();
+		const ws = this.ws;
+		this.stopHeartbeat();
+		this.handleDisconnect("Chii relay connection closed");
+		ws?.close();
 	}
 };
 //#endregion
@@ -335,7 +568,7 @@ async function startChiiRelay(options = {}) {
 */
 /** Max events retained per domain ring buffer. */
 const DEFAULT_BUFFER_SIZE = 500;
-function isObject$1(value) {
+function isObject$2(value) {
 	return typeof value === "object" && value !== null;
 }
 function parseInbound(raw) {
@@ -345,13 +578,13 @@ function parseInbound(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 = [
@@ -404,7 +637,7 @@ var LocalCdpConnection = class {
 		this.targets.clear();
 		let selected = null;
 		for (const item of list) {
-			if (!isObject$1(item) || typeof item.id !== "string") continue;
+			if (!isObject$2(item) || typeof item.id !== "string") continue;
 			const cdpTarget = {
 				id: item.id,
 				title: typeof item.title === "string" ? item.title : "",
@@ -928,6 +1161,162 @@ function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
 	return `${base}?${query}${hash}`;
 }
 //#endregion
+//#region src/mcp/sdk-signatures.ts
+function isObject$1(v) {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function describeArgs(args) {
+	try {
+		return JSON.stringify(args);
+	} catch {
+		return String(args);
+	}
+}
+/**
+* 등록된 메서드 목록.
+*
+* 시그니처 출처 확인:
+*   - 함수가 인자를 받지 않으면 args[0] 없음 → `args.length === 0`을 체크하지 않고
+*     그냥 통과시킨다(args 무시하는 stub가 많아서 noArgs 체크가 noise).
+*   - 실 SDK 시그니처는 `src/__typecheck.ts`의 `Assert<Mock, Original>` 줄로 보장.
+*/
+const SIGNATURES = [
+	{
+		name: "setDeviceOrientation",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject$1(arg)) return {
+				ok: false,
+				expected: "{ type: 'portrait' | 'landscape' }",
+				received: describeArgs(args)
+			};
+			const type = arg.type;
+			if (type !== "portrait" && type !== "landscape") return {
+				ok: false,
+				expected: "{ type: 'portrait' | 'landscape' }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setDeviceOrientation', [{ type: 'landscape' }])"
+	},
+	{
+		name: "setIosSwipeGestureEnabled",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject$1(arg) || typeof arg.isEnabled !== "boolean") return {
+				ok: false,
+				expected: "{ isEnabled: boolean }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setIosSwipeGestureEnabled', [{ isEnabled: false }])"
+	},
+	{
+		name: "setSecureScreen",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject$1(arg) || typeof arg.enabled !== "boolean") return {
+				ok: false,
+				expected: "{ enabled: boolean }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setSecureScreen', [{ enabled: true }])"
+	},
+	{
+		name: "setScreenAwakeMode",
+		validateArgs(args) {
+			const arg = args[0];
+			if (!isObject$1(arg) || typeof arg.enabled !== "boolean") return {
+				ok: false,
+				expected: "{ enabled: boolean }",
+				received: describeArgs(args)
+			};
+			return { ok: true };
+		},
+		example: "call_sdk('setScreenAwakeMode', [{ enabled: true }])"
+	},
+	{
+		name: "getOperationalEnvironment",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getOperationalEnvironment', [])"
+	},
+	{
+		name: "getPlatformOS",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getPlatformOS', [])"
+	},
+	{
+		name: "getDeviceId",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getDeviceId', [])"
+	},
+	{
+		name: "getLocale",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getLocale', [])"
+	},
+	{
+		name: "getNetworkStatus",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getNetworkStatus', [])"
+	},
+	{
+		name: "getSchemeUri",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('getSchemeUri', [])"
+	},
+	{
+		name: "requestReview",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('requestReview', [])"
+	},
+	{
+		name: "closeView",
+		validateArgs(_args) {
+			return { ok: true };
+		},
+		example: "call_sdk('closeView', [])"
+	}
+];
+const SIGNATURE_MAP = new Map(SIGNATURES.map((s) => [s.name, s]));
+/** 세션 내 passthrough 경고를 한 번만 emit하기 위한 Set */
+const _warnedPassthrough = /* @__PURE__ */ new Set();
+/**
+* 메서드 이름으로 시그니처를 조회한다.
+* 등록된 메서드이면 `SdkSignature`를 반환하고, 미등록이면 `undefined`.
+*/
+function lookupSignature(name) {
+	return SIGNATURE_MAP.get(name);
+}
+/**
+* 미등록 메서드에 대해 stderr에 passthrough 경고를 1회 출력한다.
+* 세션 내 동일 메서드 이름은 최초 1회만 출력.
+*/
+function warnPassthrough(name) {
+	if (_warnedPassthrough.has(name)) return;
+	_warnedPassthrough.add(name);
+	process.stderr.write(`[ait-debug] call_sdk: "${name}" 시그니처가 등록되지 않음 — passthrough\n`);
+}
+SIGNATURES.map((s) => s.name);
+//#endregion
 //#region src/mcp/tools.ts
 /** Static MCP tool descriptors (name + JSONSchema) for the full debug tool surface. */
 const DEBUG_TOOL_DEFINITIONS = [
@@ -951,7 +1340,7 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "list_pages",
-		description: "Lists the mini-app page(s) the Chii relay currently sees attached, plus whether the cloudflared tunnel is up and the public wss relay URL the phone uses to 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. 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: {},
@@ -1028,9 +1417,21 @@ const DEBUG_TOOL_DEFINITIONS = [
 			required: ["expression"]
 		}
 	},
+	{
+		name: "list_exceptions",
+		description: "Lists JS-level exceptions captured via `Runtime.exceptionThrown` from the relay attached page. Includes timestamp, exception text, source URL/line, and stack trace. Use to root-cause SDK throws that may precede a Toss app crash (#265 / #267). The buffer holds up to 50 most recent exceptions and survives target replaced/crashed/destroyed events so an exception just before a crash is preserved. Returns up to 50 most recent by default.",
+		inputSchema: {
+			type: "object",
+			properties: { limit: {
+				type: "number",
+				description: "Maximum number of exceptions to return (default 50, max 50)."
+			} },
+			required: []
+		}
+	},
 	{
 		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).",
+		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. If a Runtime.exceptionThrown event was observed within [callStart-50ms, callEnd+200ms], the result also includes `recentException` for crash triage. Returns a clear error if window.__sdkCall is not available (non-dogfood bundle).\n\nIMPORTANT — 인자 시그니처 (잘못된 인자로 호출하면 토스 앱 crash 위험):\n  setDeviceOrientation:        call_sdk(\"setDeviceOrientation\", [{ type: \"landscape\" }])  // NOT \"landscape\"\n  setIosSwipeGestureEnabled:   call_sdk(\"setIosSwipeGestureEnabled\", [{ isEnabled: false }])\n  setSecureScreen:             call_sdk(\"setSecureScreen\", [{ enabled: true }])\n  setScreenAwakeMode:          call_sdk(\"setScreenAwakeMode\", [{ enabled: true }])\n  getOperationalEnvironment:   call_sdk(\"getOperationalEnvironment\", [])\n  getPlatformOS:               call_sdk(\"getPlatformOS\", [])\n  getDeviceId:                 call_sdk(\"getDeviceId\", [])\n  getLocale:                   call_sdk(\"getLocale\", [])\n  getNetworkStatus:            call_sdk(\"getNetworkStatus\", [])\n  getSchemeUri:                call_sdk(\"getSchemeUri\", [])\n  requestReview:               call_sdk(\"requestReview\", [])\n  closeView:                   call_sdk(\"closeView\", [])",
 		inputSchema: {
 			type: "object",
 			properties: {
@@ -1133,10 +1534,58 @@ function listNetworkRequests(connection) {
 		};
 	});
 }
+/** Formats a single CDP call frame into `at fn (url:line:col)`. */
+function formatCallFrame(frame) {
+	return `at ${frame.functionName || "(anonymous)"} (${frame.url}:${frame.lineNumber}:${frame.columnNumber})`;
+}
+/** Normalizes a raw `Runtime.exceptionThrown` event into a `BufferedException`. */
+function normalizeException(event) {
+	const { timestamp, exceptionDetails } = event;
+	const frames = exceptionDetails.stackTrace?.callFrames;
+	const stack = frames && frames.length > 0 ? frames.map(formatCallFrame).join("\n") : void 0;
+	const exceptionText = exceptionDetails.exception?.description ?? void 0;
+	const result = {
+		timestamp,
+		text: exceptionDetails.text,
+		raw: event
+	};
+	if (exceptionDetails.url !== void 0) result.url = exceptionDetails.url;
+	if (exceptionDetails.lineNumber !== void 0) result.lineNumber = exceptionDetails.lineNumber;
+	if (exceptionDetails.columnNumber !== void 0) result.columnNumber = exceptionDetails.columnNumber;
+	if (exceptionText !== void 0) result.exceptionText = exceptionText;
+	if (stack !== void 0) result.stack = stack;
+	return result;
+}
+/**
+* Returns the most recent buffered `Runtime.exceptionThrown` events, normalized.
+* Oldest-first; limited to `limit` entries (default 50, max 50).
+*/
+function listExceptions(connection, limit = 50) {
+	const cap = Math.min(Math.max(1, limit), 50);
+	const events = connection.getBufferedEvents("Runtime.exceptionThrown");
+	return (events.length > cap ? events.slice(events.length - cap) : events).map((e) => normalizeException(e));
+}
+function isCrashAware(conn) {
+	return typeof conn.getLastCrashDetectedAt === "function" && typeof conn.getTargetLastSeenAt === "function";
+}
 function listPages(connection, tunnel) {
+	const pages = connection.listTargets().map((t) => {
+		const lastSeenMs = isCrashAware(connection) ? connection.getTargetLastSeenAt(t.id) : null;
+		return {
+			id: t.id,
+			title: t.title,
+			url: t.url,
+			lastSeenAt: lastSeenMs !== null ? new Date(lastSeenMs).toISOString() : null
+		};
+	});
+	const crashMs = isCrashAware(connection) ? connection.getLastCrashDetectedAt() : null;
+	const crashDetectedAt = crashMs !== null ? new Date(crashMs).toISOString() : null;
 	return {
-		pages: connection.listTargets(),
-		tunnel
+		pages,
+		tunnel,
+		crashDetectedAt,
+		crashWarning: crashDetectedAt ? `[ait-debug] page crash 감지됨 — 새 attach 필요 (관측 시각: ${crashDetectedAt})` : null,
+		singleAttachModel: true
 	};
 }
 /**
@@ -1542,29 +1991,73 @@ function normalizeCallSdkResult(rawValue) {
 	throw new Error("call_sdk: bridge result missing \"ok\" field");
 }
 /**
+* Looks up the most recent exception from the buffer that falls within the
+* triage window [windowStart, windowEnd]. Returns `undefined` if none found.
+*
+* The heuristic window is:
+*   - windowStart = callStart - 50ms  (catch sync throws before bridge fires)
+*   - windowEnd   = callEnd + 200ms   (catch async throws resolved soon after)
+*
+* Only the most recent exception within the window is returned (the one most
+* likely to be causally related to the SDK call).
+*/
+function findRecentException(connection, windowStart, windowEnd) {
+	const events = connection.getBufferedEvents("Runtime.exceptionThrown");
+	for (let i = events.length - 1; i >= 0; i--) {
+		const e = events[i];
+		if (e.timestamp >= windowStart && e.timestamp <= windowEnd) return normalizeException(e);
+	}
+}
+/**
 * 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.
 *
+* 인자 시그니처 검증: 등록된 메서드는 bridge 호출 전에 인자를 검증하고, mismatch면
+* `{ok:false, error}` MCP 오류 결과를 반환한다(bridge에 도달하지 않음).
+* 미등록 메서드는 passthrough + stderr 경고 1회.
+*
 * Throws on CDP error or result parse failure. Returns `{ok:false, error}`
-* for bridge-level errors (method not found, SDK threw, bridge absent).
+* for bridge-level errors (method not found, SDK threw, bridge absent) or
+* argument schema violations.
+*
+* If a `Runtime.exceptionThrown` event was observed within the triage window
+* [callStart-50ms, callEnd+200ms], the result includes `recentException` for
+* crash triage. This window is a heuristic — it catches the common case of an
+* SDK throw immediately before/after the bridge resolves.
 *
 * SECRET-HANDLING: name, args, and the result value are NOT written to any log.
 */
 async function callSdk(connection, name, args) {
+	const signature = lookupSignature(name);
+	if (signature !== void 0) {
+		const validation = signature.validateArgs(args);
+		if (!validation.ok) return {
+			ok: false,
+			error: `call_sdk("${name}") 인자 시그니처 오류.\n받음: ${validation.received}\n기대: ${validation.expected}\n올바른 예시: ${signature.example}`
+		};
+	} else warnPassthrough(name);
+	const callStart = Date.now();
 	const expression = buildCallSdkExpression(name, args);
 	const result = await connection.send("Runtime.evaluate", {
 		expression,
 		returnByValue: true,
 		awaitPromise: true
 	});
+	const callEnd = Date.now();
 	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);
+	const sdkResult = normalizeCallSdkResult(result.result.value);
+	const recentException = findRecentException(connection, callStart - 50, callEnd + 200);
+	if (recentException !== void 0) return {
+		...sdkResult,
+		recentException
+	};
+	return sdkResult;
 }
 /** Set of tool names served by the AIT source rather than the CDP connection. */
 const AIT_TOOL_NAMES = new Set([
@@ -1861,7 +2354,7 @@ function createDebugServer(deps) {
 	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4, qrHttpServer } = deps;
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.40"
+		version: "0.1.41"
 	}, { 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 })) };
@@ -2014,6 +2507,10 @@ function createDebugServer(deps) {
 		try {
 			switch (name) {
 				case "list_console_messages": return jsonResult$1(listConsoleMessages(connection));
+				case "list_exceptions": {
+					const rawLimit = request.params.arguments?.limit;
+					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": return jsonResult$1(listPages(connection, getTunnelStatus()));
 				case "get_dom_document": return jsonResult$1(await getDomDocument(connection));
@@ -2174,12 +2671,12 @@ async function runDebugServer(options = {}) {
 	const connection = new ChiiCdpConnection({ relayBaseUrl: relay.baseUrl });
 	const aitSource = new ChiiAitSource(connection);
 	let qrServer;
-	startQrHttpServer().then((s) => {
-		qrServer = s;
-	}, (err) => {
+	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`);
-	});
+	}
 	const server = createDebugServer({
 		connection,
 		aitSource,
@@ -2412,7 +2909,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.40"
+		version: "0.1.41"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {