@kvell007/embed-labs-cli 0.1.0-alpha.7 → 0.1.0-alpha.70

package/dist/embed-labs-mcp-bridge.mjs

@@ -0,0 +1,3139 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(SCRIPT_DIR, "../../../../..");
+const DEFAULT_TEMPLATE_ID = "taishanpi-1m-rk3566";
+const DEFAULT_HOST = "198.19.77.2";
+const DEFAULT_PORTS = "22,15301";
+const DEFAULT_STATUS_PORTS = "22";
+const TOOL_INTEGRITY_RELOGIN_MESSAGE = "工具完整性校验失败，请在当前电脑重新执行 embedlabs auth login --token <key>";
+const MCP_SERVER_VERSION = "0.2.40";
+const MCP_ICON_FILES = [
+  { fileName: "embed-labs-icon-dark.png", theme: "dark" },
+  { fileName: "embed-labs-icon-light.png", theme: "light" }
+];
+
+function iconDataUri(fileName) {
+  const candidates = [
+    path.join(SCRIPT_DIR, "..", "assets", fileName),
+    path.join(SCRIPT_DIR, "assets", fileName)
+  ];
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    const data = readFileSync(candidate).toString("base64");
+    return `data:image/png;base64,${data}`;
+  }
+  return null;
+}
+
+function mcpServerInfo() {
+  const icons = MCP_ICON_FILES
+    .map(({ fileName, theme }) => {
+      const src = iconDataUri(fileName);
+      return src ? { src, mimeType: "image/png", sizes: ["100x100"], theme } : null;
+    })
+    .filter(Boolean);
+  return {
+    name: "embed-labs",
+    title: "Embed Labs",
+    version: MCP_SERVER_VERSION,
+    description: "Embed Labs MCP service for local-first embedded development boards, board knowledge, toolchain metadata, Local Bridge hardware access, and account/device-bound service logging.",
+    websiteUrl: "https://embedboard.com/",
+    ...(icons.length > 0 ? { icons } : {})
+  };
+}
+
+const tools = [
+  {
+    name: "dbt_auth_status",
+    description: "Check whether the local Embed Labs CLI is signed in and bound to this computer. If not ready, return the exact login command and dashboard URL the user should use before any board/cloud tool call.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  {
+    name: "dbt_current_board_status",
+    description: "Get the latest local Embed Labs Bridge inventory snapshot for supported development boards, without server-side AI planning. Use this MCP tool directly for requests like 当前开发板状态, 开发板状态, board status, USB ECM, and SSH checks; it is not a shell command. Do not report optional control ports or unrelated local serial paths unless the user explicitly asks.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        reason: { type: "string" },
+        local_device_id: { type: "string" },
+        host: { type: "string" },
+        ports: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_initial_image_flash",
+    description: "Single high-level entrypoint for initialization-image flashing. Use this directly for requests like 刷写初始化镜像, 将泰山派1M RK3566的初始化镜像刷写到开发板, or RP2350/Pico initial firmware. The tool infers or accepts the board, validates installed SDK resources, calls Local Bridge flash plan/run, waits for completion when approved, and returns a compact user-facing result. Do not inspect plugin scripts, do not list tools, do not use dbt_board_debug, and do not print raw CLI help.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board_id: { type: "string", description: "Optional board/template id such as taishanpi-1m-rk3566, pico2w-rp2350-monitor, or coloreasypico2-rp2350-monitor." },
+        board: { type: "string" },
+        local_device_id: { type: "string" },
+        device_id: { type: "string" },
+        image_dir: { type: "string" },
+        artifact_path: { type: "string" },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" },
+        wait: { type: "boolean", description: "Defaults to true when approved=true." },
+        timeout_ms: { type: "number" },
+        include_raw: { type: "boolean" }
+      }
+    }
+  },
+  {
+    name: "dbt_rp2350_monitor_status",
+    description: "Read RP2350-Monitor status through Embed Labs Local Bridge on 18083, including board status, logic-analyzer caps, probe caps, pins, channels, and the browser UI URL. Report ui_url/browser_url for the web interface; bridge_url/monitor_bridge_url is the internal upstream and must not be opened as /rp2350-monitor/.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        transport: { type: "string" },
+        local_device_id: { type: "string" },
+        monitor_bridge_url: { type: "string" },
+        serial_path: { type: "string" },
+        host: { type: "string" },
+        port: { type: "number" },
+        include_caps: { type: "boolean" },
+        timeout_ms: { type: "number" },
+        monitor_root: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_rp2350_capabilities",
+    description: "Return the RP2350/Pico2 monitor capability catalog: supported operations, parameters, defaults, firmware commands, and preferred MCP tools. Call this before using unfamiliar RP2350 hardware protocols.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "dbt_rp2350_operation",
+    description: "Run a supported RP2350 Monitor /api/operation action through the shared Local Bridge. Prefer specific tools for GPIO/UART/I2C/SPI/Wi-Fi/probe; use this for advanced catalog actions.",
+    inputSchema: {
+      type: "object",
+      required: ["action"],
+      properties: {
+        local_device_id: { type: "string" },
+        monitor_bridge_url: { type: "string" },
+        action: { type: "string" },
+        params: { type: "object", additionalProperties: true },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" },
+        timeout_ms: { type: "number" }
+      }
+    }
+  },
+  {
+    name: "dbt_rp2350_gpio_read",
+    description: "Read one or more RP2350/Pico GPIO levels through the shared monitor bridge. This temporarily configures pins, so use approved=true after user approval.",
+    inputSchema: { type: "object", properties: { pins: { type: "array", items: { type: "number" } }, pull: { type: "string" }, approved: { type: "boolean" }, approve: { type: "boolean" }, local_device_id: { type: "string" }, timeout_ms: { type: "number" } } }
+  },
+  {
+    name: "dbt_rp2350_gpio_write",
+    description: "Drive an RP2350/Pico GPIO pin high or low through the shared monitor bridge. Requires approved=true.",
+    inputSchema: { type: "object", properties: { pin: { type: "number" }, gpio: { type: "number" }, id: { type: "number" }, level: { type: "boolean" }, approved: { type: "boolean" }, approve: { type: "boolean" }, local_device_id: { type: "string" }, timeout_ms: { type: "number" } } }
+  },
+  {
+    name: "dbt_rp2350_uart_write",
+    description: "Send text or HEX data over the current/default RP2350 UART channel, with optional tx/rx/baud override. Requires approved=true.",
+    inputSchema: { type: "object", properties: { id: { type: "number" }, instance: { type: "number" }, tx: { type: "number" }, rx: { type: "number" }, baud: { type: "number" }, text: { type: "string" }, hex: { type: "string" }, data_hex: { type: "string" }, line_ending: { type: "string" }, approved: { type: "boolean" }, approve: { type: "boolean" }, local_device_id: { type: "string" }, timeout_ms: { type: "number" } } }
+  },
+  {
+    name: "dbt_rp2350_i2c_transfer",
+    description: "Run RP2350 I2C write/read/write-read transaction with address, write payload, and read length. Requires approved=true.",
+    inputSchema: { type: "object", properties: { id: { type: "number" }, instance: { type: "number" }, sda: { type: "number" }, scl: { type: "number" }, baud: { type: "number" }, addr: { type: "string" }, address: { type: "string" }, write: { type: "string" }, write_hex: { type: "string" }, hex: { type: "string" }, read_len: { type: "number" }, approved: { type: "boolean" }, approve: { type: "boolean" }, local_device_id: { type: "string" }, timeout_ms: { type: "number" } } }
+  },
+  {
+    name: "dbt_rp2350_logic_capture",
+    description: "Capture a compact RP2350-Monitor logic-analyzer JSONL file from selected GPIO pins for AI-assisted data collection and later decode. Requires approved=true because it arms local hardware. Logic analyzer pins are configurable as a contiguous exposed GPIO range; use dbt_rp2350_capabilities/status and the user's wiring before choosing pin_base/pin_count.",
+    inputSchema: {
+      type: "object",
+      required: ["pin_base", "pin_count"],
+      properties: {
+        transport: { type: "string" },
+        local_device_id: { type: "string" },
+        monitor_bridge_url: { type: "string" },
+        serial_path: { type: "string" },
+        host: { type: "string" },
+        port: { type: "number" },
+        pin_base: { type: "number" },
+        pin_count: { type: "number" },
+        sample_rate: { type: "number" },
+        samples: { type: "number" },
+        output_path: { type: "string" },
+        pull: { type: "string" },
+        release: { type: "boolean" },
+        wait_timeout_ms: { type: "number" },
+        read_timeout_ms: { type: "number" },
+        pre_samples: { type: "number" },
+        post_samples: { type: "number" },
+        search_samples: { type: "number" },
+        burst_count: { type: "number" },
+        trigger_pin: { type: "number" },
+        trigger_mode: { type: "string" },
+        trigger_level: { type: "boolean" },
+        trigger_mask: { type: "number" },
+        trigger_value: { type: "number" },
+        channel_names: { type: "object", additionalProperties: { type: "string" } },
+        pin_pulls: { type: "object", additionalProperties: { type: "string" } },
+        stimulus: { type: "object", additionalProperties: true, description: "Optional closed-loop stimulus. For SPI, use action/protocol spi.transfer. If SPI pins are omitted, the bridge uses the documented SPI0 example SCK GP2, MOSI GP3, MISO GP0, CS GP1; this is only an example profile, not a global wiring rule." },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" },
+        timeout_ms: { type: "number" },
+        monitor_root: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_rp2350_logic_decode",
+    description: "Decode a local RP2350-Monitor logic JSONL capture without touching hardware. Supported decoders: summary, bursts, edges, spi, and structure/auto/unknown. The result includes summary_for_user, decoded_preview, protocol_data, and analysis so the AI can report actual sampled data; use structure/unknown when the protocol is not known.",
+    inputSchema: {
+      type: "object",
+      required: ["input_path"],
+      properties: {
+        local_device_id: { type: "string" },
+        input_path: { type: "string" },
+        decoder: { type: "string", description: "summary, bursts, edges, spi, structure, auto, or unknown." },
+        output_path: { type: "string" },
+        preview_limit: { type: "number" },
+        pins: { type: "array", items: { type: "number" } },
+        rx_pin: { type: "number" },
+        baud: { type: "number" },
+        sck_pin: { type: "number" },
+        mosi_pin: { type: "number" },
+        miso_pin: { type: "number" },
+        cs_pin: { type: "number" },
+        sda_pin: { type: "number" },
+        scl_pin: { type: "number" },
+        monitor_root: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_rp2350_spi_transfer",
+    description: "Send test bytes through a configurable RP2350 SPI channel via Embed Labs Local Bridge. Pin choices must match the firmware pin map for the selected SPI instance; if pins are omitted, the bridge uses the documented SPI0 example SCK GP2, MOSI GP3, MISO GP0, CS GP1. Use this directly for requests like 通过默认SPI接口发送测试数据; mutating bus output requires approve=true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        transport: { type: "string" },
+        local_device_id: { type: "string" },
+        monitor_bridge_url: { type: "string" },
+        serial_path: { type: "string" },
+        host: { type: "string" },
+        port: { type: "number" },
+        id: { type: "number" },
+        instance: { type: "number" },
+        sck: { type: "number", default: 2, description: "SPI SCK GPIO. Default is the documented SPI0 example GP2; other valid pins depend on the selected SPI instance." },
+        mosi: { type: "number", default: 3, description: "SPI MOSI/TX GPIO. Default is the documented SPI0 example GP3; other valid pins depend on the selected SPI instance." },
+        miso: { type: "number", default: 0, description: "SPI MISO/RX GPIO. Default is the documented SPI0 example GP0; other valid pins depend on the selected SPI instance." },
+        cs: { type: "number", default: 1, description: "Manual CS GPIO. Default is the documented SPI0 example GP1; it may be another free exposed GPIO that does not overlap SCK/MOSI/MISO." },
+        baud: { type: "number", default: 1000000 },
+        hex: { type: "string" },
+        data_hex: { type: "string" },
+        write_hex: { type: "string" },
+        read_len: { type: "number" },
+        use_current_channel: { type: "boolean", description: "Advanced: reuse active SPI channel from monitor snapshot instead of the documented SPI0 example pins." },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" },
+        timeout_ms: { type: "number" },
+        monitor_root: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_rp2350_wifi_manage",
+    description: "Manage RP2350 Monitor Wi-Fi actions: scan, save, save-connect, connect, clear, or AP mode. Requires approved=true because it can change board Wi-Fi state.",
+    inputSchema: { type: "object", properties: { action: { type: "string" }, wifi_action: { type: "string" }, slot: { type: "number" }, ssid: { type: "string" }, password: { type: "string" }, save: { type: "boolean" }, approved: { type: "boolean" }, approve: { type: "boolean" }, local_device_id: { type: "string" }, timeout_ms: { type: "number" } } }
+  },
+  {
+    name: "dbt_rp2350_probe_debug",
+    description: "Run RP2350 Monitor debug-probe actions: caps, status, config, release, reset, or raw DAP packet. Mutating actions require approved=true.",
+    inputSchema: { type: "object", required: ["action"], properties: { action: { type: "string" }, swclk: { type: "number" }, swdio: { type: "number" }, reset: { type: "number" }, swclk_khz: { type: "number" }, reset_action: { type: "string" }, pulse_ms: { type: "number" }, packet_hex: { type: "string" }, approved: { type: "boolean" }, approve: { type: "boolean" }, local_device_id: { type: "string" }, timeout_ms: { type: "number" } } }
+  },
+  {
+    name: "dbt_rp2350_monitor_command",
+    description: "Run an allowlisted RP2350-Monitor command through Embed Labs Local Bridge. Mutating commands require approve=true.",
+    inputSchema: {
+      type: "object",
+      required: ["command"],
+      properties: {
+        transport: { type: "string" },
+        local_device_id: { type: "string" },
+        monitor_bridge_url: { type: "string" },
+        serial_path: { type: "string" },
+        host: { type: "string" },
+        port: { type: "number" },
+        command: { type: "string" },
+        args: { type: "array", items: { type: "string" } },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" },
+        timeout_ms: { type: "number" },
+        monitor_root: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_cloud_status",
+    description: "Discover Embed Labs Cloud supported boards, knowledge file index, plugin/service metadata, and local toolchain download metadata. Server-side user workspaces, quota/billing tools, and Docker builds are disabled by default.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        template_id: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_board_knowledge_search",
+    description: "Search bounded Embed Labs server-side board knowledge snippets for pinout, UART/serial, GPIO, build, flash, SDK, and workflow questions. For supported boards, use this instead of web search; if no snippet matches, report the board-pack gap.",
+    inputSchema: {
+      type: "object",
+      required: ["query"],
+      properties: {
+        template_id: { type: "string" },
+        query: { type: "string" },
+        source: { type: "string", enum: ["board_pack", "build_template", "registry"] },
+        limit: { type: "number" }
+      }
+    }
+  },
+  {
+    name: "dbt_supported_boards",
+    description: "List currently supported Embed Labs development boards across Cloud board registry and local toolchain environments. Use this directly for 当前支持哪些开发板 / supported boards questions.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  {
+    name: "dbt_task_status",
+    description: "Read an Embed Labs Cloud task status, including output_tail and artifact metadata.",
+    inputSchema: {
+      type: "object",
+      required: ["task_id"],
+      properties: {
+        task_id: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_task_log_download",
+    description: "Download the first log artifact from a Cloud task.",
+    inputSchema: {
+      type: "object",
+      required: ["task_id"],
+      properties: {
+        task_id: { type: "string" },
+        output_path: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_artifact_download",
+    description: "Download an Embed Labs Cloud artifact.",
+    inputSchema: {
+      type: "object",
+      required: ["artifact_id", "output_path"],
+      properties: {
+        artifact_id: { type: "string" },
+        output_path: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_board_debug",
+    description: "Run managed-model local-board debug/deploy planning through Cloud API plus Local Bridge. Source edits and compilation stay in the user's local environment. Do not use this for initialization image flashing; use dbt_initial_image_flash instead.",
+    inputSchema: {
+      type: "object",
+      required: ["prompt"],
+      properties: {
+        account_id: { type: "string" },
+        workspace_id: { type: "string" },
+        prompt: { type: "string" },
+        provider: { type: "string" },
+        model: { type: "string" },
+        host: { type: "string" },
+        ports: { type: "string" },
+        artifact_path: { type: "string" },
+        artifact_id: { type: "string" },
+        artifact_task_id: { type: "string" },
+        artifact_output: { type: "string" },
+        remote_path: { type: "string" },
+        run_command: { type: "string" },
+        approve: { type: "boolean" },
+        run: { type: "boolean" }
+      }
+    }
+  },
+  {
+    name: "dbt_boot_logo_update",
+    description: "Single high-level local boot-logo action. Use this directly for 启动logo修改/刷写启动Logo/logo替换. Pass only the image path and optional approval; the tool validates the local SDK, converts/resizes the image locally, repacks the local Rockchip resource image, patches the local boot.img, and returns a compact result. Do not call dbt_update_logo and dbt_compose_boot_logo manually unless this tool reports a product gap.",
+    inputSchema: {
+      type: "object",
+      required: ["logo_path"],
+      properties: {
+        logo_path: { type: "string" },
+        logo: { type: "string" },
+        kernel_logo_path: { type: "string" },
+        board_id: { type: "string" },
+        board: { type: "string" },
+        variant_id: { type: "string" },
+        variant: { type: "string" },
+        output_dir: { type: "string" },
+        package_path: { type: "string" },
+        base_image_path: { type: "string" },
+        output_image_path: { type: "string" },
+        manifest_path: { type: "string" },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" },
+        force: { type: "boolean" },
+        auto_repair: { type: "boolean" },
+        include_raw: { type: "boolean" }
+      }
+    }
+  },
+  {
+    name: "dbt_update_logo",
+    description: "Ask the server to generate a small free boot-logo package for later local image merge and approved flashing. This does not allocate a paid server workspace.",
+    inputSchema: {
+      type: "object",
+      required: ["logo_path"],
+      properties: {
+        account_id: { type: "string" },
+        account: { type: "string" },
+        project_id: { type: "string" },
+        project: { type: "string" },
+        board_id: { type: "string" },
+        board: { type: "string" },
+        variant_id: { type: "string" },
+        variant: { type: "string" },
+        logo_path: { type: "string" },
+        kernel_logo_path: { type: "string" },
+        output_path: { type: "string" },
+        output: { type: "string" },
+        rotate: { type: "string" },
+        scale: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_compose_boot_logo",
+    description: "Compose a downloaded server boot-logo package with a local base image using the cross-platform Embed CLI local composer. The result reports whether it is ready for approved flashing.",
+    inputSchema: {
+      type: "object",
+      required: ["package_path", "base_image_path", "output_path"],
+      properties: {
+        package_path: { type: "string" },
+        package: { type: "string" },
+        base_image_path: { type: "string" },
+        base_image: { type: "string" },
+        output_path: { type: "string" },
+        output: { type: "string" },
+        manifest_path: { type: "string" },
+        manifest: { type: "string" },
+        force: { type: "boolean" }
+      }
+    }
+  },
+  {
+    name: "dbt_local_toolchain_list",
+    description: "List supported local development-board environments for this host. Summarize board names, installed/available/update status, package groups, and the recommended install command in plain language.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board_id: { type: "string" },
+        board: { type: "string" },
+        channel: { type: "string" },
+        metadata_root: { type: "string" },
+        metadataRoot: { type: "string" },
+        install_root: { type: "string" },
+        installRoot: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_local_toolchain_installed",
+    description: "Show only development-board environments already installed on this computer, including the release root and installed mode. Use this when the user asks what board packages or SDKs are currently installed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board_id: { type: "string" },
+        board: { type: "string" },
+        channel: { type: "string" },
+        metadata_root: { type: "string" },
+        metadataRoot: { type: "string" },
+        install_root: { type: "string" },
+        installRoot: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_local_toolchain_latest",
+    description: "Show the latest available local development-board environment package metadata for this host and board.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board_id: { type: "string" },
+        board: { type: "string" },
+        channel: { type: "string" },
+        metadata_root: { type: "string" },
+        metadataRoot: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_local_toolchain_current",
+    description: "Show the currently selected local development-board environment in the Embed Labs CLI registry.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        install_root: { type: "string" },
+        installRoot: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_local_toolchain_install",
+    description: "Download, install, or repair a local development-board environment, such as TaishanPi LLVM/Qt support or Pico2W/RP2350 Monitor runtime support. If validation reports missing components for the user's requested workflow, call this with the matching board_id and mode to overlay the missing packages.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board_id: { type: "string" },
+        board: { type: "string" },
+        channel: { type: "string" },
+        metadata_root: { type: "string" },
+        metadataRoot: { type: "string" },
+        source_url: { type: "string" },
+        sourceUrl: { type: "string" },
+        source_release_root: { type: "string" },
+        sourceReleaseRoot: { type: "string" },
+        install_root: { type: "string" },
+        installRoot: { type: "string" },
+        mode: { type: "string", enum: ["minimal", "runtime", "compile", "qt", "firmware", "full", "images"] },
+        force: { type: "boolean" }
+      }
+    }
+  },
+  {
+    name: "dbt_local_toolchain_uninstall",
+    description: "Uninstall a selected local development-board SDK/tool package from this computer and remove its CLI registry entry. Use this when the user asks to remove, uninstall, or clean up a board environment.",
+    inputSchema: {
+      type: "object",
+      required: ["board_id"],
+      properties: {
+        board_id: { type: "string" },
+        board: { type: "string" },
+        install_root: { type: "string" },
+        installRoot: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_local_toolchain_validate",
+    description: "Validate a local development-board environment release, such as TaishanPi LLVM/Qt support or Pico2W/RP2350 Monitor runtime support. The response includes missing_groups, summary_for_user, and repair_command; for TaishanPi Qt development, an ok=false result should be repaired with dbt_local_toolchain_install mode=qt before one-click cross compile or deploy.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        release_root: { type: "string" },
+        releaseRoot: { type: "string" },
+        board_id: { type: "string" },
+        board: { type: "string" },
+        mode: { type: "string", enum: ["minimal", "runtime", "compile", "qt", "firmware", "full", "images"] }
+      }
+    }
+  },
+  {
+    name: "dbt_taishanpi_initial_image_flash",
+    description: "Install/repair the TaishanPi 1M-RK3566 images SDK, resolve images/current automatically, plan initialization image flashing through Embed Labs Local Bridge, and optionally run it when approved=true. Use this directly for TaishanPi requests like 烧写初始化镜像, 刷写1M RK3566初始化镜像, Loader/Maskrom 初始化镜像刷写. Do not use dbt_board_debug for this flow and do not ask the user to provide image_dir when the SDK is installed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board_id: { type: "string", description: "Defaults to taishanpi-1m-rk3566 for SDK install and taishanpi for flash." },
+        board: { type: "string" },
+        local_device_id: { type: "string" },
+        device_id: { type: "string" },
+        image_dir: { type: "string" },
+        install_root: { type: "string" },
+        installRoot: { type: "string" },
+        channel: { type: "string" },
+        metadata_root: { type: "string" },
+        metadataRoot: { type: "string" },
+        force: { type: "boolean" },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" }
+      }
+    }
+  },
+  {
+    name: "dbt_rp2350_monitor_firmware_flash",
+    description: "Download/install the optional RP2350 Monitor firmware package, locate rp2350_monitor.uf2, plan UF2 flashing through Embed Labs Local Bridge, and optionally flash it when approved=true. Use this only when the user explicitly asks for RP2350 Monitor, logic-analyzer, hardware-control, or Monitor firmware. For 初始化镜像/initial firmware requests use dbt_rp2350_initial_firmware_flash instead. Initialized boards use the Local Bridge inventory and picotool runtime handoff when available.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board_id: { type: "string", description: "pico2w-rp2350-monitor or coloreasypico2-rp2350-monitor. Defaults to pico2w-rp2350-monitor." },
+        board: { type: "string" },
+        install_root: { type: "string" },
+        installRoot: { type: "string" },
+        channel: { type: "string" },
+        metadata_root: { type: "string" },
+        metadataRoot: { type: "string" },
+        artifact_path: { type: "string", description: "Optional UF2 path. If omitted, the tool installs firmware mode and uses toolkit-runtime/rp2350-monitor/firmware/rp2350_monitor.uf2." },
+        artifact: { type: "string" },
+        force: { type: "boolean" },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" }
+      }
+    }
+  },
+  {
+    name: "dbt_rp2350_initial_firmware_flash",
+    description: "Download/install the RP2350 board initialization firmware package, locate the board-specific initial.uf2, plan UF2 flashing through Embed Labs Local Bridge, and optionally flash it when approved=true. Use this directly for user requests like 烧写初始化镜像, 刷初始化镜像, initial firmware, or initialization UF2. Do not ask the user to choose Monitor vs initial firmware for those requests. If Local Bridge inventory already shows an initialized RP2350 runtime, the flash plan should use the picotool runtime handoff after approval.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board_id: { type: "string", description: "pico2w-rp2350-monitor or coloreasypico2-rp2350-monitor. Defaults to pico2w-rp2350-monitor." },
+        board: { type: "string" },
+        install_root: { type: "string" },
+        installRoot: { type: "string" },
+        channel: { type: "string" },
+        metadata_root: { type: "string" },
+        metadataRoot: { type: "string" },
+        artifact_path: { type: "string", description: "Optional UF2 path. If omitted, the tool installs firmware mode and uses rp2350-initial-firmware/<board>/initial.uf2." },
+        artifact: { type: "string" },
+        force: { type: "boolean" },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" }
+      }
+    }
+  },
+  {
+    name: "dbt_plugin_update_check",
+    description: "Check the published Embed Labs Codex/OpenCode plugin release and report whether the local plugins should be updated.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        release_url: { type: "string" },
+        releaseUrl: { type: "string" },
+        target: { type: "string" },
+        codex_target: { type: "string" },
+        codexTarget: { type: "string" },
+        opencode_target: { type: "string" },
+        opencodeTarget: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_plugin_update",
+    description: "Update the local Embed Labs Codex/OpenCode plugin installation from the published release. Restart Codex/OpenCode after this finishes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target_plugin: { type: "string", enum: ["codex", "opencode", "all"] },
+        plugin: { type: "string", enum: ["codex", "opencode", "all"] },
+        release_url: { type: "string" },
+        releaseUrl: { type: "string" },
+        target: { type: "string" },
+        codex_target: { type: "string" },
+        codexTarget: { type: "string" },
+        opencode_target: { type: "string" },
+        opencodeTarget: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_local_compile",
+    description: "Compile a local TaishanPi source file with the local Embed Labs LLVM toolchain. The user must be signed in with an Embed Labs token for account attribution.",
+    inputSchema: {
+      type: "object",
+      required: ["source_path", "output_path"],
+      properties: {
+        account_id: { type: "string" },
+        source_path: { type: "string" },
+        output_path: { type: "string" },
+        release_root: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_local_qt_smoke",
+    description: "Build a local TaishanPi Qt/CMake application with the local Embed Labs LLVM/Qt toolchain. Defaults to the built-in smoke app, but for real demos pass source_path and target_name. Use official board-pack examples such as taishanpi/examples/modbus-loop-demo instead of ad hoc projects. The user must be signed in with an Embed Labs token for account attribution.",
+    inputSchema: {
+      type: "object",
+      required: ["build_dir"],
+      properties: {
+        account_id: { type: "string" },
+        source_path: { type: "string" },
+        build_dir: { type: "string" },
+        target_name: { type: "string" },
+        release_root: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "dbt_taishanpi_qt_app_workflow",
+    description: "Single high-level TaishanPi Qt application workflow. Use this directly for Qt/QtQuick app development, Modbus/UART demos, cross compilation, deployment, and runtime checks. The tool validates/repairs the Qt SDK, selects a board-pack template when source_path is omitted, builds with the local LLVM/Qt toolchain, and can deploy/run after approval. Do not search scripts, print CLI help, or create ad hoc serial backends.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        request: { type: "string" },
+        source_path: { type: "string" },
+        project_dir: { type: "string" },
+        build_dir: { type: "string" },
+        target_name: { type: "string" },
+        local_device_id: { type: "string" },
+        host: { type: "string" },
+        remote_path: { type: "string" },
+        deploy: { type: "boolean" },
+        run: { type: "boolean" },
+        approve: { type: "boolean" },
+        approved: { type: "boolean" },
+        include_raw: { type: "boolean" }
+      }
+    }
+  },
+  {
+    name: "dbttool",
+    description: "Dispatcher for supported-boards, status, RP2350 hardware tools, debug, high-level boot-logo-update, TaishanPi Qt workflow, local toolchain install/validate, local-compile, task-status, task-log-download, or artifact-download. Server workspace and Docker build actions are disabled in the local-first product model.",
+    inputSchema: {
+      type: "object",
+      required: ["action"],
+      properties: {
+        action: { type: "string" },
+        request: { type: "string" },
+        arguments_json: { type: "string" }
+      }
+    }
+  }
+];
+
+function asString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function asCliValue(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return asString(value);
+}
+
+function boolValue(value) {
+  return value === true || ["1", "true", "yes", "on"].includes(asString(value).toLowerCase());
+}
+
+function compactObject(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined && item !== ""));
+}
+
+function objectValue(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value;
+  const text = asString(value);
+  if (!text) return undefined;
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+  } catch {
+    // Fall through to key=value parsing for compact CLI-oriented prompts.
+  }
+  const entries = text
+    .split(/[,\s]+/g)
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map((item) => item.split("=", 2))
+    .filter((item) => item.length === 2 && item[0]);
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+function unwrapRp2350Snapshot(value) {
+  const root = objectValue(value) || {};
+  return objectValue(root.snapshot) || root;
+}
+
+function resolveEmbedCommand() {
+  if (process.env.EMBED_CLI_BIN) {
+    const cliBin = process.env.EMBED_CLI_BIN;
+    if (cliBin.endsWith(".js") || cliBin.endsWith(".mjs") || cliBin.endsWith(".cjs")) {
+      return { file: process.execPath, args: [cliBin] };
+    }
+    return { file: cliBin, args: [] };
+  }
+  const localDist = path.join(REPO_ROOT, "packages", "cli", "dist", "index.js");
+  if (existsSync(localDist)) return { file: process.execPath, args: [localDist] };
+  return { file: "embedlabs", args: [] };
+}
+
+function ensureJson(args) {
+  return args.includes("--json") ? args : args.concat("--json");
+}
+
+function pushOptional(args, name, value) {
+  const text = asCliValue(value);
+  if (text) args.push(`--${name}`, text);
+}
+
+async function runEmbed(args) {
+  const command = resolveEmbedCommand();
+  const fullArgs = command.args.concat(ensureJson(args));
+  return await new Promise((resolve, reject) => {
+    const child = spawn(command.file, fullArgs, {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      const output = stdout.trim();
+      const parsed = parseEmbedJson(output);
+      if (code !== 0) {
+        reject(new Error(JSON.stringify(summarizeEmbedFailure(code, parsed, stderr), null, 2)));
+        return;
+      }
+      resolve({ ok: true, response: parsed });
+    });
+  });
+}
+
+async function runProcess(command, args, options = {}) {
+  return await new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: asString(options.cwd) || process.cwd(),
+      env: options.env || process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      resolve({ code: 127, stdout, stderr: stderr || error.message, error });
+    });
+    child.on("close", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+  });
+}
+
+function parseEmbedJson(output) {
+  if (!output) {
+    return { ok: false, error: { code: "empty_cli_output", message: "Embed Labs CLI returned an empty response." } };
+  }
+  try {
+    return JSON.parse(output);
+  } catch {
+    return { ok: false, error: { code: "non_json_cli_output", message: "Embed Labs CLI returned non-JSON output." } };
+  }
+}
+
+function summarizeEmbedFailure(exitCode, parsed, stderr) {
+  const body = parsed && typeof parsed === "object" ? parsed : {};
+  const error = body.error && typeof body.error === "object" ? body.error : {};
+  const message = asString(error.message) || asString(error.code) || summarizePublicText(stderr) || "Embed Labs CLI command failed.";
+  const code = asString(error.code) || "embed_cli_failed";
+  const summarizedError = {
+    code,
+    message: message.slice(0, 500)
+  };
+  const remediation = asString(error.remediation);
+  if (remediation && isAuthSetupError(code)) {
+    summarizedError.remediation = remediation.slice(0, 1200);
+    summarizedError.details = authSetupDetails(error.details);
+  }
+  return {
+    ok: false,
+    exit_code: exitCode,
+    error: summarizedError,
+    stderr_summary: summarizePublicText(stderr)
+  };
+}
+
+function isAuthSetupError(code) {
+  return code === "auth_token_missing"
+    || code === "auth_token_rejected"
+    || code === "auth_not_ready"
+    || code === "tool_integrity_check_failed"
+    || code === "device_signature_required";
+}
+
+function authSetupDetails(details) {
+  if (!details || typeof details !== "object" || Array.isArray(details)) return undefined;
+  const allowed = {};
+  for (const key of ["dashboard_url", "login_command", "env_var", "auth_status_command", "device_status_command", "auth_file"]) {
+    const value = details[key];
+    if (typeof value === "string" && value.trim()) {
+      allowed[key] = value.slice(0, 500);
+    }
+  }
+  return Object.keys(allowed).length ? allowed : undefined;
+}
+
+function summarizePublicText(value) {
+  const text = asString(value).trim();
+  if (!text) return undefined;
+  return text
+    .replace(/(sk-[A-Za-z0-9_-]{8,})/g, "[redacted]")
+    .replace(/(npm_[A-Za-z0-9_-]{8,})/g, "[redacted]")
+    .replace(/(re_[A-Za-z0-9_-]{8,})/g, "[redacted]")
+    .slice(0, 500);
+}
+
+function responseData(response) {
+  const body = response?.response ?? response;
+  if (body && typeof body === "object" && "data" in body) return body.data;
+  return body;
+}
+
+async function pluginAuthStatus() {
+  let response;
+  try {
+    response = await runEmbed(["auth", "status"]);
+  } catch (error) {
+    return authNotReadyResult({
+      authenticated: false,
+      source_error: error instanceof Error ? error.message : String(error)
+    });
+  }
+  const status = responseData(response) || {};
+  if (status.authenticated === true && status.device_id && status.device_integrity === "ok") {
+    return {
+      ok: true,
+      authenticated: true,
+      device_ready: true,
+      profile: status.profile,
+      source: status.source,
+      account_id: status.account_id,
+      api_key_id: status.api_key_id,
+      device_id: status.device_id,
+      device_integrity: status.device_integrity,
+      message: "Embed Labs token and device binding are ready."
+    };
+  }
+  return authNotReadyResult(status);
+}
+
+function formatCurrencyCents(value, currency = "USD") {
+  const amount = Number(value);
+  if (!Number.isFinite(amount)) return undefined;
+  return `${currency || "USD"} ${(amount / 100).toFixed(2)}`;
+}
+
+function authNotReadyResult(status) {
+  const authenticated = status?.authenticated === true;
+  const integrity = asString(status?.device_integrity) || (status?.device_id ? "unknown" : "unbound");
+  const code = !authenticated ? "auth_token_missing" : integrity === "failed" ? "tool_integrity_check_failed" : "auth_not_ready";
+  const message = code === "tool_integrity_check_failed"
+    ? TOOL_INTEGRITY_RELOGIN_MESSAGE
+    : !authenticated
+      ? "Embed Labs API Token is not configured for this plugin."
+      : "Embed Labs API Token 已配置，但还没有完成本机设备绑定。";
+  return {
+    ok: false,
+    error: {
+      code,
+      message,
+      remediation: [
+        "1. Open https://api.embedboard.com/dashboard and sign in or register.",
+        "2. Create or copy your Embed Labs API Token.",
+        "3. Update the local CLI, then run: embedlabs auth login --token <your_token>",
+        "4. Verify device binding with: embedlabs auth device status",
+        "5. Restart Codex/OpenCode so the plugin picks up the refreshed CLI and auth file."
+      ].join("\n"),
+      details: {
+        dashboard_url: "https://api.embedboard.com/dashboard",
+        login_command: "embedlabs auth login --token <your_token>",
+        auth_status_command: "embedlabs auth status",
+        device_status_command: "embedlabs auth device status",
+        auth_file: ".embed-labs/auth.json",
+        current_status: {
+          authenticated,
+          source: status?.source,
+          profile: status?.profile,
+          device_id: status?.device_id,
+          device_integrity: integrity
+        }
+      }
+    }
+  };
+}
+
+function pickArtifact(response, preferredKind) {
+  const data = responseData(response);
+  const artifacts = Array.isArray(data?.artifacts) ? data.artifacts : [];
+  const candidates = artifacts.filter((item) => !["manifest", "log", "evidence", "report"].includes(String(item.kind || "")));
+  return (
+    candidates.find((item) => item.kind === preferredKind) ||
+    candidates.find((item) => /\.sh$|\.img$|\.bin$|\.zip$/i.test(String(item.name || ""))) ||
+    candidates[0] ||
+    artifacts[0] ||
+    null
+  );
+}
+
+async function cloudStatus(args) {
+  const template = asString(args.template_id || args.template);
+  const [modelDefault, serviceModes] = await Promise.all([
+    runEmbed(["model", "default"]),
+    runEmbed(["service", "modes"])
+  ]);
+  if (!template) {
+    const boards = await supportedBoards(args);
+    return {
+      model_default: modelDefault,
+      service_modes: serviceModes,
+      ...boards,
+      selected_template_id: null,
+      board_methods: undefined,
+      note: "No template_id was supplied, so this response lists supported boards only. Board methods are template-specific; call dbt_cloud_status with template_id for one selected board."
+    };
+  }
+  const [board, methods, knowledge] = await Promise.all([
+    runEmbed(["board", "registry", "show", template]),
+    runEmbed(["board", "methods", template]),
+    runEmbed(["board", "knowledge", template])
+  ]);
+  return { model_default: modelDefault, service_modes: serviceModes, board, methods, knowledge };
+}
+
+async function boardKnowledgeSearch(args) {
+  const template = asString(args.template_id || args.template) || DEFAULT_TEMPLATE_ID;
+  const query = asString(args.query || args.q || args.prompt);
+  if (!query) {
+    throw new Error("query is required");
+  }
+  const command = ["board", "knowledge", "search", template, "--query", query];
+  pushOptional(command, "source", args.source);
+  pushOptional(command, "limit", args.limit);
+  return await runEmbed(command);
+}
+
+async function supportedBoards() {
+  const [registrySettled, localSettled] = await Promise.allSettled([
+    runEmbed(["board", "registry", "list"]),
+    runEmbed(["local", "toolchain", "list"])
+  ]);
+  const registry = settledRunValue(registrySettled);
+  const local = settledRunValue(localSettled);
+  const profiles = Array.isArray(responseData(registry)?.profiles) ? responseData(registry).profiles : [];
+  const environments = Array.isArray(responseData(local)?.environments) ? responseData(local).environments : [];
+  const localByBoard = new Map(environments.map((item) => [asString(item.board_id), item]));
+  const supported = profiles.map((profile) => {
+    const localEnv = localByBoard.get(asString(profile.template_id));
+    const methods = Array.isArray(profile.methods) ? profile.methods : [];
+    const runtimes = [...new Set(methods.map((method) => asString(method.runtime)).filter(Boolean))];
+    return compactObject({
+      template_id: profile.template_id,
+      board_id: profile.board_id,
+      variant_id: profile.variant_id,
+      display_name: normalizeSupportedBoardDisplayName(profile.display_name || profile.variant_id || profile.template_id),
+      support_level: profile.support_level,
+      cloud_method_count: methods.length,
+      cloud_method_runtimes: runtimes,
+      local_toolchain_status: localEnv?.status,
+      local_install_modes: Array.isArray(localEnv?.install_modes) ? localEnv.install_modes : undefined,
+      local_installed: localEnv?.installed,
+      local_installed_version: localEnv?.installed?.version,
+      server_latest_version: localEnv?.latest?.version,
+      local_install_command: localEnv?.install_command,
+      local_update_command: localEnv?.update_command,
+      local_uninstall_command: localEnv ? `embedlabs local toolchain uninstall --board ${profile.template_id}` : undefined
+    });
+  });
+  for (const env of environments) {
+    const boardId = asString(env.board_id);
+    if (!boardId || supported.some((item) => item.template_id === boardId)) continue;
+    supported.push(compactObject({
+      template_id: boardId,
+      board_id: boardId,
+      display_name: normalizeSupportedBoardDisplayName(env.display_name || boardId),
+      support_level: "local_toolchain",
+      cloud_method_count: 0,
+      cloud_method_runtimes: [],
+      local_toolchain_status: env.status,
+      local_install_modes: Array.isArray(env.install_modes) ? env.install_modes : undefined,
+      local_installed: env.installed,
+      local_installed_version: env.installed?.version,
+      server_latest_version: env.latest?.version,
+      local_install_command: env.install_command,
+      local_update_command: env.update_command,
+      local_uninstall_command: `embedlabs local toolchain uninstall --board ${boardId}`
+    }));
+  }
+  supported.sort((a, b) => asString(a.display_name).localeCompare(asString(b.display_name)));
+  const table = supported.map((item) => ({
+    board: item.display_name,
+    template_id: item.template_id,
+    support_level: item.support_level,
+    install_status: item.local_toolchain_status || "unknown",
+    local_version: item.local_installed_version || "not installed",
+    server_version: item.server_latest_version || "unknown",
+    modes: Array.isArray(item.local_install_modes) ? item.local_install_modes.join(",") : "",
+    install: item.local_install_command,
+    update: item.local_update_command,
+    uninstall: item.local_uninstall_command
+  }));
+  return {
+    supported_boards: supported,
+    table,
+    cloud_registry: {
+      available: !!registry,
+      count: profiles.length,
+      error: settledRunError(registrySettled)
+    },
+    local_toolchains: {
+      available: !!local,
+      count: environments.length,
+      error: settledRunError(localSettled)
+    },
+    guidance: "When the user asks which boards are supported, show the table fields as a Markdown table. Use install/update/uninstall commands through dbt_local_toolchain_install and dbt_local_toolchain_uninstall rather than shell rm.",
+    observed_at: new Date().toISOString()
+  };
+}
+
+function settledRunValue(result) {
+  return result.status === "fulfilled" ? result.value : undefined;
+}
+
+function settledRunError(result) {
+  if (result.status !== "rejected") return undefined;
+  return compactEmbedError(result.reason);
+}
+
+function compactEmbedError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  try {
+    const parsed = JSON.parse(message);
+    return parsed?.response?.error || parsed?.error || { message: redactSensitive(message) };
+  } catch {
+    return { message: redactSensitive(message) };
+  }
+}
+
+function redactSensitive(value) {
+  return asString(value)
+    .replace(/(sk-[A-Za-z0-9_-]{8,})/g, "[redacted]")
+    .replace(/(npm_[A-Za-z0-9_-]{8,})/g, "[redacted]")
+    .replace(/(re_[A-Za-z0-9_-]{8,})/g, "[redacted]")
+    .slice(0, 500);
+}
+
+function normalizeSupportedBoardDisplayName(value) {
+  const text = asString(value);
+  if (!text) return "";
+  if (/^TaishanPi 1M RK3566 server build template$/i.test(text)) return "TaishanPi 1M-RK3566";
+  return text;
+}
+
+async function boardDebug(args) {
+  const prompt = asString(args.prompt || args.request || args.reason) || "验证开发板状态";
+  const command = ["agent", "run", "--prompt", prompt];
+  pushOptional(command, "account", args.account_id || args.account);
+  pushOptional(command, "workspace", args.workspace_id || args.workspace);
+  pushOptional(command, "provider", args.provider);
+  pushOptional(command, "model", args.model);
+  pushOptional(command, "host", args.host || DEFAULT_HOST);
+  pushOptional(command, "ports", args.ports || DEFAULT_PORTS);
+  pushOptional(command, "artifact", args.artifact_path || args.artifact);
+  pushOptional(command, "artifact-id", args.artifact_id);
+  pushOptional(command, "artifact-task", args.artifact_task_id || args.task_id);
+  pushOptional(command, "artifact-output", args.artifact_output);
+  pushOptional(command, "remote-path", args.remote_path);
+  pushOptional(command, "run-command", args.run_command || args.runCommand);
+  if (boolValue(args.approve)) command.push("--approve");
+  if (boolValue(args.run)) command.push("--run");
+  return await runEmbed(command);
+}
+
+async function currentBoardStatus(args, authStatus = undefined) {
+ const startedAt = Date.now();
+ const explicitHost = asString(args.host);
+ const ports = parsePorts(args.ports || DEFAULT_STATUS_PORTS);
+  const requestedLocalDeviceId = localDeviceIdForTool(args, authStatus);
+  const scan = await runEmbed(["device", "list"]);
+  const taishanHost = taishanStatusHostFromScan(scan);
+  const host = explicitHost || taishanHost;
+  const probe = host
+    ? await runEmbed(["tool", "call", "device.probe", "--input-json", JSON.stringify({ host, ports })])
+    : emptyBoardStatusProbe();
+  const summary = summarizeBoardStatus(scan, probe, ports);
+  const localDeviceId = requestedLocalDeviceId || (summary.local_device_ids?.length === 1 ? summary.local_device_ids[0] : "");
+  if (authStatus?.ok) {
+    summary.device_binding = {
+      authenticated: true,
+      account_id: authStatus.account_id,
+      api_key_id: authStatus.api_key_id,
+      device_id: authStatus.device_id,
+      device_integrity: authStatus.device_integrity
+    };
+  }
+  if (localDeviceId) {
+    summary.local_device_id = localDeviceId;
+  }
+  const logResult = await recordMcpToolEvent("dbt_current_board_status", {
+    client: "codex",
+    mode: "local_ai",
+    server_model_used: false,
+    success: summary.query_ok === true,
+    duration_ms: Date.now() - startedAt,
+    local_device_id: localDeviceId,
+    input_summary: host ? `host=${host} ports=${ports.join(",")}` : "inventory_only",
+    output_summary: summary.status_text
+  });
+  summary.usage.mcp_service_log = logResult;
+  return summary;
+}
+
+function taishanStatusHostFromScan(scanResult) {
+  const scan = responseData(scanResult) || {};
+  const devices = Array.isArray(scan.development_boards) ? scan.development_boards : (Array.isArray(scan.devices) ? scan.devices : []);
+  const taishan = devices.find((item) => item?.board_id === "taishanpi" || String(item?.device_id || "").includes("taishanpi"));
+  if (!taishan) return "";
+  const locatorHost = Array.isArray(taishan.locators)
+    ? taishan.locators.map((locator) => asString(locator.host)).find(Boolean)
+    : "";
+  return asString(taishan.host || taishan.link_local?.host || locatorHost);
+}
+
+function emptyBoardStatusProbe() {
+  return {
+    ok: true,
+    response: {
+      ok: true,
+      data: {
+        result: {
+          tcp: [],
+          observed_at: new Date().toISOString()
+        }
+      }
+    }
+  };
+}
+
+async function rp2350MonitorTool(toolName, capabilityId, args) {
+  const startedAt = Date.now();
+  const input = normalizeRp2350Input(args);
+  const requestedLocalDeviceId = asString(input.local_device_id || input.localDeviceId);
+  if (requestedLocalDeviceId) input.local_device_id = requestedLocalDeviceId;
+  delete input.localDeviceId;
+  delete input.approve;
+  delete input.approved;
+  const command = ["tool", "call", capabilityId, "--input-json", JSON.stringify(input)];
+  if (boolValue(args.approve) || boolValue(args.approved)) command.push("--approve");
+  const response = await runEmbed(command);
+  const data = responseData(response);
+  const localDeviceId = requestedLocalDeviceId || inferLocalDeviceIdFromToolResponse(data);
+  const summary = data?.result?.summary_for_user || data?.summary_for_user || `${capabilityId} completed.`;
+  const logResult = await recordMcpToolEvent(toolName, {
+    client: "codex",
+    mode: "local_ai",
+    server_model_used: false,
+    success: response?.response?.ok === true,
+    duration_ms: Date.now() - startedAt,
+    local_device_id: localDeviceId,
+    input_summary: `${capabilityId} ${JSON.stringify(input).slice(0, 180)}`,
+    output_summary: asString(summary).slice(0, 240)
+  });
+  return { ...response, usage: { mode: "local_ai_mcp_tool", server_model_used: false, input_tokens: 0, output_tokens: 0, local_device_id: localDeviceId || undefined, mcp_service_log: logResult } };
+}
+
+function normalizeRp2350Input(args) {
+  const input = compactObject({ ...args });
+  for (const key of [
+    "port", "baud", "timeout_ms", "pin_base", "pin_count", "sample_rate", "samples",
+    "wait_timeout_ms", "read_timeout_ms", "pre_samples", "post_samples", "search_samples",
+    "burst_count", "trigger_pin", "trigger_mask", "trigger_value", "capture_id",
+    "start_sample", "end_sample", "preview_limit", "rx_pin", "data_bits", "sck_pin", "mosi_pin",
+    "miso_pin", "cs_pin", "mode", "word_bits", "sda_pin", "scl_pin",
+    "id", "instance", "sck", "mosi", "miso", "cs", "read_len", "tx", "rx",
+    "sda", "scl", "pin", "gpio", "slot", "swclk", "swdio", "reset",
+    "swclk_khz", "pulse_ms"
+  ]) {
+    const value = input[key];
+    if (typeof value === "string" && value.trim() && Number.isFinite(Number(value))) {
+      input[key] = Number(value);
+    }
+  }
+  for (const key of ["include_caps", "release", "trigger_level", "invert", "cs_active_high", "level", "save", "use_current_channel"]) {
+    if (typeof input[key] === "string") {
+      input[key] = boolValue(input[key]);
+    }
+  }
+  if (typeof input.pins === "string") {
+    input.pins = input.pins.split(/[,\s]+/g).map((item) => Number(item)).filter((item) => Number.isFinite(item));
+  }
+  for (const key of ["channel_names", "pin_pulls", "stimulus", "params"]) {
+    const parsed = objectValue(input[key]);
+    if (parsed) input[key] = parsed;
+    else delete input[key];
+  }
+  return input;
+}
+
+async function rp2350MonitorStatus(args) {
+  return await rp2350MonitorTool("dbt_rp2350_monitor_status", "rp2350.monitor.status", args);
+}
+
+async function rp2350Capabilities(args) {
+  return await rp2350MonitorTool("dbt_rp2350_capabilities", "rp2350.monitor.capabilities", args);
+}
+
+async function rp2350Operation(args) {
+  return await rp2350MonitorTool("dbt_rp2350_operation", "rp2350.monitor.operation", args);
+}
+
+async function rp2350GpioRead(args) {
+  return await rp2350MonitorTool("dbt_rp2350_gpio_read", "rp2350.monitor.gpio.read", args);
+}
+
+async function rp2350GpioWrite(args) {
+  return await rp2350MonitorTool("dbt_rp2350_gpio_write", "rp2350.monitor.gpio.write", args);
+}
+
+async function rp2350UartWrite(args) {
+  return await rp2350MonitorTool("dbt_rp2350_uart_write", "rp2350.monitor.uart.write", args);
+}
+
+async function rp2350I2cTransfer(args) {
+  return await rp2350MonitorTool("dbt_rp2350_i2c_transfer", "rp2350.monitor.i2c.transfer", args);
+}
+
+async function rp2350LogicCapture(args) {
+  return await rp2350MonitorTool("dbt_rp2350_logic_capture", "rp2350.monitor.logic.capture", args);
+}
+
+async function rp2350LogicDecode(args) {
+  return await rp2350MonitorTool("dbt_rp2350_logic_decode", "rp2350.monitor.logic.decode", args);
+}
+
+async function rp2350SpiTransfer(args) {
+  return await rp2350MonitorTool("dbt_rp2350_spi_transfer", "rp2350.monitor.spi.transfer", args);
+}
+
+async function rp2350WifiManage(args) {
+  return await rp2350MonitorTool("dbt_rp2350_wifi_manage", "rp2350.monitor.wifi.manage", args);
+}
+
+async function rp2350ProbeDebug(args) {
+  return await rp2350MonitorTool("dbt_rp2350_probe_debug", "rp2350.monitor.probe.debug", args);
+}
+
+async function rp2350MonitorCommand(args) {
+  return await rp2350MonitorTool("dbt_rp2350_monitor_command", "rp2350.monitor.command", args);
+}
+
+function parsePorts(value) {
+  const text = asString(value) || DEFAULT_PORTS;
+  const ports = text
+    .split(/[,\s]+/g)
+    .map((item) => Number.parseInt(item, 10))
+    .filter((item) => Number.isInteger(item) && item > 0 && item <= 65535);
+  return ports.length > 0 ? ports : DEFAULT_PORTS.split(",").map((item) => Number.parseInt(item, 10));
+}
+
+async function recordMcpToolEvent(toolName, details) {
+  try {
+    const requestId = `mcp_${toolName}_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+    const command = [
+      "mcp", "log",
+      "--tool", toolName,
+      "--client", details.client || "codex",
+      "--mode", details.mode || "local_ai",
+      "--server-model-used", details.server_model_used ? "true" : "false",
+      "--success", details.success ? "true" : "false",
+      "--request-id", requestId
+    ];
+    if (Number.isFinite(details.duration_ms)) command.push("--duration-ms", String(Math.max(0, Math.round(details.duration_ms))));
+    if (asString(details.local_device_id)) command.push("--local-device-id", asString(details.local_device_id));
+    if (asString(details.input_summary)) command.push("--input-summary", asString(details.input_summary));
+    if (asString(details.output_summary)) command.push("--output-summary", asString(details.output_summary));
+    const response = await runEmbed(command);
+    return { recorded: response?.response?.ok === true, event_id: response?.response?.data?.event_id };
+  } catch (error) {
+    return compactMcpLogError(error);
+  }
+}
+
+function compactMcpLogError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  try {
+    const parsed = JSON.parse(message);
+    const cloudError = parsed?.stdout?.error || parsed?.response?.error || parsed?.error;
+    if (cloudError?.code) {
+      return {
+        recorded: false,
+        error_code: cloudError.code,
+        message: cloudError.message || "MCP service log was not recorded."
+      };
+    }
+  } catch {
+    // Fall through to a concise text message.
+  }
+  return { recorded: false, message: message.slice(0, 240) };
+}
+
+function localDeviceIdForTool(args) {
+  return asString(args.local_device_id || args.localDeviceId);
+}
+
+function inferLocalDeviceIdFromToolResponse(data) {
+  const result = data?.result || data || {};
+  const existing = asString(result.local_device_id || result.device_id);
+  if (existing) return existing;
+  const bridgeUrl = asString(result.bridge_url);
+  if (bridgeUrl) return stableLocalDeviceId("rp2350-monitor", bridgeUrl);
+  const host = asString(result.host);
+  if (host) return stableLocalDeviceId("taishanpi", host);
+  return "";
+}
+
+function stableLocalDeviceId(kind, locator) {
+  const hash = createHash("sha256").update(`${kind}:${locator}`).digest("hex").slice(0, 12);
+  return `${kind}_${hash}`;
+}
+
+function summarizeBoardStatus(scanResult, probeResult, requestedPorts = []) {
+  const scan = responseData(scanResult) || {};
+  const probeEnvelope = responseData(probeResult) || {};
+  const probe = probeEnvelope.result || probeEnvelope || {};
+  const devices = Array.isArray(scan.development_boards) ? scan.development_boards : (Array.isArray(scan.devices) ? scan.devices : []);
+  const bridgeBoardStatus = objectValue(scan.board_status) || {};
+  const visiblePorts = new Set((Array.isArray(requestedPorts) ? requestedPorts : []).map((port) => Number(port)).filter((port) => Number.isFinite(port)));
+  const boardLocalDeviceIds = devices
+    .map((item) => asString(item.local_device_id || item.device_id))
+    .filter(Boolean);
+  const boards = devices
+    .map((item) => summarizeBoardDevice(item, visiblePorts));
+  const tcp = (Array.isArray(probe.tcp) ? probe.tcp : []).map((item) => ({
+    host: item.host,
+    port: item.port,
+    reachable: item.reachable,
+    duration_ms: item.duration_ms
+  }));
+  const result = {
+    board_connected: boards.some((item) => item.connected === true || item.status === "connected"),
+    boards,
+    local_device_ids: boardLocalDeviceIds,
+    tcp_ports: tcp,
+    status_text: asString(bridgeBoardStatus.status_text) || (boards.length > 0
+      ? boards.map((board) => `${board.display_name || board.board_id || "Board"} is ${board.status || "detected"}${board.host ? ` at ${board.host}` : ""}.`).join(" ")
+      : "No supported board was detected in the local scan."),
+    bridge_board_status: bridgeBoardStatus,
+    usage: {
+      mode: "local_ai_mcp_tool",
+      server_model_used: false,
+      input_tokens: 0,
+      output_tokens: 0
+    },
+    observed_at: probe.observed_at || scan.observed_at,
+    raw_result_omitted: true,
+    model_answer_omitted: true
+  };
+  Object.defineProperty(result, "query_ok", {
+    value: scanResult?.ok === true && scanResult?.response?.ok === true && probeResult?.ok === true && probeResult?.response?.ok === true,
+    enumerable: false
+  });
+  return result;
+}
+
+function summarizeBoardDevice(item, visiblePorts) {
+  const isRp2350 = isRp2350Device(item);
+  const monitor = isRp2350 ? rp2350MonitorSummary(item) : undefined;
+  const displayName = isRp2350
+    ? `${rp2350BoardDisplayName(item) || item.display_name || item.name || "RP2350"}${monitor?.running ? " (Monitor)" : ""}`
+    : item.display_name || item.name || item.variant_id;
+  const host = isRp2350 ? asString(item.host || item.link_local?.host) : item.host || item.link_local?.host || item.bridge_url;
+  return {
+    device_id: item.device_id,
+    local_device_id: item.local_device_id,
+    board_id: item.board_id,
+    display_name: displayName,
+    status: item.status || (item.connected === true ? "connected" : item.reachable === true ? "reachable" : "detected"),
+    connected: item.connected === true || item.status === "connected",
+    host: host || undefined,
+    ui_url: isRp2350 ? asString(item.ui_url || item.browser_url) || undefined : undefined,
+    browser_url: isRp2350 ? asString(item.browser_url || item.ui_url) || undefined : undefined,
+    public_bridge_url: isRp2350 ? asString(item.public_bridge_url) || undefined : undefined,
+    reachable: item.reachable,
+    link_local: item.link_local,
+    locators: isRp2350 ? filteredRp2350Locators(item.locators) : item.locators,
+    monitor,
+    tcp: Array.isArray(item.tcp) ? item.tcp
+      .filter((entry) => visiblePorts.size === 0 || visiblePorts.has(Number(entry.port)))
+      .map((entry) => ({
+        host: entry.host,
+        port: entry.port,
+        reachable: entry.reachable,
+        error: entry.error
+      })) : undefined,
+    identity: item.identity ? {
+      attempted: item.identity.attempted,
+      exit_code: item.identity.exit_code,
+      stdout: item.identity.stdout,
+      timed_out: item.identity.timed_out,
+      board: isRp2350 ? rp2350BoardDisplayName(item) : undefined
+    } : undefined,
+    summary_for_user: item.summary_for_user
+  };
+}
+
+function isRp2350Device(item) {
+  const boardId = asString(item?.board_id).toLowerCase();
+  const kind = asString(item?.kind).toLowerCase();
+  const id = asString(item?.local_device_id || item?.device_id).toLowerCase();
+  return boardId === "rp2350" || boardId.includes("rp2350") || kind.includes("rp2350") || id.includes("rp2350");
+}
+
+function rp2350BoardDisplayName(item) {
+  const identity = objectValue(item?.identity) || {};
+  const monitorDevice = objectValue(identity.monitor_device) || {};
+  const details = objectValue(item?.details) || {};
+  const snapshot = unwrapRp2350Snapshot(details.snapshot);
+  const snapshotDevice = objectValue(snapshot.device) || {};
+  for (const value of [
+    item?.board_display_name,
+    item?.variant_id,
+    item?.board_model,
+    monitorDevice.board,
+    snapshotDevice.board,
+    item?.board,
+    item?.display_name,
+    item?.name
+  ]) {
+    const normalized = normalizeRp2350BoardName(value);
+    if (normalized) return normalized;
+  }
+  return "";
+}
+
+function normalizeRp2350BoardName(value) {
+  const text = asString(value);
+  if (!text) return "";
+  const compact = text.toLowerCase().replace(/[\s_/-]+/g, "");
+  if (compact.includes("coloreasypico2") || compact.includes("colorpico2")) return "ColorEasyPICO2";
+  if (compact.includes("pico2w") || compact.includes("pico2wireless")) return "Pico 2 W";
+  if (compact === "rp2350" || compact === "rp2350monitor") return "";
+  return text;
+}
+
+function rp2350MonitorSummary(item) {
+  const identity = objectValue(item?.identity) || {};
+  const monitorDevice = objectValue(identity.monitor_device) || {};
+  const details = objectValue(item?.details) || {};
+  const snapshot = unwrapRp2350Snapshot(details.snapshot);
+  const snapshotDevice = objectValue(snapshot.device) || {};
+  const running = item?.monitor_running === true || item?.monitor_status === "running";
+  return compactObject({
+    running,
+    status: item?.monitor_status || (running ? "running" : "not_running"),
+    feature_state: item?.feature_state,
+    ui_url: asString(item?.ui_url || item?.browser_url),
+    browser_url: asString(item?.browser_url || item?.ui_url),
+    public_bridge_url: asString(item?.public_bridge_url),
+    upstream_url: asString(item?.upstream_url || item?.monitor_bridge_url || item?.bridge_url),
+    firmware: monitorDevice.firmware || snapshotDevice.firmware,
+    transport: monitorDevice.transport || snapshotDevice.transport
+  });
+}
+
+function filteredRp2350Locators(locators) {
+  if (!Array.isArray(locators)) return undefined;
+  const filtered = locators.filter((locator) => asString(locator?.transport) !== "rp2350-monitor");
+  return filtered.length > 0 ? filtered : undefined;
+}
+
+async function updateLogo(args) {
+  const logoPath = asString(args.logo_path || args.logo);
+  if (!logoPath) throw new Error("logo_path is required");
+  const command = ["build", "image", "boot-logo", "--logo", logoPath];
+  pushOptional(command, "account", args.account_id || args.account);
+  pushOptional(command, "project", args.project_id || args.project);
+  pushOptional(command, "board", args.board_id || args.board || "taishanpi");
+  pushOptional(command, "variant", args.variant_id || args.variant);
+  pushOptional(command, "kernel-logo", args.kernel_logo_path || args.kernel_logo);
+  pushOptional(command, "output", args.output_path || args.output);
+  pushOptional(command, "rotate", args.rotate);
+  pushOptional(command, "scale", args.scale);
+  return await runEmbed(command);
+}
+
+async function composeBootLogo(args) {
+  const packagePath = asString(args.package_path || args.package);
+  const baseImagePath = asString(args.base_image_path || args.base_image);
+  const outputPath = asString(args.output_path || args.output);
+  if (!packagePath) throw new Error("package_path is required");
+  if (!baseImagePath) throw new Error("base_image_path is required");
+  if (!outputPath) throw new Error("output_path is required");
+  const command = [
+    "image",
+    "boot-logo",
+    "compose",
+    "--package",
+    packagePath,
+    "--base-image",
+    baseImagePath,
+    "--output",
+    outputPath
+  ];
+  pushOptional(command, "manifest", args.manifest_path || args.manifest);
+  if (boolValue(args.force)) command.push("--force");
+  return await runEmbed(command);
+}
+
+function defaultActionDir(kind, explicitDir) {
+  const outputDir = asString(explicitDir) || path.join(process.cwd(), ".embed-labs", kind, `${kind}_${Date.now()}`);
+  mkdirSync(outputDir, { recursive: true });
+  return outputDir;
+}
+
+function firstExistingPath(candidates) {
+  return candidates.map(asString).find((candidate) => candidate && existsSync(candidate)) || "";
+}
+
+async function ensureLocalToolchain(args, boardId, mode) {
+  const sdkCheck = await localToolchainValidate({
+    board_id: boardId,
+    mode,
+    release_root: args.release_root || args.releaseRoot
+  });
+  const checkData = responseData(sdkCheck) || {};
+  if (checkData.ok) {
+    return { sdkCheck, sdkInstall: null, releaseRoot: asString(checkData.release_root) };
+  }
+  const sdkInstall = await localToolchainInstall({
+    board_id: boardId,
+    channel: args.channel,
+    metadata_root: args.metadata_root || args.metadataRoot,
+    install_root: args.install_root || args.installRoot,
+    mode,
+    force: args.force
+  });
+  const installData = responseData(sdkInstall) || {};
+  return { sdkCheck, sdkInstall, releaseRoot: asString(installData.release_root) };
+}
+
+function bootLogoBaseImageCandidates(args, releaseRoot) {
+  return [
+    args.base_image_path || args.base_image,
+    releaseRoot ? path.join(releaseRoot, "boot-workspace", "out", "resource.img") : "",
+    releaseRoot ? path.join(releaseRoot, "boot-workspace", "out", "boot.img") : "",
+    releaseRoot ? path.join(releaseRoot, "images", "current", "boot.img") : ""
+  ].map(asString).filter(Boolean);
+}
+
+function fileSha256Sync(filePath) {
+  return createHash("sha256").update(readFileSync(filePath)).digest("hex");
+}
+
+function expectedBaseShaFromPackage(packagePath) {
+  try {
+    const payload = JSON.parse(readFileSync(packagePath, "utf8"));
+    return asString(payload?.local_merge?.base_image?.sha256).toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function resolveBootLogoBaseImage(args, releaseRoot, packagePath) {
+  const candidates = bootLogoBaseImageCandidates(args, releaseRoot).filter((candidate) => existsSync(candidate));
+  const expectedSha = expectedBaseShaFromPackage(packagePath);
+  if (expectedSha) {
+    const matched = candidates.find((candidate) => fileSha256Sync(candidate) === expectedSha);
+    if (matched) return matched;
+    return "";
+  }
+  return candidates[0] || "";
+}
+
+function compactBootLogoCompose(composeResult) {
+  const data = responseData(composeResult) || {};
+  return compactObject({
+    ready_for_flash: data.ready_for_flash,
+    replacement_applied: data.replacement_applied,
+    operation_kind: data.operation_kind,
+    output_path: data.output_path || data.output,
+    manifest_path: data.manifest_path || data.manifest,
+    local_merge_strategy: data.local_merge_strategy,
+    requires_board_specific_patcher: data.requires_board_specific_patcher,
+    summary_for_user: data.summary_for_user,
+    warnings: compactWarnings(data.warnings)
+  });
+}
+
+function executableExists(filePath) {
+  try {
+    return statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function resolveExecutableFromPath(names) {
+  const pathEntries = asString(process.env.PATH).split(path.delimiter).filter(Boolean);
+  const extensions = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
+  for (const name of names) {
+    if (path.isAbsolute(name) && executableExists(name)) return name;
+    for (const dir of pathEntries) {
+      for (const ext of extensions) {
+        const candidate = path.join(dir, `${name}${ext}`);
+        if (executableExists(candidate)) return candidate;
+      }
+    }
+  }
+  return "";
+}
+
+function resourceToolPath(releaseRoot) {
+  const platformDirs = process.platform === "darwin"
+    ? ["mac", "darwin"]
+    : process.platform === "win32"
+      ? ["windows", "win"]
+      : ["linux"];
+  const names = process.platform === "win32" ? ["resource_tool.exe", "resource_tool"] : ["resource_tool"];
+  const candidates = [];
+  for (const dir of platformDirs) {
+    for (const name of names) {
+      candidates.push(path.join(releaseRoot, "tools", dir, name));
+    }
+  }
+  for (const name of names) {
+    candidates.push(path.join(releaseRoot, "tools", name));
+  }
+  return firstExistingPath(candidates);
+}
+
+function readBmpDimensions(filePath) {
+  const bytes = readFileSync(filePath);
+  if (bytes.length < 54 || bytes.toString("ascii", 0, 2) !== "BM") {
+    throw new Error(`Not a Windows BMP file: ${filePath}`);
+  }
+  return {
+    width: Math.abs(bytes.readInt32LE(18)),
+    height: Math.abs(bytes.readInt32LE(22)),
+    bits_per_pixel: bytes.readUInt16LE(28)
+  };
+}
+
+function normalizeBmpTopDown(filePath) {
+  const bytes = Buffer.from(readFileSync(filePath));
+  if (bytes.length < 54 || bytes.toString("ascii", 0, 2) !== "BM") return;
+  const width = bytes.readInt32LE(18);
+  const height = bytes.readInt32LE(22);
+  const bitsPerPixel = bytes.readUInt16LE(28);
+  if (height <= 0 || width <= 0 || bitsPerPixel <= 0) return;
+  const pixelOffset = bytes.readUInt32LE(10);
+  const rowSize = Math.floor((bitsPerPixel * width + 31) / 32) * 4;
+  const pixelBytes = rowSize * height;
+  if (pixelOffset + pixelBytes > bytes.length) return;
+  const original = Buffer.from(bytes.subarray(pixelOffset, pixelOffset + pixelBytes));
+  for (let row = 0; row < height; row += 1) {
+    const sourceStart = (height - row - 1) * rowSize;
+    original.copy(bytes, pixelOffset + row * rowSize, sourceStart, sourceStart + rowSize);
+  }
+  bytes.writeInt32LE(-height, 22);
+  writeFileSync(filePath, bytes);
+}
+
+async function convertImageToBootBmp(inputPath, outputPath, width, height) {
+  const magick = resolveExecutableFromPath(["magick"]);
+  if (magick) {
+    const result = await runProcess(magick, [
+      inputPath,
+      "-auto-orient",
+      "-resize", `${width}x${height}^`,
+      "-gravity", "center",
+      "-extent", `${width}x${height}`,
+      "-type", "TrueColor",
+      "-depth", "8",
+      `BMP3:${outputPath}`
+    ]);
+    if (result.code === 0) {
+      normalizeBmpTopDown(outputPath);
+      return { converter: "magick", output_path: outputPath };
+    }
+  }
+  const convert = resolveExecutableFromPath(["convert"]);
+  if (convert) {
+    const result = await runProcess(convert, [
+      inputPath,
+      "-auto-orient",
+      "-resize", `${width}x${height}^`,
+      "-gravity", "center",
+      "-extent", `${width}x${height}`,
+      "-type", "TrueColor",
+      "-depth", "8",
+      `BMP3:${outputPath}`
+    ]);
+    if (result.code === 0) {
+      normalizeBmpTopDown(outputPath);
+      return { converter: "convert", output_path: outputPath };
+    }
+  }
+  const sips = resolveExecutableFromPath(["sips"]);
+  if (sips) {
+    const result = await runProcess(sips, [
+      "-s", "format", "bmp",
+      "-z", String(height), String(width),
+      inputPath,
+      "--out", outputPath
+    ]);
+    if (result.code === 0) {
+      normalizeBmpTopDown(outputPath);
+      return { converter: "sips", output_path: outputPath };
+    }
+  }
+  const ffmpeg = resolveExecutableFromPath(["ffmpeg"]);
+  if (ffmpeg) {
+    const result = await runProcess(ffmpeg, [
+      "-y",
+      "-i", inputPath,
+      "-vf", `scale=${width}:${height}:force_original_aspect_ratio=increase,crop=${width}:${height}`,
+      outputPath
+    ]);
+    if (result.code === 0) {
+      normalizeBmpTopDown(outputPath);
+      return { converter: "ffmpeg", output_path: outputPath };
+    }
+  }
+  throw new Error("No local image converter was found. Install ImageMagick, or use the SDK image converter package once published.");
+}
+
+function readFdtTotalsize(bytes) {
+  if (bytes.length < 8 || bytes.readUInt32BE(0) !== 0xd00dfeed) return 0;
+  const totalSize = bytes.readUInt32BE(4);
+  return totalSize > 0 && totalSize <= bytes.length ? totalSize : 0;
+}
+
+function findUniqueSubBufferOffset(haystack, needle) {
+  let found = -1;
+  let searchFrom = 0;
+  while (searchFrom < haystack.length) {
+    const index = haystack.indexOf(needle, searchFrom);
+    if (index < 0) break;
+    if (found >= 0) return -1;
+    found = index;
+    searchFrom = index + 1;
+  }
+  return found;
+}
+
+async function readFitIntegerProperty(imagePath, nodePath, property, workDir) {
+  const fdtget = resolveExecutableFromPath(["fdtget"]);
+  if (!fdtget) return undefined;
+  const result = await runProcess(fdtget, ["-ti", imagePath, nodePath, property], { cwd: workDir });
+  if (result.code !== 0) return undefined;
+  const value = Number.parseInt(result.stdout.trim(), 10);
+  return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+async function readFitExternalDataInfo(imagePath, nodeName, workDir) {
+  const nodePath = `/images/${nodeName}`;
+  const offset = await readFitIntegerProperty(imagePath, nodePath, "data-position", workDir);
+  const size = await readFitIntegerProperty(imagePath, nodePath, "data-size", workDir);
+  if (offset === undefined || size === undefined) return undefined;
+  return { offset, size };
+}
+
+function sha256Buffer(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function writeJsonFile(filePath, payload) {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+async function localBootLogoCompose(args, sdk, logoPath, outputDir, outputImagePath, manifestPath) {
+  const releaseRoot = sdk.releaseRoot;
+  const toolPath = resourceToolPath(releaseRoot);
+  if (!toolPath) {
+    return {
+      ok: false,
+      error: {
+        code: "resource_tool_missing",
+        message: "本机 SDK 缺少 Rockchip resource_tool，无法在本地重打包启动 Logo 镜像。"
+      }
+    };
+  }
+
+  const baseBootImage = firstExistingPath([
+    args.base_image_path || args.base_image,
+    path.join(releaseRoot, "images", "current", "boot.img"),
+    path.join(releaseRoot, "boot-workspace", "out", "boot.img")
+  ]);
+  if (!baseBootImage) {
+    return {
+      ok: false,
+      error: {
+        code: "base_boot_image_missing",
+        message: "本机 SDK 中没有找到基础 boot.img，无法生成新的启动 Logo 镜像。"
+      }
+    };
+  }
+
+  const baseBootBytes = readFileSync(baseBootImage);
+  const headerSize = readFdtTotalsize(baseBootBytes);
+  if (!headerSize) {
+    return {
+      ok: false,
+      error: {
+        code: "unsupported_boot_image_format",
+        message: "当前 boot.img 不是可直接本地补丁的 FIT 镜像格式。"
+      }
+    };
+  }
+  const fitResource = await readFitExternalDataInfo(baseBootImage, "resource", outputDir);
+  if (!fitResource || fitResource.offset + fitResource.size > baseBootBytes.length) {
+    return {
+      ok: false,
+      error: {
+        code: "fit_resource_not_found",
+        message: "无法从 boot.img 中定位 Rockchip resource 数据段。请确认 SDK 包包含 fdtget 或等效 FIT 工具。"
+      }
+    };
+  }
+
+  const workDir = path.join(outputDir, "local-work");
+  rmSync(workDir, { recursive: true, force: true });
+  mkdirSync(workDir, { recursive: true });
+  const baseResourcePath = path.join(workDir, "base-resource.img");
+  const patchedResourcePath = asString(args.output_resource_path || args.outputResource)
+    || path.join(outputDir, "boot-logo-resource.img");
+  writeFileSync(baseResourcePath, baseBootBytes.subarray(fitResource.offset, fitResource.offset + fitResource.size));
+
+  const unpackResult = await runProcess(toolPath, ["--unpack", `--image=${baseResourcePath}`], { cwd: workDir });
+  if (unpackResult.code !== 0) {
+    return {
+      ok: false,
+      error: {
+        code: "resource_unpack_failed",
+        message: summarizePublicText(unpackResult.stderr || unpackResult.stdout) || "resource_tool unpack failed."
+      }
+    };
+  }
+  const unpackDir = path.join(workDir, "out");
+  const logoBmpPath = path.join(unpackDir, "logo.bmp");
+  const kernelLogoBmpPath = path.join(unpackDir, "logo_kernel.bmp");
+  const dimensions = readBmpDimensions(logoBmpPath);
+  const convertedLogoPath = path.join(outputDir, "logo.bmp");
+  const convertedKernelLogoPath = path.join(outputDir, "logo_kernel.bmp");
+  const converter = await convertImageToBootBmp(logoPath, convertedLogoPath, dimensions.width, dimensions.height);
+  const kernelLogoSource = asString(args.kernel_logo_path || args.kernel_logo) || logoPath;
+  const kernelConverter = await convertImageToBootBmp(kernelLogoSource, convertedKernelLogoPath, dimensions.width, dimensions.height);
+  copyFileSync(convertedLogoPath, logoBmpPath);
+  copyFileSync(convertedKernelLogoPath, kernelLogoBmpPath);
+
+  mkdirSync(path.dirname(patchedResourcePath), { recursive: true });
+  const packResult = await runProcess(toolPath, [
+    "--pack",
+    `--image=${patchedResourcePath}`,
+    "rk-kernel.dtb",
+    "logo.bmp",
+    "logo_kernel.bmp"
+  ], { cwd: unpackDir });
+  if (packResult.code !== 0) {
+    return {
+      ok: false,
+      error: {
+        code: "resource_pack_failed",
+        message: summarizePublicText(packResult.stderr || packResult.stdout) || "resource_tool pack failed."
+      }
+    };
+  }
+
+  let patchedResourceBytes = readFileSync(patchedResourcePath);
+  if (patchedResourceBytes.length > fitResource.size) {
+    const extra = patchedResourceBytes.subarray(fitResource.size);
+    if (extra.every((byte) => byte === 0)) {
+      patchedResourceBytes = patchedResourceBytes.subarray(0, fitResource.size);
+      writeFileSync(patchedResourcePath, patchedResourceBytes);
+    }
+  }
+  if (patchedResourceBytes.length < fitResource.size) {
+    const padded = Buffer.alloc(fitResource.size);
+    patchedResourceBytes.copy(padded, 0);
+    patchedResourceBytes = padded;
+    writeFileSync(patchedResourcePath, patchedResourceBytes);
+  }
+  if (patchedResourceBytes.length !== fitResource.size) {
+    return {
+      ok: false,
+      error: {
+        code: "resource_size_mismatch",
+        message: `重打包后的 resource.img 大小为 ${patchedResourceBytes.length} 字节，但 boot.img 资源槽大小为 ${fitResource.size} 字节。`
+      }
+    };
+  }
+
+  const baseResourceBytes = baseBootBytes.subarray(fitResource.offset, fitResource.offset + fitResource.size);
+  const baseResourceHash = Buffer.from(sha256Buffer(baseResourceBytes), "hex");
+  const patchedResourceHash = Buffer.from(sha256Buffer(patchedResourceBytes), "hex");
+  const hashOffset = findUniqueSubBufferOffset(baseBootBytes.subarray(0, headerSize), baseResourceHash);
+  if (hashOffset < 0) {
+    return {
+      ok: false,
+      error: {
+        code: "fit_resource_hash_not_found",
+        message: "无法在 boot.img FIT 头中唯一定位 resource 哈希，已停止生成，避免输出不可刷写镜像。"
+      }
+    };
+  }
+
+  const outputBootBytes = Buffer.from(baseBootBytes);
+  patchedResourceHash.copy(outputBootBytes, hashOffset);
+  patchedResourceBytes.copy(outputBootBytes, fitResource.offset);
+  mkdirSync(path.dirname(outputImagePath), { recursive: true });
+  writeFileSync(outputImagePath, outputBootBytes);
+  const manifest = {
+    schema_version: "1.0",
+    operation_kind: "image.boot_logo.local_compose",
+    board_id: "taishanpi-1m-rk3566",
+    logo_path: logoPath,
+    kernel_logo_path: kernelLogoSource,
+    base_boot_image: baseBootImage,
+    output_boot_image: outputImagePath,
+    output_resource_image: patchedResourcePath,
+    dimensions,
+    fit_resource: fitResource,
+    fit_resource_hash_offset: hashOffset,
+    base_boot_sha256: sha256Buffer(baseBootBytes),
+    output_boot_sha256: sha256Buffer(outputBootBytes),
+    base_resource_sha256: sha256Buffer(baseResourceBytes),
+    output_resource_sha256: sha256Buffer(patchedResourceBytes),
+    converter: converter.converter,
+    kernel_converter: kernelConverter.converter,
+    cross_platform: true,
+    platform: process.platform,
+    arch: process.arch,
+    observed_at: new Date().toISOString()
+  };
+  writeJsonFile(manifestPath, manifest);
+  return {
+    ok: true,
+    ready_for_flash: true,
+    local_merge_strategy: "local_resource_repack_and_fit_patch",
+    output_image_path: outputImagePath,
+    output_resource_path: patchedResourcePath,
+    manifest_path: manifestPath,
+    base_image_path: baseBootImage,
+    summary_for_user: "启动 Logo 已在本机完成图片转换、resource.img 重打包和 boot.img 补丁生成。",
+    manifest
+  };
+}
+
+async function bootLogoUpdate(args) {
+  const logoPath = asString(args.logo_path || args.logo);
+  if (!logoPath) throw new Error("logo_path is required");
+  if (!existsSync(logoPath)) {
+    return {
+      ok: false,
+      action: "boot_logo_update",
+      error: {
+        code: "logo_not_found",
+        message: `Logo image does not exist: ${logoPath}`
+      }
+    };
+  }
+
+  const boardId = asString(args.board_id || args.board) || "taishanpi-1m-rk3566";
+  const outputDir = defaultActionDir("boot-logo", args.output_dir || args.outputDir);
+  const outputImagePath = asString(args.output_image_path || args.outputImage || args.output)
+    || path.join(outputDir, "boot-logo-boot.img");
+  const manifestPath = asString(args.manifest_path || args.manifest) || path.join(outputDir, "boot-logo-compose-manifest.json");
+  const sdk = await ensureLocalToolchain(args, boardId, "images");
+  if (!sdk.releaseRoot) {
+    return {
+      ok: false,
+      action: "boot_logo_update",
+      error: {
+        code: "local_sdk_missing",
+        message: "本机没有可用的 TaishanPi images SDK，无法本地生成启动 Logo 镜像。"
+      },
+      sdk: compactSdkState(sdk.sdkCheck, sdk.sdkInstall)
+    };
+  }
+  const composeSummary = await localBootLogoCompose(args, sdk, logoPath, outputDir, outputImagePath, manifestPath);
+  if (!composeSummary.ok) {
+    return {
+      ok: false,
+      action: "boot_logo_update",
+      error: composeSummary.error,
+      sdk: compactSdkState(sdk.sdkCheck, sdk.sdkInstall),
+      output_dir: outputDir
+    };
+  }
+  const approved = boolValue(args.approved) || boolValue(args.approve);
+  const readyForFlash = composeSummary.ready_for_flash === true;
+  const result = {
+    ok: readyForFlash,
+    action: "boot_logo_update",
+    board: "TaishanPi 1M RK3566",
+    status: readyForFlash ? (approved ? "composed_ready_for_flash" : "ready_for_approval") : "composed_not_flashable",
+    approved,
+    summary_for_user: readyForFlash
+      ? "启动 Logo 已在本机完成格式转换、resource.img 重打包和 boot.img 镜像生成。需要真实写入开发板时，应继续走受控的本地刷写入口。"
+      : "启动 Logo 本地生成未完成，不能直接作为刷写产物。",
+    sdk: compactSdkState(sdk.sdkCheck, sdk.sdkInstall),
+    artifacts: compactObject({
+      logo_path: logoPath,
+      base_image_path: composeSummary.base_image_path,
+      output_image_path: outputImagePath,
+      output_resource_path: composeSummary.output_resource_path,
+      manifest_path: manifestPath
+    }),
+    compose: composeSummary,
+    next_step: readyForFlash
+      ? "如果用户明确批准写入开发板，后续应由同一高层工具调用 Local Bridge 的受控 boot 分区刷写能力，不能让模型手动拼命令。"
+      : "需要修复本地 SDK 图像转换或 resource 重打包工具后再刷写。",
+    raw_omitted: boolValue(args.include_raw) ? undefined : true
+  };
+  if (boolValue(args.include_raw)) {
+    result.raw = compactObject({ compose_result: composeSummary });
+  }
+  return result;
+}
+
+function shellQuote(value) {
+  const text = asString(value);
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
+function defaultQtExampleForRequest(request) {
+  const text = asString(request).toLowerCase();
+  if (text.includes("modbus") || text.includes("uart") || text.includes("串口") || text.includes("协议")) {
+    const relative = path.join("board-packs", "taishanpi", "examples", "modbus-loop-demo", "taishanpi");
+    return {
+      sourcePath: firstExistingPath([path.join(process.cwd(), relative), path.join(REPO_ROOT, relative)]),
+      targetName: "modbus_loop_demo",
+      template: "taishanpi_modbus_loop_demo"
+    };
+  }
+  return {
+    sourcePath: "",
+    targetName: "qt_smoke",
+    template: "qt_smoke"
+  };
+}
+
+function qtRuntimeCommand(remotePath) {
+  const remote = shellQuote(remotePath);
+  return [
+    "export QT_ROOT=/userdata/rootfs/qt6-rk3566-llvm",
+    "export LD_LIBRARY_PATH=$QT_ROOT/lib:$LD_LIBRARY_PATH",
+    "export QT_PLUGIN_PATH=$QT_ROOT/plugins",
+    "export QT_QPA_PLATFORM_PLUGIN_PATH=$QT_ROOT/plugins/platforms",
+    "export QML2_IMPORT_PATH=$QT_ROOT/qml",
+    "export QML_IMPORT_PATH=$QT_ROOT/qml",
+    "export QT_QUICK_CONTROLS_STYLE=Basic",
+    `chmod +x ${remote}`,
+    remote
+  ].join(" && ");
+}
+
+function artifactPathFromBuild(buildResult) {
+  const data = responseData(buildResult) || {};
+  return asString(data.artifact_path || data.artifactPath || data.output_path || data.executable_path);
+}
+
+function taishanpiHostFromDeviceList(scanResult) {
+  const data = responseData(scanResult) || {};
+  const devices = Array.isArray(data.development_boards) ? data.development_boards : [];
+  for (const device of devices) {
+    if (device?.board_id !== "taishanpi") continue;
+    const host = asString(device.host || device.link_local?.host);
+    if (host && device.status !== "bootloader") return host;
+  }
+  return "";
+}
+
+async function taishanpiQtAppWorkflow(args) {
+  const request = asString(args.request || args.prompt);
+  const boardId = "taishanpi-1m-rk3566";
+  const selected = defaultQtExampleForRequest(request);
+  const outputDir = defaultActionDir("qt-app", args.output_dir || args.outputDir);
+  const explicitSource = asString(args.source_path || args.source);
+  let sourcePath = explicitSource || selected.sourcePath;
+  const projectDir = asString(args.project_dir || args.projectDir);
+  if (!explicitSource && projectDir && selected.sourcePath) {
+    mkdirSync(path.dirname(projectDir), { recursive: true });
+    cpSync(selected.sourcePath, projectDir, { recursive: true, force: true });
+    sourcePath = projectDir;
+  }
+  if (!sourcePath && selected.template !== "qt_smoke") {
+    return {
+      ok: false,
+      action: "taishanpi_qt_app_workflow",
+      error: {
+        code: "qt_template_not_found",
+        message: "未找到匹配需求的官方 Qt 示例模板。",
+        remediation: "请在包含 board-packs 的 Embed Labs 项目目录中运行，或传入 source_path 指向已有 Qt/CMake 工程。"
+      },
+      template: selected.template
+    };
+  }
+  const targetName = asString(args.target_name || args.targetName) || selected.targetName;
+  const buildDir = asString(args.build_dir || args.buildDir) || path.join(outputDir, targetName || "qt-app-build");
+
+  const sdk = await ensureLocalToolchain(args, boardId, "qt");
+  const buildArgs = { build_dir: buildDir, target_name: targetName, release_root: sdk.releaseRoot };
+  if (sourcePath) buildArgs.source_path = sourcePath;
+  const buildResult = await localQtSmoke(buildArgs);
+  const artifactPath = artifactPathFromBuild(buildResult);
+
+  let deployResult;
+  const approved = boolValue(args.approved) || boolValue(args.approve);
+  const shouldDeploy = boolValue(args.deploy) || boolValue(args.run);
+  if (shouldDeploy && approved) {
+    const scan = await runEmbed(["device", "list"]);
+    const host = asString(args.host) || taishanpiHostFromDeviceList(scan);
+    if (!host) {
+      deployResult = {
+        ok: false,
+        error: {
+          code: "runtime_host_not_found",
+          message: "Qt 程序已完成交叉编译，但当前未检测到可通过 SSH 部署的泰山派运行态主机。",
+          remediation: "确认泰山派已启动初始化系统并连接到当前电脑/网络后，再调用同一工具部署。"
+        }
+      };
+    } else if (!artifactPath) {
+      deployResult = {
+        ok: false,
+        error: {
+          code: "artifact_not_found",
+          message: "Qt 构建没有返回可部署的可执行文件路径。"
+        }
+      };
+    } else {
+      const remotePath = asString(args.remote_path || args.remotePath)
+        || `/userdata/embed-labs/apps/${path.basename(artifactPath)}`;
+      const command = ["deploy", "taishanpi", "--host", host, "--artifact", artifactPath, "--remote-path", remotePath, "--approve"];
+      if (boolValue(args.run)) {
+        command.push("--run", "--run-command", qtRuntimeCommand(remotePath));
+      }
+      deployResult = await runEmbed(command);
+    }
+  }
+
+  const buildData = responseData(buildResult) || {};
+  const deployData = responseData(deployResult) || {};
+  const result = {
+    ok: buildResult?.response?.ok === true && (!deployResult || deployResult?.response?.ok === true || deployResult?.ok === false),
+    action: "taishanpi_qt_app_workflow",
+    board: "TaishanPi 1M RK3566",
+    status: deployResult ? (deployResult?.response?.ok === true ? "built_and_deployed" : "built_deploy_pending") : "built",
+    template: selected.template,
+    request: request || undefined,
+    sdk: compactSdkState(sdk.sdkCheck, sdk.sdkInstall),
+    source_path: sourcePath || "built-in Qt smoke source",
+    build: compactObject({
+      build_dir: buildDir,
+      target_name: targetName,
+      artifact_path: artifactPath,
+      artifact_size_bytes: buildData.artifact_size_bytes,
+      artifact_sha256: buildData.artifact_sha256,
+      summary_for_user: buildData.summary_for_user
+    }),
+    deploy: deployResult ? compactObject({
+      ok: deployResult?.response?.ok ?? deployResult?.ok,
+      host: deployData.host,
+      remote_path: deployData.remote_path,
+      ran: deployData.ran,
+      error: deployResult?.error || deployResult?.response?.error
+    }) : undefined,
+    summary_for_user: deployResult?.response?.ok === true
+      ? "Qt 程序已按泰山派 Qt 运行库路径完成构建、部署并启动。"
+      : "Qt 程序已通过本机 LLVM/Qt 工具链完成交叉编译。",
+    next_step: deployResult ? "查看部署/运行结果；如需协议采集，再调用 RP2350 Monitor 的对应高层工具。" : "如需上板运行，用户批准后用同一工具传入 deploy=true、run=true、approved=true。",
+    raw_omitted: boolValue(args.include_raw) ? undefined : true
+  };
+  if (boolValue(args.include_raw)) {
+    result.raw = compactObject({ build_result: buildResult, deploy_result: deployResult });
+  }
+  return result;
+}
+
+async function localToolchainLatest(args) {
+  const command = ["local", "toolchain", "latest"];
+  pushOptional(command, "board", args.board_id || args.board);
+  pushOptional(command, "channel", args.channel);
+  pushOptional(command, "metadata-root", args.metadata_root || args.metadataRoot);
+  return await runEmbed(command);
+}
+
+async function localToolchainList(args) {
+  const command = ["local", "toolchain", "list"];
+  pushOptional(command, "board", args.board_id || args.board);
+  pushOptional(command, "channel", args.channel);
+  pushOptional(command, "metadata-root", args.metadata_root || args.metadataRoot);
+  pushOptional(command, "install-root", args.install_root || args.installRoot);
+  return await runEmbed(command);
+}
+
+async function localToolchainInstalled(args) {
+  const command = ["local", "toolchain", "installed"];
+  pushOptional(command, "board", args.board_id || args.board);
+  pushOptional(command, "channel", args.channel);
+  pushOptional(command, "metadata-root", args.metadata_root || args.metadataRoot);
+  pushOptional(command, "install-root", args.install_root || args.installRoot);
+  return await runEmbed(command);
+}
+
+async function localToolchainCurrent(args) {
+  const command = ["local", "toolchain", "current"];
+  pushOptional(command, "install-root", args.install_root || args.installRoot);
+  return await runEmbed(command);
+}
+
+async function localToolchainInstall(args) {
+  const command = ["local", "toolchain", "install"];
+  pushOptional(command, "board", args.board_id || args.board);
+  pushOptional(command, "channel", args.channel);
+  pushOptional(command, "metadata-root", args.metadata_root || args.metadataRoot);
+  pushOptional(command, "source-url", args.source_url || args.sourceUrl);
+  pushOptional(command, "source-release-root", args.source_release_root || args.sourceReleaseRoot);
+  pushOptional(command, "install-root", args.install_root || args.installRoot);
+  pushOptional(command, "mode", args.mode);
+  if (boolValue(args.force)) command.push("--force");
+  return await runEmbed(command);
+}
+
+async function localToolchainUninstall(args) {
+  const boardId = asString(args.board_id || args.board);
+  if (!boardId) throw new Error("board_id is required");
+  const command = ["local", "toolchain", "uninstall", "--board", boardId];
+  pushOptional(command, "install-root", args.install_root || args.installRoot);
+  return await runEmbed(command);
+}
+
+async function localToolchainValidate(args) {
+  const command = ["local", "toolchain", "validate"];
+  pushOptional(command, "board", args.board_id || args.board);
+  pushOptional(command, "release-root", args.release_root || args.releaseRoot);
+  pushOptional(command, "mode", args.mode);
+  return await runEmbed(command);
+}
+
+function isTaishanpiInitialTarget(value) {
+  const text = asString(value).toLowerCase();
+  return text.includes("taishan") || text.includes("tspi") || text.includes("rk3566") || text.includes("1m");
+}
+
+function isRp2350InitialTarget(value) {
+  const text = asString(value).toLowerCase();
+  return text.includes("rp2350") || text.includes("pico") || text.includes("coloreasy");
+}
+
+async function initialImageFlash(args) {
+  const requestedBoard = asString(args.board_id || args.board);
+  if (isRp2350InitialTarget(requestedBoard)) {
+    return await rp2350InitialFirmwareFlash(args);
+  }
+  if (isTaishanpiInitialTarget(requestedBoard)) {
+    return await taishanpiInitialImageFlash(args);
+  }
+
+  const scan = await runEmbed(["device", "list"]);
+  const scanData = responseData(scan) || {};
+  const devices = Array.isArray(scanData.development_boards) ? scanData.development_boards : [];
+  const candidates = devices
+    .filter((item) => item?.board_id === "taishanpi" || isRp2350Device(item))
+    .map((item) => compactObject({
+      local_device_id: item.local_device_id || item.device_id,
+      board_id: item.board_id,
+      variant_id: item.variant_id,
+      display_name: item.display_name || item.name,
+      status: item.status
+    }));
+
+  if (candidates.length === 1) {
+    const candidate = candidates[0];
+    const nextArgs = { ...args, local_device_id: args.local_device_id || candidate.local_device_id };
+    if (candidate.board_id === "taishanpi") return await taishanpiInitialImageFlash(nextArgs);
+    return await rp2350InitialFirmwareFlash({ ...nextArgs, board_id: candidate.variant_id || candidate.board_id });
+  }
+
+  return {
+    ok: false,
+    error: {
+      code: candidates.length > 1 ? "ambiguous_board" : "target_not_found",
+      message: candidates.length > 1
+        ? "检测到多块可刷写开发板，请指定要刷写的开发板。"
+        : "当前未检测到可刷写初始化镜像的支持开发板。",
+      candidates,
+      remediation: candidates.length > 1
+        ? "重新调用 dbt_initial_image_flash，并传入对应 local_device_id。"
+        : "请连接开发板，或让开发板进入 Loader/Maskrom/BOOTSEL 后重新查询开发板状态。"
+    }
+  };
+}
+
+function compactSdkState(sdkCheck, sdkInstall) {
+  const checkData = responseData(sdkCheck) || {};
+  const installData = responseData(sdkInstall) || {};
+  const validation = objectValue(installData.validation) || {};
+  const repairedOk = typeof installData.ok === "boolean" ? installData.ok : validation.ok;
+  return compactObject({
+    checked: !!sdkCheck,
+    installed_or_repaired: !!sdkInstall,
+    ok: sdkInstall ? repairedOk : checkData.ok,
+    release_root: installData.release_root || validation.release_root || checkData.release_root,
+    mode: installData.mode || validation.mode || checkData.mode,
+    summary_for_user: installData.summary_for_user || validation.summary_for_user || checkData.summary_for_user
+  });
+}
+
+function compactFlashPlan(plan, boardLabel, imagePath) {
+  const data = responseData(plan) || {};
+  const target = data.target_device || {};
+  return compactObject({
+    ready: data.ready === true,
+    board: boardLabel || data.board_id,
+    boot_mode: data.boot_mode,
+    local_device_id: data.local_device_id || target.local_device_id || target.device_id,
+    target: target.display_name || target.name,
+    target_status: target.status,
+    image_dir: data.image_dir,
+    image_dir_source: data.image_dir_source,
+    artifact_path: imagePath,
+    approval_required: data.approval_required === true,
+    destructive: data.destructive === true,
+    step_count: Array.isArray(data.steps) ? data.steps.length : undefined,
+    partitions: Array.isArray(data.partitions)
+      ? data.partitions.map((item) => item.partition).filter(Boolean)
+      : undefined,
+    warnings: compactWarnings(data.warnings),
+    errors: data.errors
+  });
+}
+
+function compactWarnings(warnings) {
+  if (!Array.isArray(warnings) || warnings.length === 0) return undefined;
+  return warnings.map((item) => compactObject({
+    code: item.code,
+    message: item.message,
+    partitions: Array.isArray(item.partitions) ? item.partitions.map((part) => part.partition).filter(Boolean) : undefined
+  }));
+}
+
+function localJobIdFromRun(response) {
+  const data = responseData(response) || {};
+  return asString(data.local_job_id || data.job_id);
+}
+
+async function waitForLocalJob(jobId, timeoutMs = 180000) {
+  const deadline = Date.now() + Math.max(5000, timeoutMs);
+  let lastStatus = null;
+  while (Date.now() < deadline) {
+    lastStatus = await runEmbed(["task", "status", jobId]);
+    const data = responseData(lastStatus) || {};
+    const status = asString(data.status);
+    if (["completed", "failed", "cancelled"].includes(status)) {
+      return lastStatus;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  }
+  return lastStatus || { ok: false, response: { ok: false, error: { code: "job_status_timeout", message: "Timed out waiting for local flash job." } } };
+}
+
+function compactFlashRunResult(runResult, finalStatus) {
+  const started = responseData(runResult) || {};
+  const finalData = responseData(finalStatus) || {};
+  const data = Object.keys(finalData).length > 0 ? finalData : started;
+  return compactObject({
+    local_job_id: data.local_job_id || started.local_job_id,
+    status: data.status || started.status,
+    started_at: data.started_at || started.started_at,
+    updated_at: data.updated_at || started.updated_at,
+    completed_at: data.completed_at,
+    error: data.error,
+    logs: Array.isArray(data.logs) ? data.logs.slice(-8) : undefined
+  });
+}
+
+function compactInitialFlashResult({ boardLabel, sdkCheck, sdkInstall, imageDir, artifactPath, plan, runResult, finalStatus, approved, includeRaw }) {
+  const planSummary = compactFlashPlan(plan, boardLabel, artifactPath);
+  const runSummary = runResult ? compactFlashRunResult(runResult, finalStatus) : undefined;
+  const status = runSummary?.status || (planSummary.ready ? "ready_for_approval" : "not_ready");
+  const summary = runSummary
+    ? (runSummary.status === "completed"
+      ? `${boardLabel} 初始化镜像刷写已完成。`
+      : runSummary.status === "failed"
+        ? `${boardLabel} 初始化镜像刷写失败，请查看 error 和最近日志。`
+        : `${boardLabel} 初始化镜像刷写任务已启动，当前状态：${runSummary.status || "running"}。`)
+    : (planSummary.ready
+      ? `${boardLabel} 初始化镜像刷写计划已就绪，确认后可直接执行。`
+      : `${boardLabel} 初始化镜像刷写计划未就绪。`);
+  const result = {
+    ok: !runSummary?.error && planSummary.ready === true,
+    action: "initial_image_flash",
+    board: boardLabel,
+    status,
+    approved: approved === true,
+    summary_for_user: summary,
+    sdk: compactSdkState(sdkCheck, sdkInstall),
+    plan: planSummary,
+    run: runSummary,
+    next_step: runSummary
+      ? (runSummary.status === "completed" ? "可以重新查询开发板状态，确认系统已启动。" : "继续查询该 local_job_id 的任务状态。")
+      : (planSummary.ready ? "用户确认刷写后，调用同一工具并传入 approved=true。" : "根据 errors/warnings 修复后重试。"),
+    raw_omitted: includeRaw ? undefined : true
+  };
+  if (includeRaw) {
+    result.raw = compactObject({ sdk_check: sdkCheck, sdk_install: sdkInstall, flash_plan: plan, flash_result: runResult, final_status: finalStatus });
+  }
+  return result;
+}
+
+async function taishanpiInitialImageFlash(args) {
+  const sdkBoardId = asString(args.board_id || args.board) || "taishanpi-1m-rk3566";
+  const explicitImageDir = asString(args.image_dir || args.imageDir);
+  let sdkCheck = null;
+  let sdkInstall = null;
+  let releaseRoot = "";
+  if (!explicitImageDir) {
+    sdkCheck = await localToolchainValidate({ board_id: sdkBoardId, mode: "images" });
+    const checkData = responseData(sdkCheck) || {};
+    if (checkData.ok) {
+      releaseRoot = asString(checkData.release_root);
+    } else {
+      const installArgs = {
+        board_id: sdkBoardId,
+        channel: args.channel,
+        metadata_root: args.metadata_root || args.metadataRoot,
+        install_root: args.install_root || args.installRoot,
+        mode: "images",
+        force: args.force
+      };
+      sdkInstall = await localToolchainInstall(installArgs);
+      const installedData = responseData(sdkInstall) || {};
+      releaseRoot = asString(installedData.release_root);
+    }
+  }
+  const imageDir = explicitImageDir || (releaseRoot ? path.join(releaseRoot, "images", "current") : "");
+  const localDeviceId = asString(args.local_device_id || args.localDeviceId || args.device_id || args.deviceId);
+  const planCommand = ["flash", "plan", "--board", "taishanpi"];
+  if (imageDir) pushOptional(planCommand, "image-dir", imageDir);
+  if (localDeviceId) pushOptional(planCommand, "local-device-id", localDeviceId);
+  const plan = await runEmbed(planCommand);
+  const approved = boolValue(args.approved) || boolValue(args.approve);
+  if (!approved) {
+    return compactInitialFlashResult({
+      boardLabel: "TaishanPi 1M RK3566",
+      sdkCheck,
+      sdkInstall,
+      imageDir,
+      plan,
+      approved,
+      includeRaw: boolValue(args.include_raw)
+    });
+  }
+  const runCommand = ["flash", "run", "--board", "taishanpi", "--approve"];
+  if (imageDir) pushOptional(runCommand, "image-dir", imageDir);
+  if (localDeviceId) pushOptional(runCommand, "local-device-id", localDeviceId);
+  const flashed = await runEmbed(runCommand);
+  const wait = args.wait === undefined ? true : boolValue(args.wait);
+  const jobId = localJobIdFromRun(flashed);
+  const finalStatus = wait && jobId ? await waitForLocalJob(jobId, Number(args.timeout_ms) || 180000) : undefined;
+  return compactInitialFlashResult({
+    boardLabel: "TaishanPi 1M RK3566",
+    sdkCheck,
+    sdkInstall,
+    imageDir,
+    plan,
+    runResult: flashed,
+    finalStatus,
+    approved,
+    includeRaw: boolValue(args.include_raw)
+  });
+}
+
+async function rp2350MonitorFirmwareFlash(args) {
+  const boardId = asString(args.board_id || args.board) || "pico2w-rp2350-monitor";
+  const installArgs = {
+    board_id: boardId,
+    channel: args.channel,
+    metadata_root: args.metadata_root || args.metadataRoot,
+    install_root: args.install_root || args.installRoot,
+    mode: "firmware",
+    force: args.force
+  };
+  const installed = await localToolchainInstall(installArgs);
+  const installedData = responseData(installed) || {};
+  const releaseRoot = asString(installedData.release_root);
+  const artifactPath = asString(args.artifact_path || args.artifact)
+    || (releaseRoot ? path.join(releaseRoot, "toolkit-runtime", "rp2350-monitor", "firmware", "rp2350_monitor.uf2") : "");
+  if (!artifactPath) {
+    throw new Error("RP2350 Monitor firmware UF2 could not be resolved after local toolchain install.");
+  }
+  const plan = await runEmbed(["flash", "plan", "--board", "rp2350", "--artifact", artifactPath]);
+  const approved = boolValue(args.approved) || boolValue(args.approve);
+  if (!approved) {
+    const planData = responseData(plan) || plan;
+    const automaticBootsel = !!planData.automatic_bootsel
+      || (Array.isArray(planData.steps) && planData.steps.some((step) => step && step.kind === "picotool_load_force_usb"));
+    return {
+      ok: true,
+      firmware_install: installed,
+      artifact_path: artifactPath,
+      flash_plan: plan,
+      next_step: automaticBootsel
+        ? "Flash plan is ready. After user approval, call this tool again with approved=true."
+        : "Flash plan needs a visible UF2 target volume before it can run."
+    };
+  }
+  const flashed = await runEmbed(["flash", "run", "--board", "rp2350", "--artifact", artifactPath, "--approve"]);
+  return {
+    ok: true,
+    firmware_install: installed,
+    artifact_path: artifactPath,
+    flash_plan: plan,
+    flash_result: flashed
+  };
+}
+
+function rp2350InitialFirmwarePath(boardId, releaseRoot) {
+  const normalized = boardId.toLowerCase();
+  const boardDir = normalized.includes("coloreasy") ? "coloreasypico2" : "pico2w";
+  return releaseRoot ? path.join(releaseRoot, "rp2350-initial-firmware", boardDir, "initial.uf2") : "";
+}
+
+async function rp2350InitialFirmwareFlash(args) {
+  const boardId = asString(args.board_id || args.board) || "pico2w-rp2350-monitor";
+  const installArgs = {
+    board_id: boardId,
+    channel: args.channel,
+    metadata_root: args.metadata_root || args.metadataRoot,
+    install_root: args.install_root || args.installRoot,
+    mode: "firmware",
+    force: args.force
+  };
+  const installed = await localToolchainInstall(installArgs);
+  const installedData = responseData(installed) || {};
+  const releaseRoot = asString(installedData.release_root);
+  const artifactPath = asString(args.artifact_path || args.artifact) || rp2350InitialFirmwarePath(boardId, releaseRoot);
+  if (!artifactPath) {
+    throw new Error("RP2350 initialization firmware UF2 could not be resolved after local toolchain install.");
+  }
+  const plan = await runEmbed(["flash", "plan", "--board", "rp2350", "--artifact", artifactPath]);
+  const approved = boolValue(args.approved) || boolValue(args.approve);
+  if (!approved) {
+    const planData = responseData(plan) || plan;
+    const automaticBootsel = !!planData.automatic_bootsel
+      || (Array.isArray(planData.steps) && planData.steps.some((step) => step && step.kind === "picotool_load_force_usb"));
+    return {
+      ok: true,
+      firmware_install: installed,
+      artifact_path: artifactPath,
+      flash_plan: plan,
+      next_step: automaticBootsel
+        ? "Initialization flash plan is ready. After user approval, call this tool again with approved=true."
+        : "Initialization flash plan needs a visible UF2 target volume before it can run."
+    };
+  }
+  const flashed = await runEmbed(["flash", "run", "--board", "rp2350", "--artifact", artifactPath, "--approve"]);
+  return {
+    ok: true,
+    firmware_install: installed,
+    artifact_path: artifactPath,
+    flash_plan: plan,
+    flash_result: flashed
+  };
+}
+
+async function pluginUpdateCheck(args) {
+  const command = ["plugin", "update", "check"];
+  pushOptional(command, "release-url", args.release_url || args.releaseUrl);
+  pushOptional(command, "target", args.target);
+  pushOptional(command, "codex-target", args.codex_target || args.codexTarget);
+  pushOptional(command, "opencode-target", args.opencode_target || args.opencodeTarget);
+  return await runEmbed(command);
+}
+
+async function pluginUpdate(args) {
+  const target = asString(args.target_plugin || args.plugin || "all").toLowerCase();
+  if (!["codex", "opencode", "all"].includes(target)) {
+    throw new Error("target_plugin must be codex, opencode, or all");
+  }
+  const command = ["plugin", "update", target];
+  pushOptional(command, "release-url", args.release_url || args.releaseUrl);
+  pushOptional(command, "target", args.target);
+  pushOptional(command, "codex-target", args.codex_target || args.codexTarget);
+  pushOptional(command, "opencode-target", args.opencode_target || args.opencodeTarget);
+  return await runEmbed(command);
+}
+
+async function localCompile(args) {
+  const sourcePath = asString(args.source_path || args.source);
+  const outputPath = asString(args.output_path || args.output);
+  if (!sourcePath) throw new Error("source_path is required");
+  if (!outputPath) throw new Error("output_path is required");
+  const command = ["local", "compile", "taishanpi", "--source", sourcePath, "--output", outputPath];
+  pushOptional(command, "account", args.account_id || args.account);
+  pushOptional(command, "release-root", args.release_root || args.releaseRoot);
+  return await runEmbed(command);
+}
+
+async function localQtSmoke(args) {
+  const buildDir = asString(args.build_dir || args.buildDir);
+  if (!buildDir) throw new Error("build_dir is required");
+  const command = ["local", "build", "qt-smoke", "--build-dir", buildDir];
+  pushOptional(command, "account", args.account_id || args.account);
+  pushOptional(command, "source", args.source_path || args.source);
+  pushOptional(command, "target-name", args.target_name || args.targetName);
+  pushOptional(command, "release-root", args.release_root || args.releaseRoot);
+  return await runEmbed(command);
+}
+
+function serverWorkspaceDisabledResult() {
+  return {
+    ok: false,
+    error: {
+      code: "server_workspaces_disabled",
+      message: "Embed Labs now uses the user's local SDK/toolchain environment for source edits, builds, and board operation. Server-side user workspaces, Docker builds, and image generation are not exposed by the plugin.",
+      remediation: "Use dbt_local_toolchain_install, dbt_local_toolchain_validate, dbt_local_compile, dbt_local_qt_smoke, and Local Bridge board tools. Cloud API remains available for account login, device binding, board knowledge, plugin releases, MCP service logs, and SDK downloads."
+    }
+  };
+}
+
+function isServerWorkspaceToolName(name) {
+  return [
+    "dbt_workspace_provision",
+    "dbt_application_generate",
+    "dbt_source_list",
+    "dbt_source_get",
+    "dbt_source_search",
+    "dbt_source_put",
+    "dbt_source_patch",
+    "dbt_application_compile",
+    "dbt_image_generate",
+    "dbt_workspace_release"
+  ].includes(name);
+}
+
+function isServerWorkspaceAction(action) {
+  return [
+    "provision",
+    "workspace-provision",
+    "source-list",
+    "list-source",
+    "source-get",
+    "source-read",
+    "read-source",
+    "source-search",
+    "search-source",
+    "source-put",
+    "source-write",
+    "write-source",
+    "source-patch",
+    "patch-source",
+    "app",
+    "application",
+    "application-generate",
+    "build-run",
+    "compile",
+    "application-compile",
+    "image",
+    "image-generate",
+    "release",
+    "workspace-release"
+  ].includes(action);
+}
+
+async function workspaceProvision(args) {
+  const account = asString(args.account_id || args.account);
+  const project = asString(args.project_id || args.project);
+  if (!account) throw new Error("account_id is required");
+  if (!project) throw new Error("project_id is required");
+  const command = [
+    "build",
+    "workspace",
+    "provision",
+    "--account",
+    account,
+    "--project",
+    project,
+    "--template",
+    asString(args.template_id || args.template) || DEFAULT_TEMPLATE_ID,
+    "--copy-mode",
+    asString(args.copy_mode) || "skeleton"
+  ];
+  if (boolValue(args.dry_run)) command.push("--dry-run");
+  return await runEmbed(command);
+}
+
+async function applicationGenerate(args) {
+  const workspace = asString(args.workspace_id || args.workspace);
+  const prompt = asString(args.prompt || args.request);
+  if (!workspace) throw new Error("workspace_id is required");
+  if (!prompt) throw new Error("prompt is required");
+  const command = ["build", "application", "generate", "--workspace", workspace, "--prompt", prompt];
+  pushOptional(command, "account", args.account_id || args.account);
+  pushOptional(command, "provider", args.provider);
+  pushOptional(command, "model", args.model);
+  pushOptional(command, "target", args.target);
+  const generated = await runEmbed(command);
+  if (!asString(args.download_output)) return generated;
+  const artifact = pickArtifact(generated, "firmware");
+  if (!artifact?.artifact_id) throw new Error("No downloadable application artifact found");
+  const downloaded = await runEmbed(["artifact", "download", artifact.artifact_id, "--output", args.download_output]);
+  return { generated, selected_artifact: artifact, downloaded };
+}
+
+async function sourceList(args) {
+  const workspace = asString(args.workspace_id || args.workspace);
+  if (!workspace) throw new Error("workspace_id is required");
+  return await runEmbed(["build", "workspace", "source", "list", workspace]);
+}
+
+async function sourceGet(args) {
+  const workspace = asString(args.workspace_id || args.workspace);
+  const sourcePath = asString(args.source_path || args.path);
+  if (!workspace) throw new Error("workspace_id is required");
+  if (!sourcePath) throw new Error("source_path is required");
+  const command = ["build", "workspace", "source", "get", workspace, "--path", sourcePath];
+  pushOptional(command, "output", args.output_path || args.output);
+  return await runEmbed(command);
+}
+
+async function sourceSearch(args) {
+  const workspace = asString(args.workspace_id || args.workspace);
+  if (!workspace) throw new Error("workspace_id is required");
+  const command = ["build", "workspace", "source", "search", workspace];
+  pushOptional(command, "query", args.query);
+  pushOptional(command, "glob", args.glob);
+  pushOptional(command, "limit", args.limit);
+  return await runEmbed(command);
+}
+
+async function sourcePut(args) {
+  const workspace = asString(args.workspace_id || args.workspace);
+  const localPath = asString(args.local_path || args.local);
+  const sourcePath = asString(args.source_path || args.path);
+  if (!workspace) throw new Error("workspace_id is required");
+  if (!localPath) throw new Error("local_path is required");
+  if (!sourcePath) throw new Error("source_path is required");
+  const command = ["build", "workspace", "source", "put", workspace, "--file", `${localPath}:${sourcePath}`];
+  pushOptional(command, "account", args.account_id || args.account);
+  return await runEmbed(command);
+}
+
+async function sourcePatch(args) {
+  const workspace = asString(args.workspace_id || args.workspace);
+  const patchPath = asString(args.patch_path || args.patch);
+  if (!workspace) throw new Error("workspace_id is required");
+  if (!patchPath) throw new Error("patch_path is required");
+  const command = ["build", "workspace", "source", "patch", workspace, "--patch", patchPath];
+  pushOptional(command, "account", args.account_id || args.account);
+  return await runEmbed(command);
+}
+
+async function applicationCompile(args) {
+  const workspace = asString(args.workspace_id || args.workspace);
+  if (!workspace) throw new Error("workspace_id is required");
+  const command = ["build", "application", "compile", "--workspace", workspace];
+  pushOptional(command, "account", args.account_id || args.account);
+  pushOptional(command, "source", args.source_path || args.source);
+  pushOptional(command, "output-name", args.output_name);
+  pushOptional(command, "execution-mode", args.execution_mode);
+  pushOptional(command, "compiler", args.compiler);
+  return await runEmbed(command);
+}
+
+async function taskStatus(args) {
+  const task = asString(args.task_id || args.task);
+  if (!task) throw new Error("task_id is required");
+  return await runEmbed(["cloud", "task", "status", task]);
+}
+
+function safeArtifactOutputFileName(name) {
+  return asString(name).replace(/[^A-Za-z0-9._-]+/g, "_") || "task.log";
+}
+
+async function taskLogDownload(args) {
+  const task = asString(args.task_id || args.task);
+  if (!task) throw new Error("task_id is required");
+  const status = await taskStatus({ task_id: task });
+  const data = responseData(status);
+  const artifacts = Array.isArray(data?.artifacts) ? data.artifacts : [];
+  const log = artifacts.find((item) => item.kind === "log" || asString(item.name).endsWith(".log"));
+  if (!log?.artifact_id) throw new Error(`Task ${task} does not expose a log artifact`);
+  const output = asString(args.output_path || args.output) || path.join(".embed-labs", "artifacts", `${task}-${safeArtifactOutputFileName(log.name)}`);
+  const downloaded = await runEmbed(["artifact", "download", log.artifact_id, "--output", output]);
+  return { status, selected_artifact: log, downloaded };
+}
+
+async function imageGenerate(args) {
+  const workspace = asString(args.workspace_id || args.workspace);
+  const prompt = asString(args.prompt || args.request);
+  if (!workspace) throw new Error("workspace_id is required");
+  if (!prompt) throw new Error("prompt is required");
+  const command = ["build", "image", "generate", "--workspace", workspace, "--prompt", prompt];
+  pushOptional(command, "account", args.account_id || args.account);
+  pushOptional(command, "provider", args.provider);
+  pushOptional(command, "model", args.model);
+  pushOptional(command, "image-profile", args.image_profile);
+  pushOptional(command, "execution-mode", args.execution_mode);
+  pushOptional(command, "worker-pool", args.worker_pool);
+  const generated = await runEmbed(command);
+  if (!asString(args.download_output)) return generated;
+  const artifact = pickArtifact(generated, "image");
+  if (!artifact?.artifact_id) throw new Error("No downloadable image artifact found");
+  const downloaded = await runEmbed(["artifact", "download", artifact.artifact_id, "--output", args.download_output]);
+  return { generated, selected_artifact: artifact, downloaded };
+}
+
+async function artifactDownload(args) {
+  const artifact = asString(args.artifact_id || args.artifact);
+  const output = asString(args.output_path || args.output);
+  if (!artifact) throw new Error("artifact_id is required");
+  if (!output) throw new Error("output_path is required");
+  return await runEmbed(["artifact", "download", artifact, "--output", output]);
+}
+
+async function workspaceRelease(args) {
+  const workspace = asString(args.workspace_id || args.workspace);
+  if (!workspace) throw new Error("workspace_id is required");
+  const command = ["build", "workspace", "release", workspace];
+  if (boolValue(args.dry_run)) command.push("--dry-run");
+  if (boolValue(args.no_settle_storage)) command.push("--no-settle-storage");
+  return await runEmbed(command);
+}
+
+async function callTool(name, args = {}) {
+  if (name === "dbt_auth_status") return await pluginAuthStatus();
+  if (name === "dbt_plugin_update_check") return await pluginUpdateCheck(args);
+  if (name === "dbt_plugin_update") return await pluginUpdate(args);
+  if (name === "dbt_supported_boards") return await supportedBoards(args);
+  if (name === "dbt_local_toolchain_list") return await localToolchainList(args);
+  if (name === "dbt_local_toolchain_installed") return await localToolchainInstalled(args);
+  if (name === "dbt_local_toolchain_latest") return await localToolchainLatest(args);
+  if (name === "dbt_local_toolchain_current") return await localToolchainCurrent(args);
+  const authStatus = await pluginAuthStatus();
+  if (!authStatus.ok) return authStatus;
+  if (name === "dbt_current_board_status" || name === "dbtstatus") return await currentBoardStatus(args, authStatus);
+  if (name === "dbt_initial_image_flash") return await initialImageFlash(args);
+  if (name === "dbt_rp2350_monitor_status") return await rp2350MonitorStatus(args);
+  if (name === "dbt_rp2350_capabilities") return await rp2350Capabilities(args);
+  if (name === "dbt_rp2350_operation") return await rp2350Operation(args);
+  if (name === "dbt_rp2350_gpio_read") return await rp2350GpioRead(args);
+  if (name === "dbt_rp2350_gpio_write") return await rp2350GpioWrite(args);
+  if (name === "dbt_rp2350_uart_write") return await rp2350UartWrite(args);
+  if (name === "dbt_rp2350_i2c_transfer") return await rp2350I2cTransfer(args);
+  if (name === "dbt_rp2350_logic_capture") return await rp2350LogicCapture(args);
+  if (name === "dbt_rp2350_logic_decode") return await rp2350LogicDecode(args);
+  if (name === "dbt_rp2350_spi_transfer") return await rp2350SpiTransfer(args);
+  if (name === "dbt_rp2350_wifi_manage") return await rp2350WifiManage(args);
+  if (name === "dbt_rp2350_probe_debug") return await rp2350ProbeDebug(args);
+  if (name === "dbt_rp2350_monitor_command") return await rp2350MonitorCommand(args);
+  if (name === "dbt_cloud_status") return await cloudStatus(args);
+  if (name === "dbt_board_knowledge_search") return await boardKnowledgeSearch(args);
+  if (isServerWorkspaceToolName(name)) return serverWorkspaceDisabledResult();
+  if (name === "dbt_task_status") return await taskStatus(args);
+  if (name === "dbt_task_log_download") return await taskLogDownload(args);
+  if (name === "dbt_artifact_download") return await artifactDownload(args);
+  if (name === "dbt_board_debug") return await boardDebug(args);
+  if (name === "dbt_boot_logo_update") return await bootLogoUpdate(args);
+  if (name === "dbt_update_logo") return await updateLogo(args);
+  if (name === "dbt_compose_boot_logo") return await composeBootLogo(args);
+  if (name === "dbt_local_toolchain_install") return await localToolchainInstall(args);
+  if (name === "dbt_local_toolchain_uninstall") return await localToolchainUninstall(args);
+  if (name === "dbt_local_toolchain_validate") return await localToolchainValidate(args);
+  if (name === "dbt_taishanpi_initial_image_flash") return await taishanpiInitialImageFlash(args);
+  if (name === "dbt_rp2350_monitor_firmware_flash") return await rp2350MonitorFirmwareFlash(args);
+  if (name === "dbt_rp2350_initial_firmware_flash") return await rp2350InitialFirmwareFlash(args);
+  if (name === "dbt_plugin_update_check") return await pluginUpdateCheck(args);
+  if (name === "dbt_plugin_update") return await pluginUpdate(args);
+  if (name === "dbt_local_compile") return await localCompile(args);
+  if (name === "dbt_local_qt_smoke") return await localQtSmoke(args);
+  if (name === "dbt_taishanpi_qt_app_workflow") return await taishanpiQtAppWorkflow(args);
+  if (name === "dbttool") {
+    const action = asString(args.action).toLowerCase().replaceAll("_", "-");
+    let payload = {};
+    if (asString(args.arguments_json)) payload = JSON.parse(args.arguments_json);
+    if (asString(args.request) && !payload.prompt) payload.prompt = asString(args.request);
+    if (["supported-boards", "boards", "board-list", "registry-list"].includes(action)) return await supportedBoards(payload);
+    if (["status", "cloud-status", "methods", "knowledge", "capabilities"].includes(action)) return await cloudStatus(payload);
+    if (["board-status", "status"].includes(action)) return await currentBoardStatus(payload, authStatus);
+    if (["rp2350-capabilities", "rpmon-capabilities", "rp2350-catalog", "rpmon-catalog"].includes(action)) return await rp2350Capabilities(payload);
+    if (["rp2350-operation", "rpmon-operation"].includes(action)) return await rp2350Operation(payload);
+    if (["rp2350-monitor-status", "rp2350-status", "rpmon-status"].includes(action)) return await rp2350MonitorStatus(payload);
+    if (["rp2350-gpio-read", "rpmon-gpio-read", "gpio-read"].includes(action)) return await rp2350GpioRead(payload);
+    if (["rp2350-gpio-write", "rpmon-gpio-write", "gpio-write"].includes(action)) return await rp2350GpioWrite(payload);
+    if (["rp2350-uart-write", "rpmon-uart-write", "uart-write"].includes(action)) return await rp2350UartWrite(payload);
+    if (["rp2350-i2c-transfer", "rpmon-i2c-transfer", "i2c-transfer"].includes(action)) return await rp2350I2cTransfer(payload);
+    if (["rp2350-logic-capture", "rpmon-logic-capture", "logic-capture"].includes(action)) return await rp2350LogicCapture(payload);
+    if (["rp2350-logic-decode", "rpmon-logic-decode", "logic-decode"].includes(action)) return await rp2350LogicDecode(payload);
+    if (["rp2350-spi-transfer", "rpmon-spi-transfer", "spi-transfer", "spi-test"].includes(action)) return await rp2350SpiTransfer(payload);
+    if (["rp2350-wifi", "rpmon-wifi", "wifi-manage"].includes(action)) return await rp2350WifiManage(payload);
+    if (["rp2350-probe-debug", "rpmon-probe-debug", "probe-debug"].includes(action)) return await rp2350ProbeDebug(payload);
+    if (["rp2350-monitor-command", "rpmon-command"].includes(action)) return await rp2350MonitorCommand(payload);
+    if (["initial-image-flash", "flash-initial-image", "initial-flash", "flash-initial", "init-flash"].includes(action)) return await initialImageFlash(payload);
+    if (["debug", "agent-run", "deploy"].includes(action)) return await boardDebug(payload);
+    if (["boot-logo-update", "update-boot-logo", "update-logo", "boot-logo", "logo", "boot-logo-modify"].includes(action)) return await bootLogoUpdate(payload);
+    if (["compose-boot-logo", "boot-logo-compose", "compose-logo"].includes(action)) return await composeBootLogo(payload);
+    if (["local-toolchain-list", "toolchain-list", "list-toolchains", "board-environments", "local-environments"].includes(action)) return await localToolchainList(payload);
+    if (["local-toolchain-installed", "toolchain-installed", "installed-toolchains", "installed-board-environments"].includes(action)) return await localToolchainInstalled(payload);
+    if (["local-toolchain-latest", "toolchain-latest", "latest-toolchain"].includes(action)) return await localToolchainLatest(payload);
+    if (["local-toolchain-current", "toolchain-current", "current-toolchain"].includes(action)) return await localToolchainCurrent(payload);
+    if (["local-toolchain-install", "toolchain-install", "install-toolchain"].includes(action)) return await localToolchainInstall(payload);
+    if (["local-toolchain-uninstall", "toolchain-uninstall", "uninstall-toolchain", "remove-toolchain"].includes(action)) return await localToolchainUninstall(payload);
+    if (["local-toolchain", "local-toolchain-validate", "toolchain-validate"].includes(action)) return await localToolchainValidate(payload);
+    if (["taishanpi-initial-image-flash", "taishanpi-initial-flash", "taishanpi-flash-initial", "rk3566-initial-flash"].includes(action)) return await taishanpiInitialImageFlash(payload);
+    if (["rp2350-monitor-firmware-flash", "rp2350-firmware-flash", "pico-monitor-flash"].includes(action)) return await rp2350MonitorFirmwareFlash(payload);
+    if (["rp2350-initial-firmware-flash", "rp2350-initial-flash", "pico-initial-flash", "pico-initial-firmware-flash"].includes(action)) return await rp2350InitialFirmwareFlash(payload);
+    if (["plugin-update-check", "check-plugin-update", "update-check"].includes(action)) return await pluginUpdateCheck(payload);
+    if (["plugin-update", "update-plugin", "upgrade-plugin"].includes(action)) return await pluginUpdate(payload);
+    if (["local-compile", "compile-local"].includes(action)) return await localCompile(payload);
+    if (["local-qt-smoke", "qt-smoke", "local-qt-build"].includes(action)) return await localQtSmoke(payload);
+    if (["taishanpi-qt-app", "qt-app", "qt-workflow", "taishanpi-qt-workflow", "qt-develop"].includes(action)) return await taishanpiQtAppWorkflow(payload);
+    if (isServerWorkspaceAction(action)) return serverWorkspaceDisabledResult();
+    if (["task-status", "status-task"].includes(action)) return await taskStatus(payload);
+    if (["task-log", "task-log-download", "log-download"].includes(action)) return await taskLogDownload(payload);
+    if (["download", "artifact-download"].includes(action)) return await artifactDownload(payload);
+    return { ok: false, error_code: "unsupported_dbt_action" };
+  }
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+let responseFraming = "jsonl";
+
+function send(message) {
+  const json = JSON.stringify(message);
+  if (responseFraming === "content-length") {
+    const body = Buffer.from(json, "utf8");
+    process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+    process.stdout.write(body);
+    return;
+  }
+  process.stdout.write(`${json}\n`);
+}
+
+async function handleRpc(message) {
+  if (!message || typeof message !== "object") return;
+  if (!("id" in message)) return;
+  try {
+    if (message.method === "initialize") {
+      send({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: mcpServerInfo()
+        }
+      });
+      return;
+    }
+    if (message.method === "tools/list") {
+      send({ jsonrpc: "2.0", id: message.id, result: { tools } });
+      return;
+    }
+    if (message.method === "tools/call") {
+      const result = await callTool(message.params?.name, message.params?.arguments || {});
+      send({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+          isError: false
+        }
+      });
+      return;
+    }
+    if (message.method === "ping") {
+      send({ jsonrpc: "2.0", id: message.id, result: {} });
+      return;
+    }
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: { code: -32601, message: `Unsupported method: ${message.method}` }
+    });
+  } catch (error) {
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: { code: -32000, message: error?.message || String(error) }
+    });
+  }
+}
+
+function startMcp() {
+  let buffer = Buffer.alloc(0);
+  process.stdin.on("data", (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length > 0) {
+      const asText = buffer.toString("utf8");
+      if (/^Content-Length:/i.test(asText)) {
+        const marker = buffer.indexOf("\r\n\r\n");
+        if (marker < 0) return;
+        const header = buffer.slice(0, marker).toString("utf8");
+        const match = /Content-Length:\s*(\d+)/i.exec(header);
+        if (!match) {
+          buffer = buffer.slice(marker + 4);
+          continue;
+        }
+        const length = Number.parseInt(match[1], 10);
+        const start = marker + 4;
+        if (buffer.length < start + length) return;
+        const body = buffer.slice(start, start + length).toString("utf8");
+        buffer = buffer.slice(start + length);
+        responseFraming = "content-length";
+        try {
+          void handleRpc(JSON.parse(body));
+        } catch {
+          // Ignore malformed frames; a valid client will retry with a request id.
+        }
+        continue;
+      }
+
+      const newline = buffer.indexOf("\n");
+      if (newline < 0) return;
+      const line = buffer.slice(0, newline).toString("utf8").trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      responseFraming = "jsonl";
+      try {
+        void handleRpc(JSON.parse(line));
+      } catch {
+        // Ignore malformed frames; a valid client will retry with a request id.
+      }
+    }
+  });
+}
+
+async function main() {
+  const [mode, name, json = "{}"] = process.argv.slice(2);
+  if (mode === "--list-tools") {
+    process.stdout.write(`${JSON.stringify(tools.map((item) => item.name), null, 2)}\n`);
+    return;
+  }
+  if (mode === "--call-tool") {
+    const result = await callTool(name, JSON.parse(json || "{}"));
+    process.stdout.write(`${JSON.stringify({ ok: true, result }, null, 2)}\n`);
+    return;
+  }
+  startMcp();
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error?.message || String(error)}\n`);
+  process.exitCode = 1;
+});