dsh-switchman 1.5.0 → 1.7.0

package/host/teams.js

@@ -25,6 +25,15 @@
  *   Enforcement is a per-new-session snapshot, so a sync only affects
  *   top-level sessions composed after it.
  *
+ * - The teams-gated `child_message` bridge tool: enabling the agent-team
+ *   bundle REPLACES the global send_message with a team variant that
+ *   resolves TEAMMATE NAMES only, after which subagent child session UUIDs
+ *   are not addressable at all. The bridge restores child addressing through
+ *   ctx.subagents.sendMessage (sender = the exact live calling agent,
+ *   exec.agent), registered while the live `teamsMode` setting reads ON and
+ *   disposed again the moment it reads OFF (same live-reference gating as
+ *   the doctrine section).
+ *
  * Trigger points: plugin apply (applyTeams schedules once), every successful
  * POST /api/dsh-switchman/config (routes.js calls scheduleTeamsOrchestration),
  * and settings/document-updated for this plugin's own namespace (volatile
@@ -398,10 +407,116 @@ function pumpTeamsOrchestration(ctx, config) {
 	scheduleTeamsOrchestration(ctx, config);
 }
 
+// ---- child_message bridge tool ----------------------------------------------
+
+/** Map one ctx.subagents.sendMessage rejection to a readable reason. The
+ *  continuation runtime throws typed SubagentErrors whose stable `code`
+ *  names the failure mode: UNAUTHORIZED (the sender is not the exact live
+ *  agent, or the target is not the sender's direct continuable child /
+ *  direct parent), NOT_RESUMABLE (no continuable session resolves to the
+ *  id), CONTINUATION_UNAVAILABLE (this composition exposes no continuation
+ *  runtime), DRAINING (admission is closing), and ACTIVATION_CLOSING (the
+ *  resident child is mid-disposal). */
+function describeChildMessageError(error) {
+	const message = error?.message ?? String(error);
+	switch (typeof error?.code === "string" ? error.code : "") {
+		case "UNAUTHORIZED":
+			return `wrong sender or lineage: ${message} (childId must be one of your own direct continuable children — teammate names and other agents' children are not addressable here)`;
+		case "NOT_RESUMABLE":
+			return `unknown or non-continuable child: ${message}`;
+		case "CONTINUATION_UNAVAILABLE":
+			return `service unavailable: ${message}`;
+		case "DRAINING":
+			return `continuable subagents are draining: ${message}`;
+		case "ACTIVATION_CLOSING":
+			return `the child is closing: ${message}`;
+		default:
+			return error?.name === "AbortError" ? `cancelled before delivery: ${message}` : message;
+	}
+}
+
+/** WHY this tool exists: enabling the agent-team-profile bundle REPLACES the
+ *  global send_message with a team variant that resolves TEAMMATE NAMES
+ *  only, after which subagent child session UUIDs are not addressable at
+ *  all — background children dispatched before the switch (or recorded by a
+ *  context handover) would become uncollectable silos. This bridge restores
+ *  child addressing through the subagents service's public sendMessage,
+ *  passing the exact live calling agent (exec.agent) as the sender — the
+ *  same authority contract the factory send_message tool uses; the service
+ *  itself validates the sender identity and the direct-child lineage.
+ *  Registration uses the register-level shape (bare ctx.tools.register runs
+ *  no defineTool DSL compilation, so parameters is a full object-root JSON
+ *  Schema), mirroring context-watch.js's ctx_handover tool.
+ *  @returns the registration disposer. */
+function registerChildMessageTool(ctx) {
+	if (typeof ctx.tools?.register !== "function") throw new Error("the tools registry is unavailable");
+	const dispose = ctx.tools.register({
+		name: "child_message",
+		description:
+			"Send a message to one of your subagent child sessions by its session UUID. Needed while Agent Teams mode is active: the team send_message resolves teammate names only, so subagent child ids must go through this bridge. Delivers to a direct continuable child — a running child takes the message at its nearest step boundary, an idle child starts a turn, and an absent continuable child is cold-resumed from persistence. Returns delivery confirmation, not the child's answer.",
+		parameters: {
+			type: "object",
+			properties: {
+				childId: {
+					type: "string",
+					description: "The child session UUID to address (the id returned when the subagent was started).",
+				},
+				content: {
+					type: "string",
+					description: "The message to deliver to the child.",
+				},
+			},
+			required: ["childId", "content"],
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{ type: "text", text: value }],
+		},
+		async execute(args, exec) {
+			const sender = exec?.agent;
+			if (sender === undefined || sender === null)
+				return "child_message failed: no calling agent (exec.agent was undefined) — the subagents service requires the exact live sender.";
+			const childId = typeof args?.childId === "string" ? args.childId.trim() : "";
+			const content = typeof args?.content === "string" ? args.content : "";
+			if (childId === "" || content === "")
+				return "child_message failed: childId and content are required non-empty strings.";
+			const service = ctx.subagents;
+			if (service === undefined || service === null || typeof service.sendMessage !== "function")
+				return "child_message failed: the subagents service is unavailable in this composition.";
+			try {
+				const messageId = await service.sendMessage(
+					sender,
+					childId,
+					[{ type: "text", text: content }],
+					// The service requires options.signal (it calls
+					// throwIfAborted unconditionally); the tool turn's own
+					// signal cancels only pre-acceptance work.
+					{ signal: exec?.signal ?? new AbortController().signal },
+				);
+				return `child_message: message ${messageId} accepted for child ${childId} — a running child takes it at the nearest step boundary, an idle or absent continuable child starts (or cold-resumes into) a turn. This confirms delivery only, not the child's answer.`;
+			} catch (error) {
+				return `child_message failed: ${describeChildMessageError(error)}`;
+			}
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: "Switchman child message",
+			kind: "other",
+			rawInput: args,
+		}),
+	});
+	// If the registry registered the tool but handed back a non-function
+	// disposer, latch a no-op instead of throwing: throwing would leave a
+	// live tool unlatched, and a later retry would register it twice.
+	return typeof dispose === "function" ? dispose : () => {};
+}
+
 /** Mount the teams layer: the dynamic `[SWITCHMAN:TEAMS]` section (empty
- *  while OFF — the live reference makes toggling instant) plus the
- *  orchestration triggers (apply-time scheduling and settings-document
- *  updates for this plugin's own namespace). */
+ *  while OFF — the live reference makes toggling instant), the child_message
+ *  bridge tool (same live teamsMode gating: registered while ON, disposed
+ *  the moment it reads OFF), plus the orchestration triggers (apply-time
+ *  scheduling and settings-document updates for this plugin's own
+ *  namespace). */
 function applyTeams(ctx, config) {
 	ctx.systemPrompt.section({
 		name: "switchman:teams",
@@ -416,15 +531,53 @@ function applyTeams(ctx, config) {
 			}
 		},
 	});
+	// child_message lifecycle: reconcile the registration against the live
+	// teamsMode read (idempotent — a no-op whenever the state already
+	// matches). The closure holds the disposer so every plugin mount starts
+	// clean; the registry entry itself is scope-tracked to this fiber, so a
+	// remount never leaves a stale tool behind. A registration failure only
+	// warns and leaves the state unlatched, and a failed removal keeps the
+	// latch — the next toggle retries either way.
+	let childMessageDispose = null;
+	const syncChildMessageTool = () => {
+		const wanted = readBool(config?.teamsMode) === true;
+		if (wanted === (childMessageDispose !== null)) return;
+		if (!wanted) {
+			// Clear the latch only after a successful dispose: a throwing
+			// disposer keeps the latch set, so the next OFF sync retries the
+			// removal instead of no-oping while the tool stays live.
+			const dispose = childMessageDispose;
+			try {
+				dispose();
+				childMessageDispose = null;
+				ctx.logger?.info?.("dsh-switchman: child_message tool removed (teams mode off)");
+			} catch (error) {
+				ctx.logger?.warn?.(`dsh-switchman: child_message removal failed: ${error?.message ?? error}`);
+			}
+			return;
+		}
+		try {
+			childMessageDispose = registerChildMessageTool(ctx);
+			ctx.logger?.info?.("dsh-switchman: child_message tool registered (teams mode on)");
+		} catch (error) {
+			childMessageDispose = null;
+			ctx.logger?.warn?.(`dsh-switchman: child_message registration failed: ${error?.message ?? error}`);
+		}
+	};
 	// Volatile commits never remount the plugin, so teamsMode/syncWhitelist
 	// (or pool) edits through DSH's OWN settings UI — which bypass our POST
-	// config route — must re-trigger the orchestration too. The settings
-	// service emits this app-wide with no emitting thisArg, so a listener on
-	// this plugin's context receives every namespace's event; filter on ns.
+	// config route — must re-trigger the orchestration (and re-sync the
+	// child_message tool) too. The settings service emits this app-wide with
+	// no emitting thisArg, so a listener on this plugin's context receives
+	// every namespace's event; filter on ns.
 	ctx.on("settings/document-updated", (ns) => {
-		if (ns === SWITCHMAN_SETTINGS_NS) scheduleTeamsOrchestration(ctx, config);
+		if (ns === SWITCHMAN_SETTINGS_NS) {
+			scheduleTeamsOrchestration(ctx, config);
+			syncChildMessageTool();
+		}
 	});
 	scheduleTeamsOrchestration(ctx, config);
+	syncChildMessageTool();
 }
 
 export { applyTeams, pumpTeamsOrchestration, SWITCHMAN_SETTINGS_NS, scheduleTeamsOrchestration, teamsBundleState, teamsSyncSnapshot };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dsh-switchman",
-	"version": "1.5.0",
+	"version": "1.7.0",
 	"description": "Autonomous Agent Teams doctrine for the four shipped DeepSeek Harness presets, plus language preferences, dispatch pools with model ranking, and context watermark control.",
 	"license": "MIT",
 	"keywords": [
@@ -25,7 +25,7 @@
 	"icon": "./icon.svg",
 	"engines": {
 		"node": ">=24",
-		"dsh": ">=0.2.0-rc.0"
+		"dsh": ">=0.2.1-rc.1"
 	},
 	"exports": {
 		".": "./index.js",

package/skills/db-query/package.json

@@ -2,7 +2,7 @@
   "name": "db-query-skill",
   "version": "1.0.0",
   "private": true,
-  "description": "pi 技能：数据库只读查询核验（MySQL / Redis）",
+  "description": "Read-only database query verification skill (MySQL / Redis)",
   "engines": {
     "node": ">=18"
   },

package/skills/db-query/scripts/lib/cli.js

@@ -1,9 +1,9 @@
 'use strict';
 
 /**
- * 严格 CLI 参数解析器
- * 支持 --key=value、--key value、布尔 flag、-- 分隔 SQL/Redis 命令
- * 未知选项、重复冲突、越界数字 → 立即失败（fail-closed）
+ * Strict CLI argument parser
+ * Supports --key=value, --key value, boolean flags, and -- to separate SQL/Redis commands
+ * Unknown options, duplicate conflicts, out-of-range numbers → fail immediately (fail-closed)
  */
 
 class CliError extends Error {
@@ -11,16 +11,16 @@ class CliError extends Error {
 }
 
 /**
- * 解析 CLI 参数，返回 { options: {}, rest: string[] }
+ * Parse CLI arguments and return { options: {}, rest: string[] }
  * @param {string[]} argv - process.argv.slice(2)
- * @param {object} spec - 参数规格 { name: { type, default, min, max, alias } }
+ * @param {object} spec - option spec { name: { type, default, min, max, alias } }
  */
 function parseCli(argv, spec) {
   const options = {};
   const rest = [];
   const seen = new Set();
 
-  // 填充默认值
+  // Fill in defaults
   for (const [key, def] of Object.entries(spec)) {
     if (def.default !== undefined) options[key] = def.default;
   }
@@ -29,13 +29,13 @@ function parseCli(argv, spec) {
   while (i < argv.length) {
     const arg = argv[i];
 
-    // -- 分隔符：后续全部作为位置参数
+    // -- separator: everything after it is positional
     if (arg === '--') {
       rest.push(...argv.slice(i + 1));
       break;
     }
 
-    // --option=value 或 --option value 形式
+    // --option=value or --option value form
     if (arg.startsWith('--')) {
       let key, value;
       const eqIdx = arg.indexOf('=');
@@ -44,29 +44,29 @@ function parseCli(argv, spec) {
         value = arg.slice(eqIdx + 1);
       } else {
         key = arg.slice(2);
-        // 查找规格中该选项的类型
+        // Look up the option's type in the spec
         const s = findSpec(spec, key);
-        if (!s) throw new CliError(`未知选项: --${key}`);
+        if (!s) throw new CliError(`Unknown option: --${key}`);
         if (s.type === 'boolean') {
           value = true;
         } else {
           i++;
-          if (i >= argv.length) throw new CliError(`--${key} 需要值`);
+          if (i >= argv.length) throw new CliError(`--${key} requires a value`);
           value = argv[i];
         }
       }
 
       const resolved = resolveAlias(spec, key);
-      if (!resolved) throw new CliError(`未知选项: --${key}`);
+      if (!resolved) throw new CliError(`Unknown option: --${key}`);
 
-      // 重复选项检查
-      if (seen.has(resolved)) throw new CliError(`重复选项: --${resolved}`);
+      // Duplicate option check
+      if (seen.has(resolved)) throw new CliError(`Duplicate option: --${resolved}`);
       seen.add(resolved);
 
       const s = spec[resolved];
       options[resolved] = coerceValue(resolved, value, s);
     } else {
-      // 非选项参数 → 位置参数
+      // Non-option argument → positional
       rest.push(arg);
     }
     i++;
@@ -75,7 +75,7 @@ function parseCli(argv, spec) {
   return { options, rest };
 }
 
-/** 在 spec 或 alias 中查找选项名 */
+/** Find an option name in the spec or its aliases */
 function findSpec(spec, key) {
   if (spec[key]) return spec[key];
   for (const s of Object.values(spec)) {
@@ -84,7 +84,7 @@ function findSpec(spec, key) {
   return null;
 }
 
-/** 解析别名到规范名 */
+/** Resolve an alias to its canonical name */
 function resolveAlias(spec, key) {
   if (spec[key]) return key;
   for (const [name, s] of Object.entries(spec)) {
@@ -93,23 +93,23 @@ function resolveAlias(spec, key) {
   return null;
 }
 
-/** 类型转换 + 边界检查 */
+/** Type coercion + bounds checking */
 function coerceValue(key, raw, spec) {
   if (spec.type === 'boolean') {
     if (raw === 'true' || raw === true) return true;
     if (raw === 'false' || raw === false) return false;
-    throw new CliError(`--${key} 期望布尔值，收到: ${raw}`);
+    throw new CliError(`--${key} expects a boolean, got: ${raw}`);
   }
   if (spec.type === 'integer') {
     const n = Number(raw);
-    if (!Number.isInteger(n)) throw new CliError(`--${key} 期望整数，收到: ${raw}`);
-    if (spec.min !== undefined && n < spec.min) throw new CliError(`--${key} 最小值 ${spec.min}，收到: ${n}`);
-    if (spec.max !== undefined && n > spec.max) throw new CliError(`--${key} 最大值 ${spec.max}，收到: ${n}`);
+    if (!Number.isInteger(n)) throw new CliError(`--${key} expects an integer, got: ${raw}`);
+    if (spec.min !== undefined && n < spec.min) throw new CliError(`--${key} minimum is ${spec.min}, got: ${n}`);
+    if (spec.max !== undefined && n > spec.max) throw new CliError(`--${key} maximum is ${spec.max}, got: ${n}`);
     return n;
   }
   if (spec.type === 'string' && spec.choices) {
     const lower = String(raw).toLowerCase();
-    if (!spec.choices.includes(lower)) throw new CliError(`--${key} 必须为 ${spec.choices.join('|')} 之一，收到: ${raw}`);
+    if (!spec.choices.includes(lower)) throw new CliError(`--${key} must be one of ${spec.choices.join('|')}, got: ${raw}`);
     return lower;
   }
   return String(raw);

package/skills/db-query/scripts/lib/config.js

@@ -1,39 +1,43 @@
 'use strict';
 
 /**
- * 配置解析：env 文件 / 环境变量 / 脱敏 / 安全错误格式化
- * dotenv 只用 parse()，不污染 process.env；POSIX 下检查 env 文件权限
+ * Configuration: env file / environment variables / sanitizing / safe error formatting
+ * Only dotenv.parse() is used so process.env stays untouched; env file
+ * permissions are checked on POSIX
  */
 
 const fs = require('fs');
 const path = require('path');
 const dotenv = require('dotenv');
 
-// ── env 文件加载（不污染 process.env）──
+// ── Env file loading (does not touch process.env) ──
 
 /**
- * 加载指定 env 文件，返回键值对
- * 不读 cwd 的 .env，防止意外泄露；group/other 可读时直接拒绝（凭据安全）
- * @param {string|undefined} envFile - env 文件路径
- * @returns {object} 键值对
+ * Load the given env file and return key/value pairs
+ * Never reads .env from cwd to avoid accidental leaks; rejects outright when
+ * group/other can read it (credential safety)
+ * @param {string|undefined} envFile - env file path
+ * @returns {object} key/value pairs
  */
 function loadEnvFile(envFile) {
   if (!envFile) return {};
   const resolved = path.resolve(envFile);
   if (!fs.existsSync(resolved)) {
-    throw new Error(`env 文件不存在: ${resolved}`);
+    throw new Error(`Env file not found: ${resolved}`);
   }
 
-  // POSIX 下检查 group/other 权限：同机其他用户可读即泄露密码，直接拒绝
+  // Check group/other permissions on POSIX: if other local users can read the
+  // file the password leaks — reject outright
   try {
     const stat = fs.statSync(resolved);
     // eslint-disable-next-line no-bitwise
     if ((stat.mode & 0o077) !== 0) {
-      throw new ConfigError(`env 文件 ${resolved} 权限过宽（group/other 可访问），请 chmod 600`);
+      throw new ConfigError(`Env file ${resolved} permissions too broad (accessible by group/other), run chmod 600`);
     }
   } catch (e) {
-    // 仅跳过 Windows 等非 POSIX 系统的权限检查错误；其余错误（权限过宽）往上抛
-    if (e.message.includes('权限过宽')) throw e;
+    // Only skip the permission-check error on Windows and other non-POSIX
+    // systems; rethrow everything else (permissions too broad)
+    if (e.message.includes('permissions too broad')) throw e;
   }
 
   const content = fs.readFileSync(resolved, 'utf8');
@@ -41,28 +45,30 @@ function loadEnvFile(envFile) {
 }
 
 /**
- * 按 SKILL.md 优先级读取配置值：CLI > env 文件 > 进程环境变量 > undefined
- * @param {object} envPairs - dotenv.parse() 结果（显式 --env-file，权限受控）
- * @param {string} envKey - 环境变量名（如 DB_QUERY_MYSQL_HOST）
- * @param {*} cliValue - CLI 传入的值；undefined 表示 CLI 未指定
- * @returns {*} CLI 优先，其次 env 文件，再次进程环境变量，否则 undefined
+ * Read a config value with SKILL.md precedence: CLI > env file > process env > undefined
+ * @param {object} envPairs - dotenv.parse() result (explicit --env-file, permission-controlled)
+ * @param {string} envKey - environment variable name (e.g. DB_QUERY_MYSQL_HOST)
+ * @param {*} cliValue - value from the CLI; undefined means not given on the CLI
+ * @returns {*} CLI first, then env file, then process env, otherwise undefined
  */
 function resolveEnv(envPairs, envKey, cliValue) {
   if (cliValue !== undefined) return cliValue;
-  // env 文件优先（显式指定、权限受控 0600），其次进程环境变量
-  // （loadEnvFile 刻意不污染 process.env，必须在此显式读取兜底，否则 export DB_QUERY_* 不生效）
+  // Env file first (explicitly given, permission-controlled 0600), then the
+  // process environment (loadEnvFile deliberately leaves process.env
+  // untouched, so fall back to it here or `export DB_QUERY_*` would not work)
   if (envPairs[envKey] !== undefined) return envPairs[envKey];
   if (process.env[envKey] !== undefined) return process.env[envKey];
   return undefined;
 }
 
 /**
- * 从 env/CLI 解析数值并校验 min/max 边界
- * 所有来源（CLI / env 文件 / 环境变量）统一跑边界检查，防止 env 文件绕过硬上限
+ * Parse a number from env/CLI and validate min/max bounds
+ * Every source (CLI / env file / environment) runs the same bounds check so
+ * an env file cannot bypass hard limits
  *
- * @param {object} envPairs - dotenv.parse() 结果
- * @param {string} envKey - 环境变量名
- * @param {*} cliValue - CLI 传入的值（已由 cli.js 做过边界校验）
+ * @param {object} envPairs - dotenv.parse() result
+ * @param {string} envKey - environment variable name
+ * @param {*} cliValue - value from the CLI (bounds already checked by cli.js)
  * @param {object} bounds - { min?: number, max?: number }
  * @returns {number}
  */
@@ -71,29 +77,31 @@ class ConfigError extends Error {
 }
 
 function resolveEnvNumber(envPairs, envKey, cliValue, bounds) {
-  // CLI 来源：cli.js 的 coerceValue 已做过边界检查，直接返回
+  // CLI source: cli.js coerceValue already checked the bounds, return as-is
   if (cliValue !== undefined) return cliValue;
-  // env 文件优先，其次进程环境变量（与 resolveEnv 优先级一致，符合 SKILL.md 承诺）；
-  // env 来源的值需统一解析 + 边界校验，防止 env 绕过硬上限
+  // Env file first, then process env (same precedence as resolveEnv, per the
+  // SKILL.md contract); env-sourced values are parsed and bounds-checked
+  // uniformly so env cannot bypass hard limits
   const raw = envPairs[envKey] !== undefined ? envPairs[envKey] : process.env[envKey];
   if (raw === undefined) return undefined;
   const n = Number(raw);
   if (!Number.isInteger(n)) {
-    throw new ConfigError(`环境变量 ${envKey}=${raw} 不是合法整数`);
+    throw new ConfigError(`Environment variable ${envKey}=${raw} is not a valid integer`);
   }
   if (bounds && bounds.min !== undefined && n < bounds.min) {
-    throw new ConfigError(`环境变量 ${envKey}=${n} 低于最小值 ${bounds.min}`);
+    throw new ConfigError(`Environment variable ${envKey}=${n} is below the minimum ${bounds.min}`);
   }
   if (bounds && bounds.max !== undefined && n > bounds.max) {
-    throw new ConfigError(`环境变量 ${envKey}=${n} 超过最大值 ${bounds.max}`);
+    throw new ConfigError(`Environment variable ${envKey}=${n} exceeds the maximum ${bounds.max}`);
   }
   return n;
 }
 
-// ── 连接目标脱敏 ──
+// ── Connection target sanitizing ──
 
 /**
- * 生成脱敏的连接目标信息，绝不包含密码或含密码 URI
+ * Build sanitized connection target info; never includes the password or a
+ * password-bearing URI
  * @param {object} opts - { host, port, user, database }
  * @returns {string}
  */
@@ -104,14 +112,16 @@ function sanitizeTarget(opts) {
   return parts.join(', ');
 }
 
-// ── 安全错误格式化 ──
+// ── Safe error formatting ──
 
-// 屏蔽 URL/连接串里内联的密码（://user:password@host → ://user:***@host）。
-// 用户名段用 * 以覆盖 redis 无用户名的标准形式（://:password@host），防御性脱敏
+// Mask passwords inlined in URLs/connection strings (://user:password@host → ://user:***@host).
+// The username segment uses * to also cover the standard no-username Redis
+// form (://:password@host); defensive sanitizing
 const URL_CRED_PATTERN = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/\s:@]*:)[^/\s@]+(@)/g;
 
 /**
- * 取错误 message 首行，脱敏截断：屏蔽内联凭据 + 截断到 200 字符防意外泄露
+ * Take the first line of an error message, sanitized and truncated: mask
+ * inline credentials + cut at 200 chars to prevent accidental leaks
  * @param {string} s
  * @returns {string}
  */
@@ -121,27 +131,28 @@ function sanitizeErrorLine(s) {
   return masked.length > 200 ? masked.slice(0, 200) + '…' : masked;
 }
 
-// 连接/认证/握手阶段错误码 —— 归为「连接失败」，明确区分于查询执行错误
+// Connection/auth/handshake error codes — classified as "connection failure",
+// clearly distinct from query execution errors
 const CONNECTION_CODES = new Set([
-  // Node 网络与系统错误
+  // Node network and system errors
   'ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND',
   'EHOSTUNREACH', 'ENETUNREACH', 'EPIPE', 'ECONNABORTED', 'EDESTADDRREQ',
-  // DNS 解析错误
+  // DNS resolution errors
   'EAI_AGAIN', 'EAI_NONAME', 'EAI_SERVICE', 'EAI_FAIL', 'EAI_BADFLAGS',
-  // TLS 错误
+  // TLS errors
   'ERR_TLS_CERT_ALTNAME_INVALID', 'CERT_HAS_EXPIRED',
   'DEPTH_ZERO_SELF_SIGNED_CERT', 'ERR_TLS_INVALID_PROTOCOL_METHOD',
   'ERR_TLS_PROTOCOL_VERSION_CONFLICT',
-  // mysql2 连接/握手/选库阶段
+  // mysql2 connection/handshake/db-selection stage
   'HANDSHAKE_ERROR', 'PROTOCOL_CONNECTION_LOST',
   'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR', 'PROTOCOL_SEQUENCE_TIMEOUT',
   'ER_ACCESS_DENIED_ERROR', 'ER_DBACCESS_DENIED_ERROR',
   'ER_BAD_DB_ERROR', 'ER_BAD_HOST_ERROR',
-  // Redis 认证阶段
+  // Redis auth stage
   'WRONGPASS', 'NOAUTH',
 ]);
 
-// node-redis 命令执行阶段错误码（与连接阶段区分）
+// node-redis command execution error codes (distinct from the connection stage)
 const REDIS_EXEC_CODES = new Set([
   'ERR', 'WRONGTYPE', 'WRONGINT', 'WRONGBIT', 'WRONGKEY',
   'EXECABORT', 'NOREPLICAS', 'MISCONF', 'BUSYGROUP', 'NOGROUP',
@@ -150,14 +161,18 @@ const REDIS_EXEC_CODES = new Set([
 ]);
 
 /**
- * 安全地格式化数据库错误，让排障 agent 能立刻看清真正的失败原因。
+ * Format a database error safely so a triaging agent can see the real failure
+ * at a glance.
  *
- * 关键安全前提：mysql2 的 ER_* / node-redis 的命令错误，其 message 来自
- * 数据库服务端，不含客户端凭据（服务端不感知客户端密码）；Node 网络错误
- * message 形如 "connect ECONNREFUSED 127.0.0.1:3306" 也不含密码。因此按
- * code 分类后暴露 code + message 首行（已脱敏截断）是安全的，且能让 agent
- * 一次区分「连不上」还是「SQL 写错」，避免无效的二分排查。
- * 仅对「既无 code 也无 message」的极端异常给中性兜底，且不再误报成「连接失败」。
+ * Key security premise: messages of mysql2 ER_* / node-redis command errors
+ * come from the database server and contain no client credentials (the server
+ * never sees the client password); Node network errors such as
+ * "connect ECONNREFUSED 127.0.0.1:3306" contain no password either. So
+ * exposing the code plus the sanitized first message line, classified by
+ * code, is safe and lets the agent tell "cannot connect" from "bad SQL" in
+ * one step, avoiding pointless bisection. Only pathological errors with
+ * neither code nor message get a neutral fallback, no longer misreported as
+ * "connection failure".
  * @param {Error} err
  * @returns {string}
  */
@@ -168,29 +183,31 @@ function safeMessage(err) {
   if (code) {
     const codeStr = String(code);
     if (CONNECTION_CODES.has(codeStr)) {
-      return `连接失败 [${codeStr}]: ${line}`;
+      return `Connection failed [${codeStr}]: ${line}`;
     }
-    // mysql2 服务端执行错误：ER_BAD_FIELD_ERROR(1054)/ER_PARSE_ERROR/ER_NO_SUCH_TABLE 等
+    // mysql2 server-side execution errors: ER_BAD_FIELD_ERROR(1054)/ER_PARSE_ERROR/ER_NO_SUCH_TABLE etc.
     if (/^ER_/.test(codeStr)) {
-      return `查询执行错误 [${codeStr}]: ${line}`;
+      return `Query execution error [${codeStr}]: ${line}`;
     }
-    // node-redis 命令执行错误
+    // node-redis command execution errors
     if (REDIS_EXEC_CODES.has(codeStr)) {
-      return `查询执行错误 [${codeStr}]: ${line}`;
+      return `Query execution error [${codeStr}]: ${line}`;
     }
-    // 未知 code：仍暴露 code + 首行（已脱敏截断），比「详情已隐藏」更利于排障
+    // Unknown code: still expose code + first line (sanitized and
+    // truncated); more useful for triage than "details hidden"
     return `[${codeStr}] ${line}`;
   }
 
-  // 无 code：无法分类，给中性措辞，不再误导成「连接失败」
+  // No code: cannot classify, use neutral wording instead of a misleading
+  // "connection failure"
   const name = err.name || 'Error';
-  return `${name}: ${line || '（无错误信息，请检查 SQL/命令与连接参数）'}`;
+  return `${name}: ${line || '(no error message; check the SQL/command and connection parameters)'}`;
 }
 
-// ── TLS 选项构建 ──
+// ── TLS options ──
 
 /**
- * 从 ca-file 路径构建 TLS 选项
+ * Build TLS options from a ca-file path
  * @param {string|undefined} caFile
  * @returns {object|undefined}
  */
@@ -198,7 +215,7 @@ function buildTlsOptions(caFile) {
   if (!caFile) return undefined;
   const resolved = path.resolve(caFile);
   if (!fs.existsSync(resolved)) {
-    throw new Error(`CA 证书文件不存在: ${resolved}`);
+    throw new Error(`CA certificate file not found: ${resolved}`);
   }
   const ca = fs.readFileSync(resolved);
   return { ca, rejectUnauthorized: true };