@inobit/pi-instabox 0.0.0-stage → 0.1.0

package/src/config.ts

@@ -0,0 +1,310 @@
+/**
+ * @inobit/pi-instabox — 扩展配置与路径。
+ *
+ * 叠加顺序（后者覆盖前者）：`DEFAULT_CONFIG` → `<agentDir>/extensions/pi-instabox/config.json`
+ * → `<cwd>/.pi/extensions/pi-instabox/config.json`（仅项目可信时）→ 环境变量 `INSTABOX_MCP_*`。
+ * 照 pi-todo / pi-nvim `src/config.ts` 范式：单测走纯函数 `normalizeConfig`，`loadConfig`
+ * 在 `VITEST` 下恒返回默认值＋环境变量层（测试确定性），所有外部访问都走注入面便于离线测试。
+ *
+ * 路径布局（裁决 V3）：配置进 `<agentDir>/extensions/pi-instabox/`，运行期状态与 helper 进
+ * `<agentDir>/pi-instabox/`，事件日志进 `<agentDir>/logs/pi-instabox/`（与
+ * `logs/pi-permission/` 的生态惯例一致：扩展目录只放配置，日志与 `pi-debug.log` 同级）。
+ * 所有路径单点在 `resolvePaths()`，其余模块只消费它的返回值。
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * 超时（毫秒）：准备阶段总预算 ＋ 各步单步上限（D4 唤醒链、D7 ⑤ 远端 MCP 客户端）。
+ *
+ * 两层语义不同，别按「各步相加」理解：`prepareMs` 是**一次工具调用准备阶段的截止时间**，
+ * 下面每个字段只是**单步上限**——某一步卡住时实际超时取 `min(该步上限, 剩余预算)`，
+ * 所以准备阶段的上界是 `prepareMs`，不是各字段之和。
+ */
+export interface InstaboxTimeouts {
+	/**
+	 * 准备阶段总预算：查状态 → 唤醒链（`wake`/`start`/`resume`）→ 确认 `running` → 建连 共享
+	 * 这一个截止时间。用户要求「准备阶段总共约 1 分钟」，投一次桌面调用不该等 8 分钟。
+	 */
+	prepareMs: number;
+	/** `instabox wake` 单步上限（只处理「自动暂停」；吃满即截止到 `prepareMs`） */
+	wakeMs: number;
+	/** `instabox start` / `instabox resume` 单步上限（整箱冷启） */
+	startMs: number;
+	/**
+	 * spawn 后等远端 MCP 传输建链的单步上限。
+	 *
+	 * 唤醒由准备阶段的唤醒链完成（`wake`/`start`/`resume`），这里不必再覆盖官方文档里
+	 * 「自动唤醒最多等 45s」那一段，只留「spawn → 首个字节」的余量。`remote.ts` 的
+	 * `DEFAULT_TIMEOUTS.connect`（15s）只是该模块的兜底值，装配层（`pool.ts`）会用本字段
+	 * 覆盖它，改这里才生效。
+	 */
+	connectMs: number;
+	/** `initialize` 请求上界 */
+	initializeMs: number;
+	/** `tools/list` 请求上界 */
+	listToolsMs: number;
+	/**
+	 * `tools/call` 请求上界（桌面操作可能含截图，给得最宽）。
+	 * 它属于工具调用本身，**不**在准备阶段的 `prepareMs` 里。
+	 */
+	callMs: number;
+}
+
+export interface InstaboxConfig {
+	/** 解析链靠后的兜底目标；空串＝未配置（退到「`instabox ls` 第一台」） */
+	defaultBox: string;
+	/** DevTools 唯一对应的 box；空串＝该能力整体不存在（不建目录、不写 helper、不提示） */
+	devToolsBox: string;
+	/** 指定了 devToolsBox 但远端没装 `chrome-devtools-mcp` 时，连接前尝试自动安装 */
+	autoInstallDevTools: boolean;
+	/** 钉死的远端 PATH（不同模板的 npm prefix 不同，`/opt/npm/bin` 与 `/usr/local/bin` 都出现过） */
+	remotePath: string;
+	/** 原样透传给 `chrome-devtools-mcp` 的参数 */
+	devToolsArgs: string[];
+	timeouts: InstaboxTimeouts;
+}
+
+export const DEFAULT_CONFIG: InstaboxConfig = {
+	defaultBox: "",
+	devToolsBox: "",
+	autoInstallDevTools: true,
+	remotePath: "/opt/npm/bin:/usr/local/bin:/usr/bin:/bin",
+	devToolsArgs: [
+		"--headless",
+		"--userDataDir=/data/home/.agent-chrome",
+		"--executablePath=/usr/bin/chromium",
+		"--viewport=1280x800",
+		"--no-usage-statistics",
+	],
+	timeouts: {
+		prepareMs: 60_000,
+		wakeMs: 20_000,
+		startMs: 30_000,
+		connectMs: 15_000,
+		initializeMs: 15_000,
+		listToolsMs: 15_000,
+		callMs: 120_000,
+	},
+};
+
+const TIMEOUT_KEYS = [
+	"prepareMs",
+	"wakeMs",
+	"startMs",
+	"connectMs",
+	"initializeMs",
+	"listToolsMs",
+	"callMs",
+] as const;
+
+/** agent 目录：`PI_CODING_AGENT_DIR` 优先，否则 `~/.pi/agent`（不可用 import.meta.url 推导：jiti 直载下不可靠） */
+export function getAgentDir(): string {
+	const env = process.env.PI_CODING_AGENT_DIR;
+	if (env) {
+		// `~` / `~/x` 两种写法都按家目录展开（与 pi-todo / pi-nvim 一致）
+		if (env === "~" || env.startsWith("~/") || env.startsWith("~\\")) return path.join(os.homedir(), env.slice(2));
+		return env;
+	}
+	return path.join(os.homedir(), ".pi", "agent");
+}
+
+/** 配置文件相对路径：全局层相对 `agentDir`，项目层相对 `<cwd>/.pi` */
+const CONFIG_RELATIVE_PATH = path.join("extensions", "pi-instabox", "config.json");
+
+/** 运行期目录名：状态进 `<agentDir>/pi-instabox`，日志进 `<agentDir>/logs/pi-instabox` */
+const STATE_DIR_NAME = "pi-instabox";
+
+export interface InstaboxPaths {
+	/** 配置文件（全局层；项目层在 `<cwd>/.pi/` 下同名） */
+	configFile: string;
+	/** 运行期状态目录（缓存与 helper 的父目录，按需创建） */
+	stateDir: string;
+	/** per-box 模板缓存 */
+	templateCacheFile: string;
+	/** DevTools helper 脚本（运行期产物，非配置） */
+	helperScript: string;
+	/** 事件日志目录（JSONL 由 `log.ts` 写入，按需创建） */
+	logDir: string;
+}
+
+export function resolvePaths(agentDir: string): InstaboxPaths {
+	const stateDir = path.join(agentDir, STATE_DIR_NAME);
+	return {
+		configFile: path.join(agentDir, CONFIG_RELATIVE_PATH),
+		stateDir,
+		templateCacheFile: path.join(stateDir, "templates.json"),
+		helperScript: path.join(stateDir, "bin", "devtools-connect.sh"),
+		logDir: path.join(agentDir, "logs", STATE_DIR_NAME),
+	};
+}
+
+/** 单层覆盖：只含逐字段合法的值；非法字段直接缺席（＝保留底层值） */
+export interface InstaboxConfigOverlay {
+	defaultBox?: string;
+	devToolsBox?: string;
+	autoInstallDevTools?: boolean;
+	remotePath?: string;
+	devToolsArgs?: string[];
+	timeouts?: Partial<InstaboxTimeouts>;
+}
+
+function asRecord(raw: unknown): Record<string, unknown> | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	return raw as Record<string, unknown>;
+}
+
+function asNonEmptyString(raw: unknown): string | undefined {
+	return typeof raw === "string" && raw !== "" ? raw : undefined;
+}
+
+function asPositiveInt(raw: unknown): number | undefined {
+	if (typeof raw !== "number" || !Number.isInteger(raw) || raw <= 0) return undefined;
+	return raw;
+}
+
+/** 字符串数组：丢非字符串与空串；显式 `[]` 表示清空（保留），全非法输入回 undefined（保留底层值） */
+function asStringList(raw: unknown): string[] | undefined {
+	if (!Array.isArray(raw)) return undefined;
+	const out: string[] = [];
+	for (const v of raw) {
+		if (typeof v === "string" && v !== "") out.push(v);
+	}
+	if (out.length === 0 && raw.length > 0) return undefined;
+	return out;
+}
+
+function asTimeouts(raw: unknown): Partial<InstaboxTimeouts> | undefined {
+	const rec = asRecord(raw);
+	if (!rec) return undefined;
+	const out: Partial<InstaboxTimeouts> = {};
+	for (const key of TIMEOUT_KEYS) {
+		const n = asPositiveInt(rec[key]);
+		if (n !== undefined) out[key] = n;
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** 纯校验（单层）：任意 `unknown` 输入都不 throw，非法/未知字段缺席 */
+export function normalizeConfigOverlay(raw: unknown): InstaboxConfigOverlay {
+	const rec = asRecord(raw);
+	if (!rec) return {};
+	const out: InstaboxConfigOverlay = {};
+	const defaultBox = rec["defaultBox"];
+	if (typeof defaultBox === "string") out.defaultBox = defaultBox;
+	const devToolsBox = rec["devToolsBox"];
+	if (typeof devToolsBox === "string") out.devToolsBox = devToolsBox;
+	const autoInstallDevTools = rec["autoInstallDevTools"];
+	if (typeof autoInstallDevTools === "boolean") out.autoInstallDevTools = autoInstallDevTools;
+	const remotePath = asNonEmptyString(rec["remotePath"]);
+	if (remotePath !== undefined) out.remotePath = remotePath;
+	const devToolsArgs = asStringList(rec["devToolsArgs"]);
+	if (devToolsArgs !== undefined) out.devToolsArgs = devToolsArgs;
+	const timeouts = asTimeouts(rec["timeouts"]);
+	if (timeouts !== undefined) out.timeouts = timeouts;
+	return out;
+}
+
+/** 叠加一层：`timeouts` 逐字段深合并，数组/对象一律拷贝（不共享 `DEFAULT_CONFIG` 的引用） */
+export function applyOverlay(base: InstaboxConfig, overlay: InstaboxConfigOverlay): InstaboxConfig {
+	return {
+		defaultBox: overlay.defaultBox ?? base.defaultBox,
+		devToolsBox: overlay.devToolsBox ?? base.devToolsBox,
+		autoInstallDevTools: overlay.autoInstallDevTools ?? base.autoInstallDevTools,
+		remotePath: overlay.remotePath ?? base.remotePath,
+		devToolsArgs: [...(overlay.devToolsArgs ?? base.devToolsArgs)],
+		timeouts: { ...base.timeouts, ...(overlay.timeouts ?? {}) },
+	};
+}
+
+/** 纯校验（单文件语义）：`normalizeConfig(undefined)` 即 `DEFAULT_CONFIG` 的深拷贝 */
+export function normalizeConfig(raw: unknown): InstaboxConfig {
+	return applyOverlay(DEFAULT_CONFIG, normalizeConfigOverlay(raw));
+}
+
+/** 环境变量名（`INSTABOX_MCP_AUTO_INSTALL` 取值 `0|1`，`INSTABOX_MCP_PATH` 只喂 helper 的 PATH） */
+const ENV_KEYS = {
+	defaultBox: "INSTABOX_MCP_DEFAULT_BOX",
+	devToolsBox: "INSTABOX_MCP_DEVTOOLS_BOX",
+	autoInstall: "INSTABOX_MCP_AUTO_INSTALL",
+	remotePath: "INSTABOX_MCP_PATH",
+} as const;
+
+export type EnvLike = Record<string, string | undefined>;
+
+/** 环境变量层：空串＝未设置（忽略）；`INSTABOX_MCP_AUTO_INSTALL` 只认 `0`/`1` */
+export function normalizeEnvOverlay(env: EnvLike): InstaboxConfigOverlay {
+	const overlay: InstaboxConfigOverlay = {};
+	const defaultBox = env[ENV_KEYS.defaultBox];
+	if (defaultBox) overlay.defaultBox = defaultBox;
+	const devToolsBox = env[ENV_KEYS.devToolsBox];
+	if (devToolsBox) overlay.devToolsBox = devToolsBox;
+	const autoInstall = env[ENV_KEYS.autoInstall];
+	if (autoInstall === "0") overlay.autoInstallDevTools = false;
+	else if (autoInstall === "1") overlay.autoInstallDevTools = true;
+	const remotePath = env[ENV_KEYS.remotePath];
+	if (remotePath) overlay.remotePath = remotePath;
+	return overlay;
+}
+
+export interface LoadConfigOptions {
+	/** agent 目录（默认 `getAgentDir()`） */
+	agentDir?: string;
+	/** 项目根（默认 `process.cwd()`） */
+	cwd?: string;
+	/** 项目可信才读 `<cwd>/.pi/extensions/pi-instabox/config.json`（默认 false） */
+	isTrusted?: boolean;
+	/** 读文件（默认 `fs.readFileSync(file, "utf8")`；抛错视为该层不存在） */
+	readFile?: (file: string) => string;
+	/** 存在性检查（默认 `fs.existsSync`；false 即跳过该层） */
+	exists?: (file: string) => boolean;
+	/** 环境变量源（默认 `process.env`；**显式注入即跳过 VITEST 短路**，供离线测试逐层断言） */
+	env?: EnvLike;
+}
+
+function readLayer(
+	file: string,
+	readFile: (file: string) => string,
+	exists: (file: string) => boolean,
+): InstaboxConfigOverlay | undefined {
+	if (!exists(file)) return undefined;
+	let text: string;
+	try {
+		text = readFile(file);
+	} catch {
+		return undefined;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		// 非法 JSON 当该层不存在：配置文件写坏不能拖垮会话
+		return undefined;
+	}
+	return normalizeConfigOverlay(parsed);
+}
+
+/**
+ * 加载配置：`DEFAULT_CONFIG` → 全局层 → 项目层（仅 trusted）→ 环境变量层。
+ * `VITEST` 下（且未注入 `env`）只返回默认值＋环境变量层，不碰文件系统。
+ */
+export function loadConfig(options: LoadConfigOptions = {}): InstaboxConfig {
+	const env = options.env ?? process.env;
+	if (options.env === undefined && process.env.VITEST) {
+		return applyOverlay(DEFAULT_CONFIG, normalizeEnvOverlay(env));
+	}
+	const readFile = options.readFile ?? ((file: string) => fs.readFileSync(file, "utf8"));
+	const exists = options.exists ?? ((file: string) => fs.existsSync(file));
+	const agentDir = options.agentDir ?? getAgentDir();
+	const cwd = options.cwd ?? process.cwd();
+	const projectFile = path.join(cwd, ".pi", CONFIG_RELATIVE_PATH);
+	let merged = normalizeConfig(undefined);
+	for (const file of [resolvePaths(agentDir).configFile, options.isTrusted === true ? projectFile : undefined]) {
+		if (!file) continue;
+		const layer = readLayer(file, readFile, exists);
+		if (layer) merged = applyOverlay(merged, layer);
+	}
+	return applyOverlay(merged, normalizeEnvOverlay(env));
+}

package/src/devtools.ts

@@ -0,0 +1,257 @@
+/**
+ * @inobit/pi-instabox — DevTools MCP：helper 脚本生成/写盘 + `registerMcpServer` 参数（方案 §4.6、§5.1、T13）。
+ *
+ * 契约：
+ * - helper 是**运行期产物**而非配置：落在 `<agentDir>/pi-instabox/bin/devtools-connect.sh`
+ *   （`paths.helperScript`，裁决 V3）。每次加载 `mkdir -p` + 幂等覆盖 + `chmod 0o755`；
+ *   写盘失败只 `warn`，不 throw 到会话层。
+ * - 脚本的 stdout **只承载 JSON-RPC**：pi 把 MCP 的 `command` 直接 exec（不经 shell），
+ *   任何写到 stdout 的诊断都会破坏 MCP 握手，所以诊断一律 stderr。
+ * - 脚本自己把箱拉起来（`wake`，失败再 `start`）：MCP 客户端不会唤醒箱，pi 也不会重连
+ *   失败的 server——箱暂停时若直接把检查/ssh 打过去，结果是 0 个工具且整场会话不再恢复。
+ *   两条命令都用 shell 的 `timeout`（有则用）封顶 {@link PREPARE_TIMEOUT_SECONDS} 秒。
+ * - PATH 走 `instabox exec --env PATH=…`（CLI 原生能力，方案 C-c「比 `env PATH=… cmd` 包装更干净」）；
+ *   最后一段 `instabox ssh` 没有 `--env`，只能用 `env PATH=…` 前缀。
+ * - 内容全部来自参数（`remotePath` / `autoInstall`），本模块不读 `DEFAULT_CONFIG`；
+ *   也不做 box 存在性预校验：连接失败就是最好的报错（方案 §8.3）。
+ * - 零第三方**运行时**依赖：只用 `node:fs` / `node:path`（宿主类型 `McpServerConfig` 仅 `import type`，
+ *   编译后擦除），且都经注入面（默认实现见 {@link nodeHelperScriptFileSystem}），单测不落真实文件。
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { McpServerConfig } from "@earendil-works/pi-coding-agent";
+import type { InstaboxConfig, InstaboxPaths } from "./config.ts";
+import { logEvent } from "./log.ts";
+
+/**
+ * 远端安装检查的 `instabox exec --timeout`（秒）。
+ *
+ * 真正上界不是 CLI 的 600 秒上限，而是 pi 的 **per-request timeout**
+ * （{@link DEVTOOLS_REQUEST_TIMEOUT_SECONDS} 秒，即注册配置的 `timeout`）：MCP 客户端对
+ * `initialize` 也计时，而 helper 的唤醒/检查/安装全都发生在 `initialize` 应答之前
+ * （`chrome-devtools-mcp` 还没 exec 出来）。所以脚本预算必须小于那个 timeout。
+ */
+const CHECK_TIMEOUT_SECONDS = 10;
+
+/**
+ * 安装本身的 `--timeout`（秒）：`npm i -g` 要拉 tarball，但「检查 + 安装」（10 + 40 = 50 秒）
+ * 仍须和前面的唤醒一起留在 per-request timeout（180 秒）以内——唤醒段每条命令由
+ * `timeout` 封顶 {@link PREPARE_TIMEOUT_SECONDS} 秒（`wake` + `start` 最坏 2 × 60）。
+ */
+const INSTALL_TIMEOUT_SECONDS = 40;
+
+/**
+ * helper 自己拉起箱时的准备阶段上限（秒）：`timeout` 命令包住每条 `instabox wake`/`start`，
+ * 让一条卡住的 CLI 不能把 MCP 握手拖到天荒地老（与 `DEFAULT_CONFIG.timeouts.prepareMs` 的
+ * 1 分钟对齐；本模块不读配置，故在这里单点维护）。
+ *
+ * 它**不是**真正的上界：真正的上界是 pi 的 MCP per-request timeout
+ * （{@link DEVTOOLS_REQUEST_TIMEOUT_SECONDS} 秒）——脚本整个前置段（唤醒 ×2 ＋ 检查 ＋ 安装）
+ * 都在 `initialize` 应答之前跑完。系统里没有 `timeout` 命令时就不包（退回旧行为）。
+ */
+const PREPARE_TIMEOUT_SECONDS = 60;
+
+/** helper 权限位：MCP 的 `command` 被直接 exec，可执行位是硬要求。 */
+const HELPER_MODE = 0o755;
+
+/** MCP server 名：只允许这一种拼写（`instabox_devtools` 与之撞名，方案 C-e）。 */
+const DEVTOOLS_SERVER_NAME = "instabox-devtools";
+
+/**
+ * `registerMcpServer` 的每请求超时（秒）：默认 60 偏紧，桌面/浏览器操作给 180（方案 C-d）。
+ * 它同时是 helper 脚本前置工作（唤醒 2 × {@link PREPARE_TIMEOUT_SECONDS} + 检查
+ * {@link CHECK_TIMEOUT_SECONDS} + 安装 {@link INSTALL_TIMEOUT_SECONDS}，最坏 170 秒）
+ * 的总上界——四者之和必须留在它以内，改小这里必须同步压缩脚本预算。
+ */
+const DEVTOOLS_REQUEST_TIMEOUT_SECONDS = 180;
+
+/** 脚本内的 PATH 变量名：`--env`/`env` 两处都引用它，改字面量只改这里。 */
+const REMOTE_PATH_VAR = "remote_path";
+
+export interface BuildHelperScriptOptions {
+	/** 远端 PATH（来自 `cfg.remotePath`，不硬编码） */
+	remotePath: string;
+	/** 远端缺 `chrome-devtools-mcp` 时是否尝试自动安装（来自 `cfg.autoInstallDevTools`） */
+	autoInstall: boolean;
+}
+
+/**
+ * POSIX 单引号字面量：值内的 `'` 写成 `'\''`。
+ * 脚本里所有配置值插值都走这个函数，避免任何配置值能破出引号。
+ */
+function shSingleQuote(value: string): string {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * 安装命令（远端执行）：`sudo -n env "PATH=<remotePath>"` 把 `--env` 给的 PATH 再显式交给 sudo。
+ *
+ * 理由：sudo 默认按 `secure_path` 重写 PATH，`--env PATH=…` 传进去的 npm 目录可能在 sudo 下丢失，
+ * `sudo -n npm` 就会 "command not found"。**待真机复核**：sandbox 镜像的 sudoers/`secure_path`
+ * 还没在实际 box 上验证过（未复核，属于经验性保险）。
+ */
+function buildInstallCommand(remotePath: string): string {
+	return `sudo -n env "PATH=${remotePath}" npm i -g chrome-devtools-mcp`;
+}
+
+/**
+ * 生成 helper 脚本（纯函数，便于单测断言内容）。
+ *
+ * 脚本职责：`devtools-connect.sh <box> [chrome-devtools-mcp args...]` → 先 `wake`（失败再 `start`）
+ * 拉起箱 → 远端缺包时检查/可选安装 →
+ * `exec instabox ssh <box> -- env PATH=… chrome-devtools-mcp "$@"`，stdout 只留 JSON-RPC。
+ */
+export function buildHelperScript(options: BuildHelperScriptOptions): string {
+	const remotePath = shSingleQuote(options.remotePath);
+	const installBlock = options.autoInstall
+		? `  printf 'instabox-devtools: installing chrome-devtools-mcp on %s\\n' "$box" >&2
+  # sudo 按 secure_path 重写 PATH，故显式再传一次（待真机复核）。
+  instabox exec "$box" --env "PATH=$${REMOTE_PATH_VAR}" --timeout ${INSTALL_TIMEOUT_SECONDS} -- \\
+      sh -c ${shSingleQuote(buildInstallCommand(options.remotePath))} >&2 2>&1 || true`
+		: `  printf 'instabox-devtools: auto-install disabled (autoInstallDevTools=false)\\n' >&2`;
+
+	return `#!/bin/sh
+# devtools-connect.sh —— 由 @inobit/pi-instabox 生成，勿手改（每次加载幂等覆盖）。
+# 用法: devtools-connect.sh <box> [chrome-devtools-mcp args...]
+#
+# stdout 只承载 MCP 的 JSON-RPC 帧，诊断一律写 stderr（否则握手立刻崩）。
+set -eu
+
+if [ "$#" -lt 1 ]; then
+  printf 'usage: devtools-connect.sh <box> [chrome-devtools-mcp args...]\\n' >&2
+  exit 2
+fi
+
+box="$1"
+shift
+${REMOTE_PATH_VAR}=${remotePath}
+
+# 0) 先确保箱在运行：MCP 客户端不会自己唤醒，pi 也不会重连失败的 server。
+#    失败不阻断，让后面的检查/ssh 自然报错。每条唤醒命令包一层 \`timeout\`
+#    （有就用，没有就不加）：准备阶段上限 ${PREPARE_TIMEOUT_SECONDS}s，
+#    真实上界仍是 pi 的 MCP per-request timeout。
+if command -v timeout >/dev/null 2>&1; then TO="timeout ${PREPARE_TIMEOUT_SECONDS}"; else TO=""; fi
+$TO instabox wake "$box" >/dev/null 2>&1 || $TO instabox start "$box" >/dev/null 2>&1 || true
+
+# 远端缺 chrome-devtools-mcp 时最多处理一次；检查与安装失败都不阻断连接，
+# 让真正的 "command not found" 原样冒给 MCP 客户端。
+if ! instabox exec "$box" --env "PATH=$${REMOTE_PATH_VAR}" --timeout ${CHECK_TIMEOUT_SECONDS} -- \\
+    sh -c 'command -v chrome-devtools-mcp >/dev/null 2>&1' >/dev/null 2>&1; then
+  printf 'instabox-devtools: chrome-devtools-mcp missing on %s\\n' "$box" >&2
+${installBlock}
+fi
+
+exec instabox ssh "$box" -- env "PATH=$${REMOTE_PATH_VAR}" chrome-devtools-mcp "$@"
+`;
+}
+
+/**
+ * `pi.registerMcpServer(name, config)` 的 stdio 参数；`exposure` 钉死 `codemode`（方案 §4.3）。
+ *
+ * 本地细化类型，构造点用 `satisfies McpServerConfig` 绑到宿主并集上（见
+ * {@link buildMcpServerConfig}），宿主改字段时这里先报错。
+ */
+export interface DevToolsMcpServerConfig {
+	/** helper 脚本绝对路径 */
+	command: string;
+	/** `[devToolsBox, ...devToolsArgs]` */
+	args: string[];
+	/** 远端工具既不声明给模型、也不进 codemode 描述，脚本用 `searchTools()` 发现（方案 R3） */
+	exposure: "codemode";
+	/** 每请求秒数 */
+	timeout: number;
+	/** 出现在系统提示 `mcp_servers` 段，必须自解释（方案 §4.3 备注） */
+	description: string;
+}
+
+export interface DevToolsMcpServerRegistration {
+	/** server 名（命名空间由此派生为 `mcp__instabox_devtools`） */
+	name: string;
+	config: DevToolsMcpServerConfig;
+}
+
+/**
+ * 构造远端 `chrome-devtools-mcp` 的注册参数。
+ *
+ * `box` 是唯一对应的箱名（flag / 命令解析后传入），缺省沿用 `cfg.devToolsBox`；为空时调用方
+ * 不该调用本函数（该能力整体不存在，方案 §4.3 验收③）。
+ * `args` 每次新建数组，不与 `cfg.devToolsArgs` 共享引用。
+ */
+export function buildMcpServerConfig(
+	cfg: InstaboxConfig,
+	paths: InstaboxPaths,
+	box: string = cfg.devToolsBox,
+): DevToolsMcpServerRegistration {
+	// 双重 satisfies：本地细化类型 + 宿主 `McpServerConfig`（stdio 并集）。宿主增删字段或收窄
+	// `exposure` 时在编译期就炸，而不是留到 `registerMcpServer()` 或运行期。
+	const config = {
+		command: paths.helperScript,
+		args: [box, ...cfg.devToolsArgs],
+		exposure: "codemode",
+		timeout: DEVTOOLS_REQUEST_TIMEOUT_SECONDS,
+		description: `Remote Chromium on instabox '${box}' (fixed box): DOM/accessibility snapshots, clicks, element screenshots, CSS cascade, network, console, performance traces. Tools are not declared directly — discover them with describeNamespace("mcp__instabox_devtools") or searchTools("devtools").`,
+	} satisfies DevToolsMcpServerConfig satisfies McpServerConfig;
+
+	return { name: DEVTOOLS_SERVER_NAME, config };
+}
+
+/** 注入的文件系统：本模块只用这三个动作（不读回内容，覆盖写即是幂等）。 */
+export interface HelperScriptFileSystem {
+	/** `mkdir -p` */
+	ensureDir: (dir: string) => void;
+	/** 覆盖写文本（编码 UTF-8） */
+	writeText: (file: string, text: string) => void;
+	/** 设置权限位 */
+	setMode: (file: string, mode: number) => void;
+}
+
+/** 默认文件系统：`node:fs`（运行期唯一的外部依赖面）。 */
+export const nodeHelperScriptFileSystem: HelperScriptFileSystem = {
+	ensureDir: (dir) => {
+		fs.mkdirSync(dir, { recursive: true });
+	},
+	writeText: (file, text) => {
+		fs.writeFileSync(file, text, "utf8");
+	},
+	setMode: (file, mode) => {
+		fs.chmodSync(file, mode);
+	},
+};
+
+export interface EnsureHelperScriptOptions extends BuildHelperScriptOptions {
+	/** `resolvePaths()` 的返回值；本模块只消费 `helperScript` */
+	paths: Pick<InstaboxPaths, "helperScript">;
+	/** 注入的文件系统，默认 {@link nodeHelperScriptFileSystem} */
+	fs?: HelperScriptFileSystem;
+	/** 失败出口（目录/写盘/权限任何一步失败都只在这里报一次，不 throw） */
+	warn?: (message: string) => void;
+}
+
+export interface EnsureHelperScriptResult {
+	ok: boolean;
+	/** 失败原因（`ok: false` 时必有） */
+	error?: string;
+}
+
+/**
+ * 把 helper 写到 `paths.helperScript`：`mkdir -p` 父目录 → 覆盖写 → `chmod 0o755`。
+ * 三步共用一个 try：任一步失败都只 `warn` 一次并返回 `{ ok: false, error }`。
+ */
+export function ensureHelperScript(options: EnsureHelperScriptOptions): EnsureHelperScriptResult {
+	const file = options.paths.helperScript;
+	const io = options.fs ?? nodeHelperScriptFileSystem;
+	const script = buildHelperScript({ remotePath: options.remotePath, autoInstall: options.autoInstall });
+	try {
+		io.ensureDir(path.dirname(file));
+		io.writeText(file, script);
+		io.setMode(file, HELPER_MODE);
+		logEvent("devtools.helper", { ok: true, path: file });
+		return { ok: true };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		logEvent("devtools.helper", { ok: false, path: file, error: message });
+		options.warn?.(`无法写入 DevTools helper ${file}: ${message}`);
+		return { ok: false, error: message };
+	}
+}

package/src/entry-render.ts

@@ -0,0 +1,42 @@
+/**
+ * @inobit/pi-instabox — 目标 entry 的转录渲染（R5）。
+ *
+ * 宿主的 `EntryRenderer` 必须返回一个 `Component`（`render(width)` + `invalidate()`）：
+ * 返回字符串会被当真组件用而崩。`Text` 的第 4 参是背景色函数、不是 `Theme`，
+ * 所以着色在构造之前用 `theme.fg("dim", line)` 完成，第 4 参永不传。
+ * 工厂注入 `Text` 构造器，单测据此断言构造实参而不真渲染。
+ */
+
+import type { EntryRenderer } from "@earendil-works/pi-coding-agent";
+import { Text as HostText, type Component } from "@earendil-works/pi-tui";
+import { TARGET_ENTRY, type TargetEntryData } from "./session-target.ts";
+
+/** `Text` 构造器的最小形状；第 4 参是背景色函数，本模块永不使用 */
+export type TextConstructor = new (
+  text?: string,
+  paddingX?: number,
+  paddingY?: number,
+  customBgFn?: (text: string) => string,
+) => Component;
+
+/**
+ * 目标 entry 的渲染器工厂。
+ * 只认 `customType === TARGET_ENTRY`，其余条目返回 undefined，交回宿主默认渲染；
+ * `CustomEntry.data` 可缺省，取不到非空箱名时同样返回 undefined（不抛）。
+ */
+export function createTargetRenderer(TextCtor: TextConstructor): EntryRenderer<unknown> {
+  return (entry, _options, theme) => {
+    if (entry.customType !== TARGET_ENTRY) return undefined;
+    const box = (entry.data as Partial<TargetEntryData> | undefined)?.box;
+    if (typeof box !== "string" || box === "") return undefined;
+    return new TextCtor(theme.fg("dim", `instabox target: ${box}`), 0, 0);
+  };
+}
+
+/**
+ * 宿主默认版本：接 pi-tui 的真 `Text`，T15 一行接线：
+ * `pi.registerEntryRenderer(TARGET_ENTRY, createTargetRendererWithHostText())`。
+ */
+export function createTargetRendererWithHostText(): EntryRenderer<unknown> {
+  return createTargetRenderer(HostText);
+}