@kln-mcp/ctrl-mobile-cn 0.0.6

package/wrapper/index.js

@@ -0,0 +1,2553 @@
+'use strict';
+
+const { AsyncLocalStorage } = require('node:async_hooks');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const http = require('node:http');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+const { URL } = require('node:url');
+const { KlnCoreClient } = require('../core');
+const { loadConfig } = require('../config');
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RECONNECT_WINDOW_MS = 10_000;
+const DEFAULT_OUTPUT_DIR = path.join(process.cwd(), 'outputs');
+const DEFAULT_VIEW_HOST = '127.0.0.1';
+const DEFAULT_VIEW_PORT = 8090;
+const LIVE_VIEW_HTML_PATH = path.join(__dirname, 'live-view.html');
+const DEFAULT_DEVICE_CACHE_PATH = path.join(os.homedir(), '.kln-mobile-ctrl', 'selected-device.json');
+const DEFAULT_TASK_MEMORY_PATH = path.join(os.homedir(), '.kln', 'task_memory.json');
+const DEFAULT_CONTEXT_ELEMENT_LIMIT = 10;
+const MAX_CONTEXT_TEXT_LENGTH = 60;
+const DEFAULT_SUBSCRIPTION_CHECK_MS = 10 * 60 * 1000;
+const SUBSCRIPTION_CHECK_JITTER_MS = 60 * 1000;
+const traceStorage = new AsyncLocalStorage();
+
+const TOOL_DEFINITIONS = [
+  {
+    name: 'kln_set_api_key',
+    description: 'Set the server API key for this MCP session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        apiKey: { type: 'string', description: 'User API key from KLN server.' }
+      },
+      required: ['apiKey']
+    }
+  },
+  {
+    name: 'kln_list_devices',
+    description: 'List online Android devices from KLN server. Each device includes its current P2P endpoint ticket.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        apiKey: { type: 'string', description: 'Optional API key. Falls back to --api-key or KLN_API_KEY.' }
+      }
+    }
+  },
+  {
+    name: 'kln_select_device',
+    description: 'Select an online Android device by device ID, cache the selected device ID, and connect to it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        deviceId: { type: 'string', description: 'Device ID returned by kln_list_devices.' },
+        apiKey: { type: 'string', description: 'Optional API key. Falls back to --api-key or KLN_API_KEY.' }
+      },
+      required: ['deviceId']
+    }
+  },
+  {
+    name: 'kln_send_command',
+    description: 'Send a command to the connected Android device and wait for a response.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Command name, for example ping or get-view-tree.' },
+        text: { type: 'string', description: 'Optional command payload text.' },
+        ticket: { type: 'string', description: 'Optional endpoint ticket. Falls back to server config.' },
+        apiKey: { type: 'string', description: 'Optional server API key.' },
+        deviceId: { type: 'string', description: 'Optional server device ID.' },
+        timeoutMs: { type: 'number', description: 'Response timeout in milliseconds.' }
+      },
+      required: ['name']
+    }
+  },
+  {
+    name: 'kln_send_text',
+    description: 'Send a text message to the connected Android device and wait for a response.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Text message body.' },
+        ticket: { type: 'string', description: 'Optional endpoint ticket. Falls back to server config.' },
+        apiKey: { type: 'string', description: 'Optional server API key.' },
+        deviceId: { type: 'string', description: 'Optional server device ID.' },
+        timeoutMs: { type: 'number', description: 'Response timeout in milliseconds.' }
+      },
+      required: ['text']
+    }
+  },
+  {
+    name: 'kln_start_screen_stream',
+    description: 'Request an H264 screen stream and save it to a local file.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Optional stream request payload text.' },
+        ticket: { type: 'string', description: 'Optional endpoint ticket. Falls back to server config.' },
+        apiKey: { type: 'string', description: 'Optional server API key.' },
+        deviceId: { type: 'string', description: 'Optional server device ID.' },
+        outputDir: { type: 'string', description: 'Directory for the raw H264 output file.' }
+      }
+    }
+  },
+  {
+    name: 'kln_get_device_context',
+    description: 'Get compact Android screen context for agent decisions. Returns screen bounds plus a trimmed clickable element list.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string', description: 'Optional endpoint ticket. Falls back to server config.' },
+        apiKey: { type: 'string', description: 'Optional server API key.' },
+        deviceId: { type: 'string', description: 'Optional server device ID.' },
+        timeoutMs: { type: 'number', description: 'Response timeout in milliseconds.' },
+        maxElements: { type: 'number', description: 'Maximum clickable text elements to return. Default: 10.' }
+      }
+    }
+  },
+  {
+    name: 'kln_task_memory',
+    description: 'Persist or read task-level progress in ~/.kln/task_memory.json for resuming long mobile tasks.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        op: { type: 'string', description: 'Operation: list, get, put, or delete.' },
+        key: { type: 'string', description: 'Task key. Required for get, put, and delete.' },
+        value: { type: 'string', description: 'Opaque JSON string. Required for put.' },
+        summary: { type: 'string', description: 'Human-readable task title. Required for put.' },
+        progress: { type: 'string', description: 'Human-readable task progress. Required for put.' }
+      },
+      required: ['op']
+    }
+  },
+  {
+    name: 'kln_input_tap',
+    description: 'Tap a device coordinate.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        x: { type: 'number' },
+        y: { type: 'number' },
+        profile: { type: 'string', description: 'Gesture simulation profile. Default: human.' },
+        ticket: { type: 'string' },
+        timeoutMs: { type: 'number' }
+      },
+      required: ['x', 'y']
+    }
+  },
+  {
+    name: 'kln_input_swipe',
+    description: 'Swipe or drag between two device coordinates.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        startX: { type: 'number' },
+        startY: { type: 'number' },
+        endX: { type: 'number' },
+        endY: { type: 'number' },
+        durationMs: { type: 'number' },
+        profile: { type: 'string', description: 'Gesture simulation profile. Default: human.' },
+        ticket: { type: 'string' },
+        timeoutMs: { type: 'number' }
+      },
+      required: ['startX', 'startY', 'endX', 'endY']
+    }
+  },
+  {
+    name: 'kln_input_text',
+    description: 'Set or append text in the focused editable field.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string' },
+        replace: { type: 'boolean', description: 'Replace focused field text. Default: false.' },
+        ticket: { type: 'string' },
+        timeoutMs: { type: 'number' }
+      },
+      required: ['text']
+    }
+  },
+  {
+    name: 'kln_input_clear',
+    description: 'Clear the focused editable field.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticket: { type: 'string' },
+        timeoutMs: { type: 'number' }
+      }
+    }
+  },
+  {
+    name: 'kln_input_key',
+    description: 'Send a supported key action.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        key: { type: 'string', description: 'Supported values include back, home, recents, enter, delete.' },
+        ticket: { type: 'string' },
+        timeoutMs: { type: 'number' }
+      },
+      required: ['key']
+    }
+  },
+  {
+    name: 'kln_device_global_action',
+    description: 'Perform an Android accessibility global action.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', description: 'back, home, recents, notifications, quickSettings, powerDialog, lockScreen.' },
+        ticket: { type: 'string' },
+        timeoutMs: { type: 'number' }
+      },
+      required: ['action']
+    }
+  },
+  {
+    name: 'kln_app_start',
+    description: 'Start a launchable app by package name.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        packageName: { type: 'string' },
+        activity: { type: 'string' },
+        ticket: { type: 'string' },
+        timeoutMs: { type: 'number' }
+      },
+      required: ['packageName']
+    }
+  },
+  {
+    name: 'kln_app_stop',
+    description: 'Best-effort stop for an app by package name.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        packageName: { type: 'string' },
+        ticket: { type: 'string' },
+        timeoutMs: { type: 'number' }
+      },
+      required: ['packageName']
+    }
+  },
+  {
+    name: 'kln_apps_list_launchable',
+    description: 'Return launchable apps from the Android device via postcard.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        includeSystem: { type: 'boolean', description: 'Include system apps. Default: true.' },
+        ticket: { type: 'string' },
+        timeoutMs: { type: 'number' }
+      }
+    }
+  }
+];
+
+for (const tool of TOOL_DEFINITIONS) {
+  const properties = tool.inputSchema && tool.inputSchema.properties;
+  if (properties) {
+    properties.trace_id = properties.trace_id || { type: 'string', description: 'OpenObserve/OTel trace_id. Generated automatically when omitted.' };
+  }
+  if (properties && properties.ticket) {
+    properties.apiKey = properties.apiKey || { type: 'string', description: 'Optional server API key.' };
+    properties.deviceId = properties.deviceId || { type: 'string', description: 'Optional server device ID.' };
+  }
+}
+
+class KlnMobileController {
+  constructor(options = {}) {
+    const config = loadConfig(options.env);
+    this.env = config.env;
+    this.debug = config.env === 'dev';
+    if (this.debug) {
+      process.env.KLN_MCP_DEBUG = '1';
+    }
+    this.apiUrl = cleanString(options.apiUrl || options.api_url || config.api_url || process.env.KLN_API_URL);
+    this.apiKey = cleanString(options.apiKey || options.api_key || process.env.KLN_API_KEY);
+    this.deviceId = cleanString(options.deviceId || options.device_id || process.env.KLN_DEVICE_ID);
+    this.deviceCachePath = cleanString(options.deviceCachePath || options.device_cache_path || process.env.KLN_DEVICE_CACHE_PATH) || DEFAULT_DEVICE_CACHE_PATH;
+    this.reconnectWindowMs = normalizeTimeout(options.reconnectWindowMs || options.reconnect_window_ms, DEFAULT_RECONNECT_WINDOW_MS);
+    this.staticTicket = cleanString(options.ticket || process.env.KLN_TICKET);
+    this.ticket = this.staticTicket;
+    this.relayUrls = normalizeRelayUrls(options.relayUrls || options.relay_urls || config.relay_urls);
+    this.alpn = cleanString(options.alpn || process.env.KLN_ALPN);
+    this.traceId = cleanString(options.traceId || options.trace_id || process.env.KLN_TRACE_ID);
+    this.timeoutMs = normalizeTimeout(options.timeoutMs || options.timeout_ms, DEFAULT_TIMEOUT_MS);
+    this.outputDir = options.outputDir || options.output_dir || process.env.KLN_OUTPUT_DIR || DEFAULT_OUTPUT_DIR;
+    this.taskMemoryPath = cleanString(options.taskMemoryPath || options.task_memory_path || process.env.KLN_TASK_MEMORY_PATH) || DEFAULT_TASK_MEMORY_PATH;
+    this.client = null;
+    this.clientTicket = null;
+    this.clientKey = null;
+    this.connectPromise = null;
+    this.connectKey = null;
+    this.subscriptionStatus = null;
+    this.subscriptionTimer = null;
+    this.subscriptionCheckPromise = null;
+    this.log('controller initialized', {
+      env: this.env,
+      ticket: summarizeTicket(this.staticTicket),
+      apiUrl: this.apiUrl,
+      hasApiKey: Boolean(this.apiKey),
+      deviceId: this.deviceId || '<cache-or-auto>',
+      relayUrls: this.relayUrls,
+      alpn: this.alpn || '<default>',
+      trace_id: this.traceId || '<auto>',
+      timeoutMs: this.timeoutMs,
+      reconnectWindowMs: this.reconnectWindowMs,
+      outputDir: this.outputDir,
+      taskMemoryPath: this.taskMemoryPath
+    });
+  }
+
+  async connect(options = {}) {
+    const target = await this.resolveConnectionTarget(options);
+    const ticket = requireTicket(target.ticket);
+    const relayUrls = normalizeRelayUrls(options.relayUrls || options.relay_urls || this.relayUrls);
+    const alpn = cleanString(options.alpn || this.alpn);
+    const apiKey = cleanString(options.apiKey || this.apiKey);
+    const connectKey = JSON.stringify({ ticket, relayUrls, alpn: alpn || '', apiKey: apiKey || '' });
+
+    if (this.client && this.clientKey === connectKey) {
+      this.log('reuse existing P2P connection', {
+        ticket: summarizeTicket(ticket)
+      });
+      return this.client;
+    }
+
+    if (this.connectPromise && this.connectKey === connectKey) {
+      this.log('wait for in-flight P2P connection', {
+        ticket: summarizeTicket(ticket)
+      });
+      return this.connectPromise;
+    }
+
+    this.log('start P2P connection', {
+      ticket: summarizeTicket(ticket),
+      relayUrls,
+      alpn: alpn || '<default>'
+    });
+    await this.close();
+    this.connectKey = connectKey;
+    this.connectPromise = KlnCoreClient.connect({
+        ticket,
+        relayUrls,
+        ...(alpn ? { alpn } : {}),
+        ...(apiKey ? { apiKey } : {})
+      })
+      .then((client) => {
+        this.client = client;
+        this.clientTicket = ticket;
+        this.clientKey = connectKey;
+        this.log('P2P connection established', {
+          nodeId: client.nodeId,
+          ticket: summarizeTicket(ticket)
+        });
+        this.scheduleSubscriptionCheck();
+        return client;
+      })
+      .catch((error) => {
+        this.log('P2P connection failed', {
+          message: error.message || String(error)
+        });
+        throw error;
+      })
+      .finally(() => {
+        if (this.connectKey === connectKey) {
+          this.connectPromise = null;
+          this.connectKey = null;
+        }
+      });
+
+    return this.connectPromise;
+  }
+
+  async setApiKey(apiKey, options = {}) {
+    const normalized = cleanString(apiKey);
+    if (!normalized) {
+      throw new Error('apiKey is required');
+    }
+    this.apiKey = normalized;
+    if (options.validate !== false) {
+      await this.listServerDevices({ apiKey: normalized });
+    }
+    return {
+      ok: true,
+      summary: 'API key configured for this MCP session.'
+    };
+  }
+
+  async listServerDevices(options = {}) {
+    const apiKey = this.resolveApiKey(options);
+    const data = await this.serverRequest('/api/v1/user-device/mcp/devices', { apiKey });
+    const devices = normalizeDeviceList(data);
+    const deviceWithSubscription = devices.find((device) => device.subscription);
+    if (deviceWithSubscription) {
+      this.recordSubscriptionStatus(deviceWithSubscription.subscription);
+    }
+    return devices;
+  }
+
+  async selectDevice(deviceId, options = {}) {
+    const normalizedDeviceId = cleanString(deviceId);
+    if (!normalizedDeviceId) {
+      throw new Error('deviceId is required');
+    }
+    if (cleanString(options.apiKey || options.api_key)) {
+      this.apiKey = cleanString(options.apiKey || options.api_key);
+    }
+    const device = await this.fetchServerDeviceTicket(normalizedDeviceId, options);
+    this.deviceId = device.deviceId;
+    this.ticket = device.ticket;
+    this.writeCachedDeviceId(device.deviceId);
+    await this.close();
+    await this.connect({ ...options, deviceId: device.deviceId });
+    return {
+      ok: true,
+      device,
+      summary: `Selected device ${device.deviceId}.`
+    };
+  }
+
+  async resolveConnectionTarget(options = {}) {
+    const ticket = cleanString(options.ticket || this.staticTicket);
+    if (ticket) {
+      return { ticket, managed: false };
+    }
+
+    const device = await this.ensureServerDevice(options);
+    return {
+      ticket: device.ticket,
+      deviceId: device.deviceId,
+      managed: true
+    };
+  }
+
+  async ensureServerDevice(options = {}) {
+    const requestedDeviceId = cleanString(options.deviceId || options.device_id || this.deviceId || this.readCachedDeviceId());
+    if (requestedDeviceId) {
+      const device = await this.fetchServerDeviceTicket(requestedDeviceId, options);
+      this.deviceId = device.deviceId;
+      this.ticket = device.ticket;
+      return device;
+    }
+
+    const devices = await this.listServerDevices(options);
+    if (devices.length === 0) {
+      throw new Error('没有在线安卓设备，请确认安卓端已登录并上报 heartbeat。');
+    }
+    if (devices.length > 1) {
+      const ids = devices.map((device) => device.deviceId).join(', ');
+      throw new Error(`发现多个在线设备，请先调用 kln_select_device 选择一个设备: ${ids}`);
+    }
+
+    const [device] = devices;
+    this.deviceId = device.deviceId;
+    this.ticket = device.ticket;
+    this.writeCachedDeviceId(device.deviceId);
+    return device;
+  }
+
+  async fetchServerDeviceTicket(deviceId, options = {}) {
+    const apiKey = this.resolveApiKey(options);
+    const encodedDeviceId = encodeURIComponent(deviceId);
+    const data = await this.serverRequest(`/api/v1/user-device/mcp/devices/${encodedDeviceId}/ticket`, { apiKey });
+    const device = normalizeDevice(data);
+    if (!device || !device.ticket) {
+      throw new Error('server did not return a device ticket');
+    }
+    this.recordSubscriptionStatus(device.subscription);
+    return device;
+  }
+
+  async checkSubscriptionStatus(options = {}) {
+    if (!this.apiUrl || !cleanString(options.apiKey || options.api_key || this.apiKey)) {
+      return this.subscriptionStatus;
+    }
+    if (this.subscriptionCheckPromise) {
+      return this.subscriptionCheckPromise;
+    }
+    this.subscriptionCheckPromise = this.serverRequest('/api/v1/user-device/mcp/subscription/status', options)
+      .then((status) => {
+        this.recordSubscriptionStatus(status);
+        return this.subscriptionStatus;
+      })
+      .finally(() => {
+        this.subscriptionCheckPromise = null;
+      });
+    return this.subscriptionCheckPromise;
+  }
+
+  async ensureSubscriptionActive(options = {}) {
+    const status = this.subscriptionStatus;
+    if (status && status.active === false) {
+      await this.close();
+      throw new Error(status.message || '订阅已到期');
+    }
+    if (status && status.graceUntilMs && Date.now() >= status.graceUntilMs) {
+      this.recordSubscriptionStatus({ ...status, active: false, message: '订阅已到期' });
+      await this.close();
+      throw new Error('订阅已到期');
+    }
+    if (status && status.nextCheckAtMs && Date.now() < status.nextCheckAtMs) {
+      return status;
+    }
+    return this.checkSubscriptionStatus(options);
+  }
+
+  recordSubscriptionStatus(status) {
+    const normalized = normalizeSubscriptionStatus(status);
+    if (!normalized) {
+      return;
+    }
+    this.subscriptionStatus = normalized;
+    this.log('subscription status updated', {
+      active: normalized.active,
+      vipLevel: normalized.vipLevel,
+      expiresAt: normalized.expiresAt || '<unknown>',
+      graceUntil: normalized.graceUntil || '<unknown>',
+      nextCheckAt: normalized.nextCheckAt || '<default>'
+    });
+    this.scheduleSubscriptionCheck(normalized);
+  }
+
+  scheduleSubscriptionCheck(status = this.subscriptionStatus) {
+    if (this.subscriptionTimer) {
+      clearTimeout(this.subscriptionTimer);
+      this.subscriptionTimer = null;
+    }
+    if (!status || status.active === false || !this.apiUrl || !this.apiKey) {
+      return;
+    }
+    const nextCheckAtMs = status.nextCheckAtMs || Date.now() + DEFAULT_SUBSCRIPTION_CHECK_MS;
+    const jitterMs = Math.floor(Math.random() * SUBSCRIPTION_CHECK_JITTER_MS);
+    const delayMs = Math.max(60_000, nextCheckAtMs - Date.now() + jitterMs);
+    this.subscriptionTimer = setTimeout(() => {
+      this.checkSubscriptionStatus().catch(async (error) => {
+        if (isSubscriptionExpiredError(error)) {
+          this.recordSubscriptionStatus({ active: false, message: '订阅已到期' });
+          await this.close();
+          return;
+        }
+        this.log('subscription status check failed', {
+          message: error.message || String(error)
+        });
+        this.scheduleSubscriptionCheck({
+          ...this.subscriptionStatus,
+          active: true,
+          nextCheckAtMs: Date.now() + DEFAULT_SUBSCRIPTION_CHECK_MS
+        });
+      });
+    }, delayMs);
+    if (typeof this.subscriptionTimer.unref === 'function') {
+      this.subscriptionTimer.unref();
+    }
+  }
+
+  async refreshManagedTicket(options = {}) {
+    const deviceId = cleanString(options.deviceId || options.device_id || this.deviceId || this.readCachedDeviceId());
+    if (!deviceId) {
+      throw new Error('deviceId is required to refresh ticket from server');
+    }
+    const device = await this.fetchServerDeviceTicket(deviceId, options);
+    this.deviceId = device.deviceId;
+    this.ticket = device.ticket;
+    this.writeCachedDeviceId(device.deviceId);
+    await this.close();
+    return device;
+  }
+
+  async withConnectionRetry(operation, options = {}) {
+    try {
+      await this.ensureSubscriptionActive(options);
+      const client = await this.connect(options);
+      return await operation(client);
+    } catch (error) {
+      if (isSubscriptionExpiredError(error)) {
+        await this.close();
+        throw new Error('订阅已到期');
+      }
+      if (!this.shouldRetryWithServerTicket(options, error)) {
+        throw error;
+      }
+      return this.retryManagedConnection(operation, options, error);
+    }
+  }
+
+  async retryManagedConnection(operation, options, firstError) {
+    const deadline = Date.now() + this.reconnectWindowMs;
+    let lastError = firstError;
+    this.log('P2P operation failed; retry current ticket before server refresh', {
+      message: firstError.message || String(firstError),
+      retryWindowMs: this.reconnectWindowMs
+    });
+
+    while (Date.now() < deadline) {
+      await this.close();
+      try {
+        const client = await this.connect(options);
+        return await operation(client);
+      } catch (error) {
+        lastError = error;
+        await delay(Math.min(1000, Math.max(100, deadline - Date.now())));
+      }
+    }
+
+    this.log('current ticket retry exhausted; refresh ticket from server', {
+      message: lastError.message || String(lastError),
+      deviceId: this.deviceId || '<cache>'
+    });
+    await this.refreshManagedTicket(options);
+    const client = await this.connect(options);
+    return operation(client);
+  }
+
+  shouldRetryWithServerTicket(options, error) {
+    if (cleanString(options.ticket)) {
+      return false;
+    }
+    if (this.staticTicket && !this.deviceId && !this.readCachedDeviceId()) {
+      return false;
+    }
+    return isLikelyConnectionError(error);
+  }
+
+  async sendCommand(name, text, options = {}) {
+    if (!cleanString(name)) {
+      throw new Error('command name is required');
+    }
+    const traceOptions = this.prepareTraceOptions(options);
+    return runWithTrace(traceOptions.traceId, async () => {
+      this.log('command dispatch', {
+        trace_id: traceOptions.traceId,
+        name
+      });
+    return normalizeMessage(await this.withConnectionRetry(async (client) => (
+      client.sendCommand(String(name), optionalText(text), {
+        timeoutMs: normalizeTimeout(traceOptions.timeoutMs || traceOptions.timeout_ms, this.timeoutMs),
+        traceId: traceOptions.traceId
+      })
+    ), traceOptions));
+    });
+  }
+
+  async sendText(text, options = {}) {
+    if (typeof text !== 'string' || text.length === 0) {
+      throw new Error('text is required');
+    }
+    const traceOptions = this.prepareTraceOptions(options);
+    return runWithTrace(traceOptions.traceId, async () => {
+      this.log('text dispatch', {
+        trace_id: traceOptions.traceId
+      });
+    return normalizeMessage(await this.withConnectionRetry(async (client) => (
+      client.sendText(text, {
+        timeoutMs: normalizeTimeout(traceOptions.timeoutMs || traceOptions.timeout_ms, this.timeoutMs),
+        traceId: traceOptions.traceId
+      })
+    ), traceOptions));
+    });
+  }
+
+  async sendOnlyCommand(name, text, options = {}) {
+    if (!cleanString(name)) {
+      throw new Error('command name is required');
+    }
+    const traceOptions = this.prepareTraceOptions(options);
+    return runWithTrace(traceOptions.traceId, async () => {
+      this.log('send-only command dispatch', {
+        trace_id: traceOptions.traceId,
+        name
+      });
+    return this.withConnectionRetry(
+      (client) => client.sendOnlyCommand(String(name), optionalText(text), {
+        traceId: traceOptions.traceId
+      }),
+      traceOptions
+    );
+    });
+  }
+
+  async sendJsonRpc(method, params = {}, options = {}) {
+    if (!cleanString(method)) {
+      throw new Error('json-rpc method is required');
+    }
+    const traceOptions = this.prepareTraceOptions(options);
+    return runWithTrace(traceOptions.traceId, async () => {
+      this.log('json-rpc dispatch', {
+        trace_id: traceOptions.traceId,
+        method
+      });
+    const result = await this.withConnectionRetry((client) => client.sendJsonRpc(String(method), params || {}, {
+      timeoutMs: normalizeTimeout(traceOptions.timeoutMs || traceOptions.timeout_ms, this.timeoutMs),
+      traceId: traceOptions.traceId
+    }), traceOptions);
+    if (result && result.ok === false) {
+      const message = result.error && (result.error.message || result.error.code)
+        ? `${result.error.code || 'json-rpc error'}: ${result.error.message || ''}`.trim()
+        : 'json-rpc request failed';
+      throw new Error(message);
+    }
+    return result;
+    });
+  }
+
+  async getDeviceContext(options = {}) {
+    const traceOptions = this.prepareTraceOptions(options);
+    try {
+      return normalizeDeviceContext(await this.sendJsonRpc('device.context', {}, traceOptions), traceOptions);
+    } catch (jsonRpcError) {
+      this.log('device.context json-rpc failed; trying command fallback', {
+        trace_id: traceOptions.traceId,
+        message: jsonRpcError.message || String(jsonRpcError)
+      });
+      return normalizeDeviceContext(await this.sendCommand('get-device-context', null, traceOptions), traceOptions);
+    }
+  }
+
+  taskMemory(args = {}) {
+    return taskMemoryOperation({
+      ...args,
+      path: this.taskMemoryPath
+    });
+  }
+
+  async inputTap(x, y, options = {}) {
+    return this.sendJsonRpc('input.tap', {
+      x: requireFiniteNumber(x, 'x'),
+      y: requireFiniteNumber(y, 'y'),
+      profile: cleanString(options.profile) || 'human'
+    }, options);
+  }
+
+  async inputLongPress(x, y, options = {}) {
+    return this.sendJsonRpc('input.longPress', {
+      x: requireFiniteNumber(x, 'x'),
+      y: requireFiniteNumber(y, 'y'),
+      durationMs: normalizeOptionalPositiveInt(options.durationMs || options.duration_ms),
+      profile: cleanString(options.profile) || 'human'
+    }, options);
+  }
+
+  async inputSwipe(args = {}) {
+    return this.sendJsonRpc('input.swipe', {
+      startX: requireFiniteNumber(args.startX, 'startX'),
+      startY: requireFiniteNumber(args.startY, 'startY'),
+      endX: requireFiniteNumber(args.endX, 'endX'),
+      endY: requireFiniteNumber(args.endY, 'endY'),
+      durationMs: normalizeOptionalPositiveInt(args.durationMs || args.duration_ms),
+      profile: cleanString(args.profile) || 'human'
+    }, args);
+  }
+
+  async inputGesture(args = {}) {
+    const rawPoints = Array.isArray(args.points) ? args.points : null;
+    if (!rawPoints || rawPoints.length < 2) {
+      throw new Error('points must be an array of at least 2 entries');
+    }
+    const points = rawPoints.map((p, i) => ({
+      x: requireFiniteNumber(p && p.x, `points[${i}].x`),
+      y: requireFiniteNumber(p && p.y, `points[${i}].y`),
+      tMs: requireFiniteNumber(p && (p.tMs ?? p.t_ms ?? p.t), `points[${i}].tMs`)
+    }));
+    return this.sendJsonRpc('input.gesture', {
+      points,
+      durationMs: normalizeOptionalPositiveInt(args.durationMs || args.duration_ms),
+      profile: cleanString(args.profile) || 'human'
+    }, args);
+  }
+
+  async inputText(text, options = {}) {
+    if (typeof text !== 'string') {
+      throw new Error('text is required');
+    }
+    return this.sendJsonRpc('input.text', {
+      text,
+      replace: Boolean(options.replace)
+    }, options);
+  }
+
+  async inputClear(options = {}) {
+    return this.sendJsonRpc('input.clear', {}, options);
+  }
+
+  async inputKey(key, options = {}) {
+    return this.sendJsonRpc('input.key', {
+      key: requireString(key, 'key')
+    }, options);
+  }
+
+  async globalAction(action, options = {}) {
+    return this.sendJsonRpc('device.globalAction', {
+      action: requireString(action, 'action')
+    }, options);
+  }
+
+  async appStart(packageName, options = {}) {
+    return this.sendJsonRpc('app.start', {
+      packageName: requireString(packageName, 'packageName'),
+      ...(cleanString(options.activity) ? { activity: cleanString(options.activity) } : {})
+    }, options);
+  }
+
+  async appStop(packageName, options = {}) {
+    return this.sendJsonRpc('app.stop', {
+      packageName: requireString(packageName, 'packageName')
+    }, options);
+  }
+
+  async listLaunchableApps(options = {}) {
+    return this.sendCommand('apps.listLaunchable', JSON.stringify({
+      includeSystem: options.includeSystem !== false
+    }), options);
+  }
+
+  async startScreenStream(text, options = {}) {
+    const traceOptions = this.prepareTraceOptions(options);
+    return runWithTrace(traceOptions.traceId, async () => {
+    const outputDir = path.resolve(options.outputDir || options.output_dir || this.outputDir);
+    fs.mkdirSync(outputDir, { recursive: true });
+    const startedAt = Date.now();
+    this.log('start h264 stream', {
+      trace_id: traceOptions.traceId,
+      outputDir,
+      hasText: optionalText(text) !== null
+    });
+    const file = await this.withConnectionRetry(
+      (client) => client.startH264Stream(optionalText(text), outputDir, {
+        traceId: traceOptions.traceId
+      }),
+      traceOptions
+    );
+    const size = fs.existsSync(file) ? fs.statSync(file).size : 0;
+    this.log('h264 stream finished', {
+      file,
+      bytes: size,
+      durationMs: Date.now() - startedAt
+    });
+    return file;
+    });
+  }
+
+  async startLiveView(text, options = {}) {
+    const traceOptions = this.prepareTraceOptions(options);
+    const host = cleanString(options.host) || DEFAULT_VIEW_HOST;
+    const port = normalizePort(options.port, DEFAULT_VIEW_PORT);
+    const server = new H264LiveViewServer(this, text, { host, port, traceId: traceOptions.traceId });
+    await server.start();
+    return server;
+  }
+
+  async callTool(name, args = {}) {
+    const traceOptions = this.prepareTraceOptions(args);
+    return runWithTrace(traceOptions.traceId, async () => {
+      this.log('tool call received', {
+        trace_id: traceOptions.traceId,
+        name,
+        hasTicketOverride: Boolean(cleanString(traceOptions.ticket))
+      });
+      switch (name) {
+        case 'kln_set_api_key':
+          return this.setApiKey(traceOptions.apiKey || traceOptions.api_key, traceOptions);
+        case 'kln_list_devices':
+          return this.listServerDevices(traceOptions);
+        case 'kln_select_device':
+          return this.selectDevice(traceOptions.deviceId || traceOptions.device_id, traceOptions);
+        case 'kln_send_command':
+          return this.sendCommand(traceOptions.name, traceOptions.text, traceOptions);
+        case 'kln_send_text':
+          return this.sendText(traceOptions.text, traceOptions);
+        case 'kln_start_screen_stream': {
+          const file = await this.startScreenStream(traceOptions.text, traceOptions);
+          return {
+            ok: true,
+            trace_id: traceOptions.traceId,
+            file,
+            summary: `H264 stream saved to ${file}`
+          };
+        }
+        case 'kln_get_device_context':
+          return this.getDeviceContext(traceOptions);
+        case 'kln_task_memory':
+          return this.taskMemory(traceOptions);
+        case 'kln_input_tap':
+          return this.inputTap(traceOptions.x, traceOptions.y, traceOptions);
+        case 'kln_input_swipe':
+          return this.inputSwipe(traceOptions);
+        case 'kln_input_text':
+          return this.inputText(traceOptions.text, traceOptions);
+        case 'kln_input_clear':
+          return this.inputClear(traceOptions);
+        case 'kln_input_key':
+          return this.inputKey(traceOptions.key, traceOptions);
+        case 'kln_device_global_action':
+          return this.globalAction(traceOptions.action, traceOptions);
+        case 'kln_app_start':
+          return this.appStart(traceOptions.packageName, traceOptions);
+        case 'kln_app_stop':
+          return this.appStop(traceOptions.packageName, traceOptions);
+        case 'kln_apps_list_launchable':
+          return this.listLaunchableApps(traceOptions);
+        default:
+          throw new Error(`unknown tool: ${name}`);
+      }
+    });
+  }
+
+  async close() {
+    if (this.subscriptionTimer) {
+      clearTimeout(this.subscriptionTimer);
+      this.subscriptionTimer = null;
+    }
+    if (!this.client) {
+      return;
+    }
+
+    const client = this.client;
+    this.client = null;
+    this.clientTicket = null;
+    this.clientKey = null;
+    this.connectPromise = null;
+    this.connectKey = null;
+    this.log('closing P2P connection');
+    await client.close();
+  }
+
+  resolveApiKey(options = {}) {
+    const apiKey = cleanString(options.apiKey || options.api_key || this.apiKey);
+    if (!apiKey) {
+      throw new Error('apiKey is required. Pass --api-key, set KLN_API_KEY, or call kln_set_api_key.');
+    }
+    this.apiKey = apiKey;
+    return apiKey;
+  }
+
+  async serverRequest(pathname, options = {}) {
+    const traceOptions = this.prepareTraceOptions(options);
+    if (!this.apiUrl) {
+      throw new Error('api_url is required in mcp/config or KLN_API_URL.');
+    }
+
+    const apiKey = this.resolveApiKey(traceOptions);
+    const url = new URL(pathname, ensureTrailingSlash(this.apiUrl));
+    this.log('server request', {
+      trace_id: traceOptions.traceId,
+      method: 'GET',
+      url: url.toString()
+    });
+
+    const payload = await requestJson(url, {
+      headers: {
+        'Api-Key': apiKey,
+        'Accept': 'application/json',
+        'X-Trace-Id': traceOptions.traceId
+      },
+      timeoutMs: normalizeTimeout(traceOptions.timeoutMs || traceOptions.timeout_ms, this.timeoutMs)
+    });
+
+    if (!payload || typeof payload !== 'object') {
+      throw new Error('server response is not JSON object');
+    }
+    if (payload.code !== 0) {
+      const message = payload.error || payload.message || 'server request failed';
+      if (isSubscriptionExpiredMessage(message)) {
+        this.recordSubscriptionStatus({ active: false, message: '订阅已到期' });
+        await this.close();
+      }
+      throw new Error(message);
+    }
+    return payload.data;
+  }
+
+  readCachedDeviceId() {
+    try {
+      const value = JSON.parse(fs.readFileSync(this.deviceCachePath, 'utf8'));
+      return cleanString(value && value.deviceId);
+    } catch (_) {
+      return '';
+    }
+  }
+
+  writeCachedDeviceId(deviceId) {
+    const normalized = cleanString(deviceId);
+    if (!normalized) {
+      return;
+    }
+    try {
+      fs.mkdirSync(path.dirname(this.deviceCachePath), { recursive: true });
+      fs.writeFileSync(this.deviceCachePath, `${JSON.stringify({
+        deviceId: normalized,
+        updatedAt: new Date().toISOString()
+      }, null, 2)}\n`);
+    } catch (error) {
+      this.log('write selected device cache failed', {
+        path: this.deviceCachePath,
+        message: error.message || String(error)
+      });
+    }
+  }
+
+  log(message, fields) {
+    writeDevLog(this.debug, message, fields);
+  }
+
+  prepareTraceOptions(options = {}) {
+    const traceId = resolveTraceId(options, this.traceId);
+    return {
+      ...options,
+      traceId,
+      trace_id: traceId
+    };
+  }
+}
+
+class H264LiveViewServer {
+  constructor(controller, text, options) {
+    this.controller = controller;
+    this.text = text;
+    this.host = options.host;
+    this.port = options.port;
+    this.traceId = options.traceId;
+    this.clients = new Set();
+    this.clientBuffers = new Map();
+    this.httpServer = null;
+    this.streaming = false;
+    this.connectionState = 'idle';
+    this.deviceConnectPromise = null;
+    this.cachedConfigPacket = null;
+    this.cachedKeyPacket = null;
+    this.closed = false;
+    this.closePromise = new Promise((resolve) => {
+      this.resolveClose = resolve;
+    });
+  }
+
+  get url() {
+    return `http://${this.host}:${this.port}/`;
+  }
+
+  async start() {
+    this.httpServer = http.createServer((request, response) => {
+      if (request.url === '/' || request.url === '/index.html') {
+        const html = loadLiveViewHtml();
+        response.writeHead(200, {
+          'content-type': 'text/html; charset=utf-8',
+          'content-length': Buffer.byteLength(html)
+        });
+        response.end(html);
+        return;
+      }
+
+      response.writeHead(404);
+      response.end('not found');
+    });
+
+    this.httpServer.on('upgrade', (request, socket) => {
+      if (request.url !== '/ws') {
+        socket.destroy();
+        return;
+      }
+      this.acceptWebSocket(request, socket);
+    });
+
+    await new Promise((resolve, reject) => {
+      this.httpServer.once('error', reject);
+      this.httpServer.listen(this.port, this.host, () => {
+        this.httpServer.off('error', reject);
+        resolve();
+      });
+    });
+
+    this.controller.log('live view server started', {
+      url: this.url,
+      note: 'P2P connection starts now; open this URL in a browser to view the H264 stream'
+    });
+    this.ensureDeviceConnection('startup').catch(() => {});
+    this.controller.log('live view waiting for browser websocket', {
+      wsUrl: `ws://${this.host}:${this.port}/ws`,
+      note: 'browser websocket only starts the H264 view stream'
+    });
+  }
+
+  async ensureDeviceConnection(reason) {
+    if (this.connectionState === 'connected') {
+      return this.controller.connect();
+    }
+
+    if (this.deviceConnectPromise) {
+      this.controller.log('live view waiting for existing device connection', {
+        reason,
+        state: this.connectionState
+      });
+      return this.deviceConnectPromise;
+    }
+
+    this.connectionState = 'connecting';
+    const startedAt = Date.now();
+    this.controller.log('live view establishing device connection', {
+      reason
+    });
+    this.deviceConnectPromise = this.controller.connect()
+      .then((client) => {
+        this.connectionState = 'connected';
+        this.controller.log('live view device connection ready', {
+          reason,
+          nodeId: client.nodeId,
+          durationMs: Date.now() - startedAt
+        });
+        this.broadcastJson({
+          type: 'connection',
+          state: this.connectionState
+        });
+        return client;
+      })
+      .catch((error) => {
+        this.connectionState = 'failed';
+        this.controller.log('live view device connection failed', {
+          reason,
+          message: error.message || String(error),
+          durationMs: Date.now() - startedAt
+        });
+        this.broadcastJson({
+          type: 'error',
+          message: `device connection failed: ${error.message || String(error)}`
+        });
+        throw error;
+      })
+      .finally(() => {
+        this.deviceConnectPromise = null;
+      });
+
+    return this.deviceConnectPromise;
+  }
+
+  acceptWebSocket(request, socket) {
+    const key = request.headers['sec-websocket-key'];
+    if (!key) {
+      socket.destroy();
+      return;
+    }
+
+    const accept = crypto
+      .createHash('sha1')
+      .update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
+      .digest('base64');
+
+    socket.write([
+      'HTTP/1.1 101 Switching Protocols',
+      'Upgrade: websocket',
+      'Connection: Upgrade',
+      `Sec-WebSocket-Accept: ${accept}`,
+      '\r\n'
+    ].join('\r\n'));
+
+    this.clients.add(socket);
+    this.clientBuffers.set(socket, Buffer.alloc(0));
+    this.controller.log('live view websocket connected', {
+      clients: this.clients.size,
+      remoteAddress: socket.remoteAddress || '<unknown>'
+    });
+    socket.on('close', () => {
+      this.clients.delete(socket);
+      this.clientBuffers.delete(socket);
+      this.controller.log('live view websocket closed', {
+        clients: this.clients.size
+      });
+    });
+    socket.on('error', (error) => {
+      this.clients.delete(socket);
+      this.clientBuffers.delete(socket);
+      this.controller.log('live view websocket error', {
+        message: error.message || String(error),
+        clients: this.clients.size
+      });
+    });
+    socket.on('data', (chunk) => {
+      this.handleWebSocketData(socket, chunk).catch((error) => {
+        this.sendJson(socket, {
+          type: 'input-error',
+          message: error.message || String(error)
+        });
+      });
+    });
+
+    this.sendJson(socket, {
+      type: 'hello',
+      url: this.url,
+      connectionState: this.connectionState
+    });
+    this.sendDeviceContext(socket, 'websocket-connected').catch(() => {});
+    this.replayCachedDecoderPackets(socket);
+
+    if (!this.streaming) {
+      this.controller.log('live view starting stream after websocket connection');
+      this.startStreaming().catch((error) => {
+        this.broadcastJson({
+          type: 'error',
+          message: error.message || String(error)
+        });
+        this.controller.log('live view stream failed', {
+          message: error.message || String(error)
+        });
+      }).finally(() => {
+        this.streaming = false;
+      });
+    }
+  }
+
+  async startStreaming() {
+    this.streaming = true;
+    this.controller.log('live h264 stream waiting for device connection');
+    const client = await this.ensureDeviceConnection('stream');
+    const startedAt = Date.now();
+    this.controller.log('live h264 stream request dispatching', {
+      hasText: optionalText(this.text) !== null
+    });
+    this.cachedConfigPacket = null;
+    this.cachedKeyPacket = null;
+
+    const stats = await new Promise((resolve, reject) => {
+      let packets = 0;
+      let bytes = 0;
+      let firstPacket = true;
+      this.controller.log('live h264 stream waiting for packets');
+      client.startH264Live(optionalText(this.text), (packet) => {
+        if (firstPacket) {
+          firstPacket = false;
+          this.controller.log('live h264 first packet received', {
+            kind: packet.kind,
+            flags: packet.flags,
+            bytes: packet.data ? packet.data.length : 0,
+            width: packet.width,
+            height: packet.height,
+            endReason: packet.endReason || undefined
+          });
+        }
+        if (packet.kind === 3) {
+          resolve({
+            packets,
+            bytes,
+            endReason: packet.endReason || 'ended'
+          });
+          return;
+        }
+        if (packet.kind === 4) {
+          reject(new Error(packet.endReason || 'h264 stream error'));
+          return;
+        }
+        packets += 1;
+        bytes += packet.data ? packet.data.length : 0;
+        const encodedPacket = encodeH264Packet(packet);
+        this.rememberDecoderPacket(packet, encodedPacket);
+        this.broadcastBinary(encodedPacket);
+      }, { traceId: this.traceId });
+    });
+
+    this.controller.log('live h264 stream finished', {
+      packets: stats.packets,
+      bytes: stats.bytes,
+      endReason: stats.endReason,
+      durationMs: Date.now() - startedAt
+    });
+    this.broadcastJson({
+      type: 'end',
+      reason: stats.endReason,
+      packets: stats.packets,
+      bytes: stats.bytes
+    });
+    this.cachedConfigPacket = null;
+    this.cachedKeyPacket = null;
+  }
+
+  rememberDecoderPacket(packet, encodedPacket) {
+    if (packet.kind === 1 || (packet.flags & 2) === 2) {
+      this.cachedConfigPacket = encodedPacket;
+    }
+    if (packet.kind === 2 && (packet.flags & 1) === 1) {
+      this.cachedKeyPacket = encodedPacket;
+    }
+  }
+
+  replayCachedDecoderPackets(socket) {
+    const packets = [];
+    if (this.cachedConfigPacket) {
+      packets.push(this.cachedConfigPacket);
+    }
+    if (this.cachedKeyPacket) {
+      packets.push(this.cachedKeyPacket);
+    }
+    if (packets.length === 0) {
+      return;
+    }
+
+    this.controller.log('live view replay cached decoder packets', {
+      packets: packets.length,
+      hasConfig: Boolean(this.cachedConfigPacket),
+      hasKeyFrame: Boolean(this.cachedKeyPacket)
+    });
+    for (const packet of packets) {
+      sendWebSocketFrame(socket, packet, 0x2);
+    }
+  }
+
+  sendJson(socket, payload) {
+    sendWebSocketFrame(socket, Buffer.from(JSON.stringify(payload)), 0x1);
+  }
+
+  broadcastJson(payload) {
+    const data = Buffer.from(JSON.stringify(payload));
+    for (const socket of this.clients) {
+      sendWebSocketFrame(socket, data, 0x1);
+    }
+  }
+
+  broadcastBinary(data) {
+    for (const socket of this.clients) {
+      sendWebSocketFrame(socket, data, 0x2);
+    }
+  }
+
+  async handleWebSocketData(socket, chunk) {
+    let buffer = Buffer.concat([this.clientBuffers.get(socket) || Buffer.alloc(0), chunk]);
+    while (buffer.length >= 2) {
+      const parsed = parseClientWebSocketFrame(buffer);
+      if (!parsed) {
+        break;
+      }
+      buffer = buffer.slice(parsed.consumed);
+      if (parsed.opcode === 0x8) {
+        socket.end();
+        return;
+      }
+      if (parsed.opcode !== 0x1) {
+        continue;
+      }
+      const message = JSON.parse(parsed.payload.toString('utf8'));
+      this.controller.log('live view input received from browser', inputLogFields(message));
+      this.handleBrowserInput(socket, message).catch((error) => {
+        this.sendJson(socket, {
+          type: 'input-error',
+          message: error.message || String(error)
+        });
+      });
+    }
+    this.clientBuffers.set(socket, buffer);
+  }
+
+  async handleBrowserInput(socket, message) {
+    if (!message || message.type !== 'input') {
+      return;
+    }
+    const traceId = cleanString(message.traceId || message.trace_id) || this.traceId;
+    const startedAt = Date.now();
+    const ack = (payload) => {
+      this.sendJson(socket, {
+        ...payload,
+        clientSentAtMs: message.clientSentAtMs,
+        serverReceivedAtMs: startedAt,
+        serverAckAtMs: Date.now()
+      });
+    };
+    if (message.action === 'tap') {
+      const result = await this.controller.inputTap(message.x, message.y, {
+        profile: message.profile || 'human',
+        traceId
+      });
+      this.controller.log('live view input ack from device', {
+        ...inputLogFields(message),
+        serverToAckMs: Date.now() - startedAt
+      });
+      ack({ type: 'input-ack', action: 'tap', result });
+      return;
+    }
+    if (message.action === 'longPress') {
+      const result = await this.controller.inputLongPress(message.x, message.y, {
+        durationMs: message.durationMs,
+        profile: message.profile || 'human',
+        traceId
+      });
+      this.controller.log('live view input ack from device', {
+        ...inputLogFields(message),
+        durationMs: message.durationMs,
+        serverToAckMs: Date.now() - startedAt
+      });
+      ack({ type: 'input-ack', action: 'longPress', result });
+      return;
+    }
+    if (message.action === 'swipe') {
+      const result = await this.controller.inputSwipe({
+        startX: message.startX,
+        startY: message.startY,
+        endX: message.endX,
+        endY: message.endY,
+        durationMs: message.durationMs,
+        profile: message.profile || 'human',
+        traceId
+      });
+      this.controller.log('live view input ack from device', {
+        ...inputLogFields(message),
+        serverToAckMs: Date.now() - startedAt
+      });
+      ack({ type: 'input-ack', action: 'swipe', result });
+      return;
+    }
+    if (message.action === 'gesture') {
+      const result = await this.controller.inputGesture({
+        points: message.points,
+        durationMs: message.durationMs,
+        profile: message.profile || 'human',
+        traceId
+      });
+      this.controller.log('live view input ack from device', {
+        ...inputLogFields(message),
+        pointCount: Array.isArray(message.points) ? message.points.length : 0,
+        serverToAckMs: Date.now() - startedAt
+      });
+      ack({ type: 'input-ack', action: 'gesture', result });
+      return;
+    }
+    throw new Error(`unsupported browser input action: ${message.action}`);
+  }
+
+  async sendDeviceContext(socket, reason) {
+    try {
+      const context = await this.controller.getDeviceContext({ traceId: this.traceId });
+      this.sendJson(socket, {
+        type: 'device-context',
+        reason,
+        context,
+        serverSentAtMs: Date.now()
+      });
+      this.controller.log('live view device context sent', {
+        reason
+      });
+    } catch (error) {
+      this.sendJson(socket, {
+        type: 'device-context-error',
+        reason,
+        message: error.message || String(error),
+        serverSentAtMs: Date.now()
+      });
+      this.controller.log('live view device context query failed', {
+        reason,
+        message: error.message || String(error)
+      });
+    }
+  }
+
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    for (const socket of this.clients) {
+      socket.end();
+    }
+    this.clients.clear();
+    if (this.httpServer) {
+      await new Promise((resolve) => this.httpServer.close(resolve));
+    }
+    await this.controller.close();
+    this.resolveClose();
+  }
+
+  wait() {
+    return this.closePromise;
+  }
+}
+
+class KlnMcpServer {
+  constructor(options = {}) {
+    this.controller = options.controller || new KlnMobileController(options);
+    this.serverInfo = {
+      name: options.name || 'kln-mobile-ctrl',
+      version: options.version || '0.1.0'
+    };
+  }
+
+  async handleRequest(request) {
+    const { id, method, params = {} } = request;
+    const traceId = resolveTraceId(params && params.arguments ? params.arguments : params, this.controller.traceId);
+    return runWithTrace(traceId, async () => {
+      this.controller.log('mcp request received', {
+        trace_id: traceId,
+        id,
+        method
+      });
+
+    try {
+      if (method === 'initialize') {
+        return response(id, {
+          protocolVersion: params.protocolVersion || '2024-11-05',
+          capabilities: { tools: {} },
+          serverInfo: this.serverInfo
+        });
+      }
+
+      if (method === 'notifications/initialized') {
+        return null;
+      }
+
+      if (method === 'tools/list') {
+        return response(id, { tools: TOOL_DEFINITIONS });
+      }
+
+      if (method === 'tools/call') {
+        const args = {
+          ...(params.arguments || {}),
+          traceId: cleanString((params.arguments || {}).traceId || (params.arguments || {}).trace_id) || traceId
+        };
+        const result = await this.controller.callTool(params.name, args);
+        return response(id, {
+          content: [
+            {
+              type: 'text',
+              text: formatToolResult(result)
+            }
+          ]
+        });
+      }
+
+      return errorResponse(id, -32601, `method not found: ${method}`, traceId);
+    } catch (error) {
+      return errorResponse(id, -32000, error.message || String(error), traceId);
+    }
+    });
+  }
+
+  async listenStdio(input = process.stdin, output = process.stdout) {
+    let buffer = Buffer.alloc(0);
+    this.controller.log('mcp stdio server started; waiting for MCP client requests', {
+      note: 'P2P connection is created on the first tool call, not at process startup'
+    });
+
+    input.on('data', async (chunk) => {
+      this.controller.log('stdio data received', {
+        bytes: chunk.length
+      });
+      buffer = Buffer.concat([buffer, chunk]);
+      const parsed = parseMessages(buffer);
+      buffer = parsed.rest;
+
+      for (const message of parsed.messages) {
+        const result = await this.handleRequest(message);
+        if (result) {
+          writeJsonRpc(output, result);
+        }
+      }
+    });
+
+    const shutdown = async () => {
+      await this.controller.close();
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+  }
+}
+
+function createController(options) {
+  return new KlnMobileController(options);
+}
+
+function createMcpServer(options) {
+  return new KlnMcpServer(options);
+}
+
+function normalizeMessage(message) {
+  if (!message || typeof message !== 'object') {
+    return message;
+  }
+
+  const body = normalizeBody(message.body);
+  return {
+    ...message,
+    body,
+    ok: responseOk(body),
+    text: responseText(body),
+    media: responseMedia(body)
+  };
+}
+
+function normalizeDeviceList(data) {
+  const source = Array.isArray(data)
+    ? data
+    : Array.isArray(data && data.devices)
+      ? data.devices
+      : Array.isArray(data && data.list)
+        ? data.list
+        : [];
+  return source.map(normalizeDevice).filter(Boolean);
+}
+
+function normalizeDevice(data) {
+  if (!data || typeof data !== 'object') {
+    return null;
+  }
+  const deviceId = cleanString(data.deviceId || data.device_id || data.id);
+  const ticket = cleanString(data.ticket);
+  if (!deviceId) {
+    return null;
+  }
+  return {
+    deviceId,
+    deviceInfo: data.deviceInfo || data.device_info || '',
+    deviceRemark: data.deviceRemark || data.device_remark || data.remark || '',
+    ticket,
+    lastHeartbeatAt: data.lastHeartbeatAt || data.last_heartbeat_at || 0,
+    status: data.status,
+    subscription: normalizeSubscriptionStatus(data.subscription)
+  };
+}
+
+function normalizeSubscriptionStatus(data) {
+  if (!data || typeof data !== 'object') {
+    return null;
+  }
+  const expiresAt = cleanString(data.expiresAt || data.expires_at);
+  const graceUntil = cleanString(data.graceUntil || data.grace_until);
+  const nextCheckAt = cleanString(data.nextCheckAt || data.next_check_at);
+  const expiresAtMs = parseDateMs(expiresAt);
+  const graceUntilMs = parseDateMs(graceUntil);
+  const nextCheckAtMs = parseDateMs(nextCheckAt);
+  return {
+    active: data.active !== false,
+    userId: data.userId || data.user_id || 0,
+    vipLevel: data.vipLevel || data.vip_level || 0,
+    expiresAt,
+    expiresAtMs,
+    graceUntil,
+    graceUntilMs,
+    nextCheckAt,
+    nextCheckAtMs,
+    message: data.message || ''
+  };
+}
+
+function parseDateMs(value) {
+  if (!value) {
+    return 0;
+  }
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function requestJson(url, options = {}) {
+  const timeoutMs = normalizeTimeout(options.timeoutMs || options.timeout_ms, DEFAULT_TIMEOUT_MS);
+  return new Promise((resolve, reject) => {
+    const transport = url.protocol === 'https:' ? https : http;
+    const request = transport.request(url, {
+      method: options.method || 'GET',
+      headers: options.headers || {}
+    }, (response) => {
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          reject(new Error(`server HTTP ${response.statusCode}: ${text}`));
+          return;
+        }
+        try {
+          resolve(text ? JSON.parse(text) : null);
+        } catch (error) {
+          reject(new Error(`server response JSON parse failed: ${error.message || error}`));
+        }
+      });
+    });
+    request.once('error', reject);
+    request.setTimeout(timeoutMs, () => {
+      request.destroy(new Error(`server request timed out after ${timeoutMs}ms`));
+    });
+    request.end(options.body || undefined);
+  });
+}
+
+function ensureTrailingSlash(value) {
+  const text = String(value || '');
+  return text.endsWith('/') ? text : `${text}/`;
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isLikelyConnectionError(error) {
+  const message = String(error && (error.message || error)).toLowerCase();
+  return [
+    'iroh',
+    'p2p',
+    '连接',
+    'quic',
+    'connection',
+    'connect',
+    'closed',
+    'reset',
+    'broken pipe',
+    'timed out',
+    'timeout',
+    'deadline',
+    'aborted',
+    'eof'
+  ].some((needle) => message.includes(needle));
+}
+
+function isSubscriptionExpiredError(error) {
+  return isSubscriptionExpiredMessage(error && (error.message || error));
+}
+
+function isSubscriptionExpiredMessage(message) {
+  return String(message || '').includes('订阅已到期');
+}
+
+function normalizeDeviceContext(value, options = {}) {
+  const unwrapped = unwrapDeviceContext(value);
+  const parsed = typeof unwrapped === 'string' ? parseJsonMaybe(unwrapped) : unwrapped;
+  if (!parsed || typeof parsed !== 'object') {
+    return parsed;
+  }
+  return compactDeviceContext(parsed, options);
+}
+
+function unwrapDeviceContext(value) {
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  if (Object.prototype.hasOwnProperty.call(value, 'device_context')) {
+    return value.device_context;
+  }
+  if (Object.prototype.hasOwnProperty.call(value, 'deviceContext')) {
+    return value.deviceContext;
+  }
+  if (Object.prototype.hasOwnProperty.call(value, 'result')) {
+    return unwrapDeviceContext(value.result);
+  }
+  if (Object.prototype.hasOwnProperty.call(value, 'data')) {
+    return unwrapDeviceContext(value.data);
+  }
+  if (Object.prototype.hasOwnProperty.call(value, 'body')) {
+    return unwrapDeviceContext(normalizeBody(value.body));
+  }
+  if (Object.prototype.hasOwnProperty.call(value, 'text')) {
+    return parseJsonMaybe(value.text);
+  }
+  return value;
+}
+
+function parseJsonMaybe(value) {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return value;
+  }
+  try {
+    return unwrapDeviceContext(JSON.parse(trimmed));
+  } catch {
+    return value;
+  }
+}
+
+function compactDeviceContext(source, options = {}) {
+  const limit = normalizeElementLimit(options.maxElements || options.max_elements, DEFAULT_CONTEXT_ELEMENT_LIMIT);
+  const collected = collectContextElements(source, limit);
+  const result = {};
+  const app = firstString(
+    source.app,
+    source.package,
+    source.packageName,
+    source.package_name,
+    source.currentPackage,
+    source.current_package,
+    source.topPackage,
+    source.top_package
+  );
+  const activity = firstString(source.activity, source.activityName, source.activity_name, source.currentActivity, source.current_activity);
+  const pageHint = firstString(source.page_hint, source.pageHint, source.page, activity);
+  const screenBounds = findScreenBounds(source);
+  const screenshotRef = firstString(source.screenshot_ref, source.screenshotRef, source.frame_ref, source.frameRef, source.frame_id, source.frameId);
+
+  if (app) result.app = app;
+  if (pageHint) result.page_hint = pageHint;
+  if (screenBounds) result.screen_bounds = screenBounds;
+  result.elements = collected.elements;
+  if (collected.truncated) result.truncated = true;
+  if (screenshotRef) result.screenshot_ref = screenshotRef;
+  return result;
+}
+
+function collectContextElements(source, limit) {
+  const elements = [];
+  const seenObjects = new WeakSet();
+  const seenElements = new Set();
+  let truncated = false;
+
+  const visit = (node) => {
+    if (node === null || typeof node !== 'object') {
+      return;
+    }
+    if (seenObjects.has(node)) {
+      return;
+    }
+    seenObjects.add(node);
+
+    const element = compactContextElement(node, elements.length);
+    if (element) {
+      const fingerprint = `${element.kind}|${element.text || ''}|${(element.bounds || []).join(',')}`;
+      if (!seenElements.has(fingerprint)) {
+        seenElements.add(fingerprint);
+        if (elements.length < limit) {
+          elements.push(element);
+        } else {
+          truncated = true;
+          return;
+        }
+      }
+    }
+
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        visit(item);
+        if (truncated) return;
+      }
+      return;
+    }
+
+    for (const key of Object.keys(node)) {
+      if (isScalarContextKey(key)) {
+        continue;
+      }
+      visit(node[key]);
+      if (truncated) return;
+    }
+  };
+
+  visit(source);
+  return { elements, truncated };
+}
+
+function compactContextElement(node, index) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) {
+    return null;
+  }
+  if (!isClickableElement(node) && !isAlreadyCompactElement(node)) {
+    return null;
+  }
+
+  const text = compactElementText(node);
+  if (!text) {
+    return null;
+  }
+
+  const element = {
+    i: index,
+    kind: inferElementKind(node),
+    text
+  };
+  const bounds = normalizeBounds(firstDefined(
+    node.bounds,
+    node.bound,
+    node.rect,
+    node.frame,
+    node.visibleBounds,
+    node.visible_bounds,
+    node.screenBounds,
+    node.screen_bounds
+  ));
+  if (bounds) {
+    element.bounds = bounds;
+  }
+  return element;
+}
+
+function compactElementText(node) {
+  const text = [
+    firstString(
+      node.text,
+      node.label,
+      node.name,
+      node.title,
+      node.contentDescription,
+      node.content_description,
+      node.desc,
+      node.description,
+      node.accessibilityLabel,
+      node.accessibility_label
+    ),
+    firstString(node.hint, node.placeholder)
+  ].filter(Boolean).join(' ');
+  return truncateText(text.replace(/\s+/g, ' ').trim(), MAX_CONTEXT_TEXT_LENGTH);
+}
+
+function isClickableElement(node) {
+  return booleanLike(node.clickable)
+    || booleanLike(node.isClickable)
+    || booleanLike(node.is_clickable)
+    || booleanLike(node.longClickable)
+    || booleanLike(node.long_clickable)
+    || booleanLike(node.focusable)
+    || booleanLike(node.actionable)
+    || hasClickAction(node);
+}
+
+function isAlreadyCompactElement(node) {
+  return Object.prototype.hasOwnProperty.call(node, 'i')
+    && (Object.prototype.hasOwnProperty.call(node, 'text') || Object.prototype.hasOwnProperty.call(node, 'desc'));
+}
+
+function hasClickAction(node) {
+  const actions = node.actions || node.actionList || node.action_list;
+  if (Array.isArray(actions)) {
+    return actions.some((action) => String(action && (action.name || action.id || action)).toLowerCase().includes('click'));
+  }
+  if (typeof actions === 'string') {
+    return actions.toLowerCase().includes('click');
+  }
+  return false;
+}
+
+function inferElementKind(node) {
+  const explicit = firstString(node.kind, node.role, node.type);
+  if (explicit) {
+    return truncateText(explicit.toLowerCase(), 24);
+  }
+  const className = firstString(node.className, node.class_name, node.class, node.widget, node.nodeType, node.node_type) || '';
+  const lower = className.toLowerCase();
+  if (lower.includes('edittext') || lower.includes('textfield') || lower.includes('input')) return 'input';
+  if (lower.includes('button')) return 'btn';
+  if (lower.includes('image')) return 'img';
+  if (lower.includes('video')) return 'video';
+  if (lower.includes('text')) return 'text';
+  if (booleanLike(node.longClickable) || booleanLike(node.long_clickable)) return 'long_press';
+  return 'item';
+}
+
+function findScreenBounds(source) {
+  const direct = normalizeBounds(firstDefined(
+    source.screen_bounds,
+    source.screenBounds,
+    source.displayBounds,
+    source.display_bounds,
+    source.windowBounds,
+    source.window_bounds
+  ));
+  if (direct) {
+    return direct;
+  }
+  const width = firstFiniteNumber(source.width, source.screenWidth, source.screen_width, source.displayWidth, source.display_width);
+  const height = firstFiniteNumber(source.height, source.screenHeight, source.screen_height, source.displayHeight, source.display_height);
+  if (width && height) {
+    return [0, 0, Math.round(width), Math.round(height)];
+  }
+  const display = source.display || source.metrics || source.displayMetrics || source.display_metrics;
+  if (display && typeof display === 'object') {
+    const displayWidth = firstFiniteNumber(display.width, display.screenWidth, display.screen_width, display.displayWidth, display.display_width);
+    const displayHeight = firstFiniteNumber(display.height, display.screenHeight, display.screen_height, display.displayHeight, display.display_height);
+    if (displayWidth && displayHeight) {
+      return [0, 0, Math.round(displayWidth), Math.round(displayHeight)];
+    }
+  }
+  return null;
+}
+
+function normalizeBounds(value) {
+  if (!value) {
+    return null;
+  }
+  if (Array.isArray(value) && value.length >= 4) {
+    const numbers = value.slice(0, 4).map(Number);
+    return numbers.every(Number.isFinite) ? numbers.map(Math.round) : null;
+  }
+  if (typeof value === 'string') {
+    const numbers = value.match(/-?\d+(?:\.\d+)?/g);
+    if (numbers && numbers.length >= 4) {
+      return normalizeBounds(numbers.slice(0, 4));
+    }
+    return null;
+  }
+  if (typeof value !== 'object') {
+    return null;
+  }
+  const left = firstFiniteNumber(value.left, value.x, value.l);
+  const top = firstFiniteNumber(value.top, value.y, value.t);
+  let right = firstFiniteNumber(value.right, value.r);
+  let bottom = firstFiniteNumber(value.bottom, value.b);
+  const width = firstFiniteNumber(value.width, value.w);
+  const height = firstFiniteNumber(value.height, value.h);
+  if (right === undefined && left !== undefined && width !== undefined) {
+    right = left + width;
+  }
+  if (bottom === undefined && top !== undefined && height !== undefined) {
+    bottom = top + height;
+  }
+  if ([left, top, right, bottom].every(Number.isFinite)) {
+    return [left, top, right, bottom].map(Math.round);
+  }
+  return null;
+}
+
+function normalizeElementLimit(value, fallback) {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+  const number = Number(value);
+  if (!Number.isInteger(number) || number <= 0) {
+    throw new Error(`invalid maxElements: ${value}`);
+  }
+  return number;
+}
+
+function firstDefined(...values) {
+  return values.find((value) => value !== undefined && value !== null);
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) {
+      return value.trim();
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return String(value);
+    }
+  }
+  return '';
+}
+
+function firstFiniteNumber(...values) {
+  for (const value of values) {
+    const number = Number(value);
+    if (Number.isFinite(number)) {
+      return number;
+    }
+  }
+  return undefined;
+}
+
+function booleanLike(value) {
+  return value === true || value === 'true' || value === 1 || value === '1';
+}
+
+function truncateText(value, maxLength) {
+  if (!value || value.length <= maxLength) {
+    return value || '';
+  }
+  return value.slice(0, Math.max(0, maxLength - 1)) + '…';
+}
+
+function isScalarContextKey(key) {
+  return [
+    'text',
+    'label',
+    'name',
+    'title',
+    'contentDescription',
+    'content_description',
+    'desc',
+    'description',
+    'bounds',
+    'bound',
+    'rect',
+    'frame',
+    'visibleBounds',
+    'visible_bounds',
+    'screenBounds',
+    'screen_bounds',
+    'displayBounds',
+    'display_bounds',
+    'windowBounds',
+    'window_bounds',
+    'display',
+    'metrics',
+    'displayMetrics',
+    'display_metrics'
+  ].includes(key);
+}
+
+function taskMemoryOperation(args = {}) {
+  const op = requireString(args.op, 'op').toLowerCase();
+  const memoryPath = cleanString(args.path) || DEFAULT_TASK_MEMORY_PATH;
+  const store = readTaskMemoryStore(memoryPath);
+
+  if (op === 'list') {
+    const tasks = Object.keys(store).sort((a, b) => {
+      const left = parseDateMs(store[a] && store[a].last_updated);
+      const right = parseDateMs(store[b] && store[b].last_updated);
+      return right - left;
+    }).map((key) => ({
+      key,
+      summary: String(store[key] && store[key].summary || ''),
+      progress: String(store[key] && store[key].progress || ''),
+      last_updated: String(store[key] && store[key].last_updated || '')
+    }));
+    return {
+      ok: true,
+      path: memoryPath,
+      tasks
+    };
+  }
+
+  if (op === 'get') {
+    const key = requireMemoryKey(args.key);
+    const entry = store[key];
+    if (!entry) {
+      return {
+        ok: false,
+        path: memoryPath,
+        key,
+        error: 'task memory key not found'
+      };
+    }
+    return {
+      ok: true,
+      path: memoryPath,
+      key,
+      ...entry
+    };
+  }
+
+  if (op === 'put') {
+    const key = requireMemoryKey(args.key);
+    const summary = requireString(args.summary, 'summary');
+    const progress = requireString(args.progress, 'progress');
+    if (typeof args.value !== 'string' || args.value.length === 0) {
+      throw new Error('value is required and must be a non-empty string for put');
+    }
+    store[key] = {
+      summary,
+      progress,
+      value: args.value,
+      last_updated: new Date().toISOString()
+    };
+    writeTaskMemoryStore(memoryPath, store);
+    return {
+      ok: true,
+      path: memoryPath,
+      key,
+      summary,
+      progress,
+      last_updated: store[key].last_updated
+    };
+  }
+
+  if (op === 'delete') {
+    const key = requireMemoryKey(args.key);
+    const existed = Object.prototype.hasOwnProperty.call(store, key);
+    if (existed) {
+      delete store[key];
+      writeTaskMemoryStore(memoryPath, store);
+    }
+    return {
+      ok: true,
+      path: memoryPath,
+      key,
+      deleted: existed
+    };
+  }
+
+  throw new Error(`unsupported task memory op: ${op}`);
+}
+
+function checkTaskMemoryFile(memoryPath = DEFAULT_TASK_MEMORY_PATH) {
+  const targetPath = cleanString(memoryPath) || DEFAULT_TASK_MEMORY_PATH;
+  const existed = fs.existsSync(targetPath);
+  let raw = existed ? fs.readFileSync(targetPath, 'utf8') : '';
+  let data = {};
+  if (raw.trim()) {
+    data = JSON.parse(raw);
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throw new Error('task memory file must contain a JSON object');
+    }
+  }
+  if (!existed) {
+    raw = `${JSON.stringify(data, null, 2)}\n`;
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, raw || '{}\n', { mode: 0o600 });
+  readTaskMemoryStore(targetPath);
+  return {
+    ok: true,
+    path: targetPath,
+    readable: true,
+    writable: true
+  };
+}
+
+function readTaskMemoryStore(memoryPath) {
+  if (!fs.existsSync(memoryPath)) {
+    return {};
+  }
+  const raw = fs.readFileSync(memoryPath, 'utf8');
+  if (!raw.trim()) {
+    return {};
+  }
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('task memory file must contain a JSON object');
+  }
+  return parsed;
+}
+
+function writeTaskMemoryStore(memoryPath, store) {
+  fs.mkdirSync(path.dirname(memoryPath), { recursive: true });
+  const tempPath = `${memoryPath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(tempPath, memoryPath);
+}
+
+function requireMemoryKey(value) {
+  const key = requireString(value, 'key');
+  if (!/^[A-Za-z0-9._:-]+$/.test(key)) {
+    throw new Error('key may only contain letters, numbers, dot, underscore, colon, or hyphen');
+  }
+  return key;
+}
+
+function normalizeBody(body) {
+  if (!body || typeof body !== 'object') {
+    return body;
+  }
+
+  const keys = Object.keys(body);
+  if (keys.length === 1) {
+    const key = keys[0];
+    return {
+      kind: key.toLowerCase(),
+      ...body[key]
+    };
+  }
+  return body;
+}
+
+function responseOk(body) {
+  if (body && body.kind === 'response') {
+    return Boolean(body.ok);
+  }
+  return body && body.kind === 'error' ? false : undefined;
+}
+
+function responseText(body) {
+  if (!body || typeof body !== 'object') {
+    return undefined;
+  }
+  return body.text || body.message;
+}
+
+function responseMedia(body) {
+  if (!body || typeof body !== 'object') {
+    return undefined;
+  }
+  return body.media;
+}
+
+function writeJsonRpc(output, payload) {
+  const data = Buffer.from(JSON.stringify(payload), 'utf8');
+  output.write(`Content-Length: ${data.length}\r\n\r\n`);
+  output.write(data);
+}
+
+function parseMessages(buffer) {
+  const messages = [];
+  let offset = 0;
+
+  while (offset < buffer.length) {
+    const headerEnd = buffer.indexOf('\r\n\r\n', offset);
+    if (headerEnd === -1) {
+      break;
+    }
+
+    const header = buffer.slice(offset, headerEnd).toString('utf8');
+    const match = /^content-length:\s*(\d+)$/im.exec(header);
+    if (!match) {
+      throw new Error('invalid MCP message header: missing Content-Length');
+    }
+
+    const length = Number(match[1]);
+    const bodyStart = headerEnd + 4;
+    const bodyEnd = bodyStart + length;
+    if (buffer.length < bodyEnd) {
+      break;
+    }
+
+    const raw = buffer.slice(bodyStart, bodyEnd).toString('utf8');
+    messages.push(JSON.parse(raw));
+    offset = bodyEnd;
+  }
+
+  return {
+    messages,
+    rest: buffer.slice(offset)
+  };
+}
+
+function response(id, result) {
+  return {
+    jsonrpc: '2.0',
+    id,
+    result
+  };
+}
+
+function errorResponse(id, code, message, traceId) {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code,
+      message,
+      ...(traceId ? { data: { trace_id: traceId } } : {})
+    }
+  };
+}
+
+function formatToolResult(result) {
+  if (typeof result === 'string') {
+    return result;
+  }
+
+  return JSON.stringify(result, null, 2);
+}
+
+function cleanString(value) {
+  if (typeof value !== 'string') {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed || undefined;
+}
+
+function resolveTraceId(options = {}, fallback) {
+  return cleanString(options.traceId || options.trace_id)
+    || cleanString(fallback)
+    || currentTraceId()
+    || createTraceId();
+}
+
+function currentTraceId() {
+  return cleanString(traceStorage.getStore());
+}
+
+function runWithTrace(traceId, fn) {
+  return traceStorage.run(traceId, fn);
+}
+
+function createTraceId() {
+  return crypto.randomBytes(16).toString('hex');
+}
+
+function normalizePort(value, fallback) {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+  const port = Number(value);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`invalid port: ${value}`);
+  }
+  return port;
+}
+
+function requireFiniteNumber(value, name) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) {
+    throw new Error(`${name} must be a finite number`);
+  }
+  return number;
+}
+
+function requireString(value, name) {
+  const text = cleanString(value);
+  if (!text) {
+    throw new Error(`${name} is required`);
+  }
+  return text;
+}
+
+function normalizeOptionalPositiveInt(value) {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  const number = Number(value);
+  if (!Number.isInteger(number) || number <= 0) {
+    throw new Error(`expected positive integer, got ${value}`);
+  }
+  return number;
+}
+
+function inputLogFields(message) {
+  const clientSentAtMs = Number(message && message.clientSentAtMs);
+  return {
+    action: message && message.action,
+    clientToServerMs: Number.isFinite(clientSentAtMs) ? Date.now() - clientSentAtMs : undefined
+  };
+}
+
+function encodeH264Packet(packet) {
+  const data = Buffer.from(packet.data || []);
+  const header = Buffer.alloc(33);
+  header.writeUInt8(packet.kind, 0);
+  header.writeUInt32LE(packet.flags || 0, 1);
+  header.writeUInt32LE(packet.width || 0, 5);
+  header.writeUInt32LE(packet.height || 0, 9);
+  header.writeBigInt64LE(BigInt(Math.trunc(packet.presentationTimeUs || 0)), 13);
+  header.writeBigUInt64LE(BigInt(Math.trunc(packet.capturedAtMs || 0)), 21);
+  header.writeUInt32LE(data.length, 29);
+  return Buffer.concat([header, data]);
+}
+
+function sendWebSocketFrame(socket, data, opcode) {
+  if (socket.destroyed || !socket.writable) {
+    return;
+  }
+  const length = data.length;
+  let header;
+  if (length < 126) {
+    header = Buffer.alloc(2);
+    header[1] = length;
+  } else if (length <= 0xffff) {
+    header = Buffer.alloc(4);
+    header[1] = 126;
+    header.writeUInt16BE(length, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(length), 2);
+  }
+  header[0] = 0x80 | opcode;
+  socket.write(Buffer.concat([header, data]));
+}
+
+function parseClientWebSocketFrame(buffer) {
+  if (buffer.length < 2) {
+    return null;
+  }
+  const first = buffer[0];
+  const second = buffer[1];
+  const opcode = first & 0x0f;
+  const masked = (second & 0x80) === 0x80;
+  let length = second & 0x7f;
+  let offset = 2;
+  if (length === 126) {
+    if (buffer.length < offset + 2) return null;
+    length = buffer.readUInt16BE(offset);
+    offset += 2;
+  } else if (length === 127) {
+    if (buffer.length < offset + 8) return null;
+    const bigLength = buffer.readBigUInt64BE(offset);
+    if (bigLength > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new Error('websocket frame too large');
+    }
+    length = Number(bigLength);
+    offset += 8;
+  }
+  if (!masked) {
+    throw new Error('browser websocket frame was not masked');
+  }
+  if (buffer.length < offset + 4 + length) {
+    return null;
+  }
+  const mask = buffer.slice(offset, offset + 4);
+  offset += 4;
+  const payload = Buffer.from(buffer.slice(offset, offset + length));
+  for (let index = 0; index < payload.length; index += 1) {
+    payload[index] ^= mask[index % 4];
+  }
+  return {
+    opcode,
+    payload,
+    consumed: offset + length
+  };
+}
+
+function loadLiveViewHtml() {
+  return fs.readFileSync(LIVE_VIEW_HTML_PATH, 'utf8');
+}
+
+function summarizeTicket(ticket) {
+  const value = cleanString(ticket);
+  if (!value) {
+    return '<missing>';
+  }
+  if (value.length <= 16) {
+    return `<${value.length} chars>`;
+  }
+  return `${value.slice(0, 8)}...${value.slice(-8)} (${value.length} chars)`;
+}
+
+function writeDevLog(enabled, message, fields) {
+  if (!enabled) {
+    return;
+  }
+  const timestamp = new Date().toISOString();
+  const traceId = fields && (fields.trace_id || fields.traceId) ? (fields.trace_id || fields.traceId) : currentTraceId();
+  const fieldCopy = fields ? { ...fields } : undefined;
+  if (fieldCopy && fieldCopy.traceId) {
+    delete fieldCopy.traceId;
+  }
+  const normalizedFields = traceId
+    ? { trace_id: traceId, ...(fieldCopy || {}) }
+    : fieldCopy;
+  const details = normalizedFields ? ` ${JSON.stringify(normalizedFields)}` : '';
+  process.stderr.write(`[kln:mcp:dev] ${timestamp} ${message}${details}\n`);
+}
+
+function optionalText(value) {
+  const text = cleanString(value);
+  return text === undefined ? null : text;
+}
+
+function requireTicket(ticket) {
+  const normalized = cleanString(ticket);
+  if (!normalized) {
+    throw new Error('ticket is required. Pass --ticket or set KLN_TICKET.');
+  }
+  return normalized;
+}
+
+function normalizeRelayUrls(value) {
+  if (Array.isArray(value)) {
+    return value.filter(Boolean).map(String);
+  }
+  if (typeof value === 'string' && value.trim()) {
+    return value.split(',').map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function normalizeTimeout(value, fallback) {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+  const timeout = Number(value);
+  if (!Number.isFinite(timeout) || timeout < 0) {
+    throw new Error(`invalid timeoutMs: ${value}`);
+  }
+  return Math.trunc(timeout);
+}
+
+module.exports = {
+  KlnMobileController,
+  KlnMcpServer,
+  H264LiveViewServer,
+  TOOL_DEFINITIONS,
+  createController,
+  createMcpServer,
+  normalizeMessage,
+  taskMemoryOperation,
+  checkTaskMemoryFile,
+  parseMessages,
+  writeJsonRpc
+};