huaweicloud-devkit 1.1.13-next.0 → 1.1.13-next.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "huaweicloud-devkit",
   "mcpName": "io.github.huaweicloud/huaweicloud-devkit",
-  "version": "1.1.13-next.0",
+  "version": "1.1.13-next.2",
   "kooCliVersion": "7.3.12",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",

package/plugins/huaweicloud-core/.claude-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.13-next.0",
+  "version": "1.1.13-next.2",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.codex-plugin/plugin.json

@@ -20,7 +20,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "skills": "./skills/",
-  "version": "1.1.13-next.0",
+  "version": "1.1.13-next.2",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.cursor-plugin/plugin.json

@@ -17,7 +17,7 @@
   "mcpServers": "./.mcp.json",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "skills": "./skills/",
-  "version": "1.1.13-next.0",
+  "version": "1.1.13-next.2",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.hermes-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.13-next.0",
+  "version": "1.1.13-next.2",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/.workbuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.1.13-next.0",
+  "version": "1.1.13-next.2",
   "description": "Guide coding agents to use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities with safer execution and less context.",
   "author": {
     "name": "HuaweiCloud Mate",

package/plugins/huaweicloud-core/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "name": "huaweicloud-devkit",
   "id": "huaweicloud-devkit",
   "displayName": "HuaweiCloud DevKit",
-  "version": "1.1.13-next.0",
+  "version": "1.1.13-next.2",
   "family": "bundle-plugin",
   "bundleFormat": "codex",
   "description": "Guide coding agents to use Huawei Cloud safely — KooCLI, APIs, SDKs, 28 MCP tools, skills, and safety guardrails.",

package/plugins/huaweicloud-core/skills/huawei-sandbox/SKILL.md

@@ -47,6 +47,36 @@ Hard rules:
 
 Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace terminal execution. Covers sandbox lifecycle via hdkitservice API and remote terminal command execution via hwlink protocol.
 
+## 两池沙箱（pool_type）
+
+> 口径基调：一切以实测为准，口头支持不作数（下表生命周期为实测/平台侧现状，平台调参后本节随之更新）。
+
+`huaweicloud_sandbox_connect` 用 `pool_type` 选择资源池（服务端权威映射模板；**没有 persist_mode 参数**——上游参数面仅 template_id/flavor_id）：
+
+| pool_type           | 语义               | 生命周期（已实测）                                         | 适用                        |
+| ------------------- | ------------------ | ---------------------------------------------------------- | --------------------------- |
+| `ephemeral`（默认） | 非持久沙箱         | 闲置 30 分钟自动关机 + 闲置 1 小时自动删除（平台定时任务） | 临时运行/预览，勿存重要数据 |
+| `persistent`        | 持久沙箱（EVS 盘） | 数据跨关机保留；闲置回收保留期上限 7 天                    | 需要跨会话保留数据          |
+
+Selection rules（agent 按意图自动选池，开发者可覆盖；意图不明确时呈现两类供选择）：
+
+| 意图 / 场景               | pool_type  | 理由                                |
+| ------------------------- | ---------- | ----------------------------------- |
+| 预览 / 试用 / demo        | ephemeral  | 用完即弃，无需保留状态              |
+| 一次性任务（跑完即弃）    | ephemeral  | 结果带出沙箱；实例随闲置回收        |
+| 敏感内容（即焚）          | ephemeral  | 闲置 1 小时自动删除，数据随实例消亡 |
+| 开发工作台 / workbench    | persistent | 会话跨天；状态需跨关机保留          |
+| 带数据库项目（DB-backed） | persistent | 数据落在挂载的 EVS 盘（32G）        |
+| 跨日评审 / 展示           | persistent | 评审者后续日期回访；实例保留        |
+
+- **配额**：每用户每类型 1 台（1+1 可并存）；同池 connect 自动复用已有实例
+- **429 双错误码**：`HDKIT_QUOTA_EXCEEDED`（账号配额满，重试无效→引导释放/复用）；`HDKIT_CAPACITY_INSUFFICIENT`（池容量不足→建议错峰重试）。响应带 `Retry-After`
+- **TTL 播报**：connect 与执行类工具返回值带池模式/生命周期提示——**ephemeral 池部署的公网地址会随沙箱闲置关机失效**，向开发者交付 URL 时必须附带该提示
+- **烧核播报口径**：沙箱运行消耗核时，播报用「平台赠送 + 活动赚取」口径（非直接计费）；账号核时耗尽（`HD.97520422`）时工具返回值给出友好引导
+- **删除纪律**：不向开发者暴露生命周期删除 API（回收走平台闲置策略 G1）；开发者主动删除时必须二次确认（确认要删除？数据不可恢复）；绝不做延后代删
+- 显式 `template_id` 优先于 `pool_type`（自定义模板场景）
+- 完整口径、容量规划与 G 清单：[references/resource-pool.md](references/resource-pool.md)
+
 ## Activation
 
 - **Proactive offering**: when the developer's task needs a temporary runtime (e.g. "deploy this web app", "run this app and preview it"), offer the sandbox proactively — the developer never has to say "use sandbox". Prompt: "This task can be satisfied by a sandbox — use it?"
@@ -74,10 +104,10 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 
 ### Sandbox Lifecycle
 
-| Tool                              | Purpose                                                                  |
-| --------------------------------- | ------------------------------------------------------------------------ |
-| `huaweicloud_sandbox_connect`     | Connect to sandbox (one user one instance, reuses existing if available) |
-| `huaweicloud_sandbox_credentials` | Inject temporary AK/SK into a running sandbox                            |
+| Tool                              | Purpose                                                                                                          |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `huaweicloud_sandbox_connect`     | Connect to sandbox (one instance per user per pool; `pool_type` selects ephemeral/persistent, default ephemeral) |
+| `huaweicloud_sandbox_credentials` | Inject temporary AK/SK into a running sandbox                                                                    |
 
 ### Tunnel Persistence (public URL lifetime)
 
@@ -133,6 +163,8 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 
 **Step 0 — Target-Selection Gate (MANDATORY)**: before any sandbox lifecycle tool, confirm the target. If the developer asked to deploy/host/publish a site without naming a target, STOP and run the [Target-Selection Gate](#target-selection-gate-mandatory--do-not-skip) first; do NOT call `huaweicloud_sandbox_connect` until it is resolved. Proceed with this workflow only if the target is already confirmed as sandbox (or a temporary runtime).
 
+**Step 0.3 — Resource pool selection**: once the target is sandbox, pick the pool type per the [两池沙箱（pool_type）](#两池沙箱pool_type) selection rules (auto by intent, developer may override; 1 instance per type, same type reuses). Check the task survives the chosen type's lifecycle window (ephemeral: idle 30min shutdown + 1h delete; persistent: 7-day idle reclaim cap) before connecting.
+
 **Step 0.5 — Stack-Selection Gate (MANDATORY)**: before uploading or writing any application code, confirm the backend stack via the [Stack-Selection Gate](#stack-selection-gate-mandatory--do-not-skip). 工作台/workbench/全栈/full-stack/CRUD/持久化 ⇒ full-stack (PostgreSQL + PostgREST default) — do NOT start an SPA-only deployment for a workbench request.
 
 Setup is a **plugin-side preflight** — the developer should be asked a question only once, when the agreement actually needs signing:
@@ -1049,6 +1081,7 @@ Returns `complete: true/false`, `score`, and `nextStep` to fix missing items.
 
 - [Framework Commands](references/framework-commands.md) — command mapping for all supported frameworks
 - [Nginx Templates](references/nginx-templates.md) — nginx configuration templates and fallback
+- [Resource Pool](references/resource-pool.md) — 资源池定稿口径：两沙箱类型、申请/限流参数（持久 2U4G×300 + 4U8G×200、非持久 2U4G×1000、overlayer 5GB/实例、EVS 300TB）、配额 1/类型 与 429+Retry-After 语义
 
 ## Critical Warnings
 

package/plugins/huaweicloud-core/skills/huawei-sandbox/references/resource-pool.md

@@ -0,0 +1,77 @@
+# 两池沙箱资源池口径（v3，2026-11 定稿）
+
+> 权威实现：hdkitservice（pool_type 服务端权威解析 + 池感知复用 + 429 双错误码）+ 本插件 `sandbox-pool.mjs`。
+> 本文件是口径快照，与实现冲突时以最新实测为准（基调：一切以实测为准，口头支持不作数）。
+> 本版合并并取代 #1071 旧口径（非持久 3h 固定 / 持久 14 天保留 / 三信号 / 关机前通知均已作废）。
+
+## 机制
+
+- **池 = 平台预置模板**：非持久 `9a108ab1bc354bc4979b949b36e3c8c1` / 持久 `05860f507ee94930844907a3a136d1a7` / flavor 3U6G `23ebdfe3b2d34cc4b34a1aaf03d27c54`（服务端 `POOL_TEMPLATE_*` 环境变量维护）
+- 客户端传 `pool_type`（ephemeral/persistent），**服务端权威映射** template_id；显式 `template_id` 优先（自定义模板）
+- **无 persist_mode 请求参数**（需求方两次纠正）；闲置语义由平台按模板配置，上游参数面仅 name/template_id/flavor_id/source/env/git
+- 实例名前缀即池归属：`hcdke*`（非持久）/ `hcdkp*`（持久）；同池才复用。遗留 `hcdk*` 老实例不参与池复用（老模板后续可能无对应资源池，处置待定）
+
+## 两类沙箱
+
+| 维度     | 非持久化 (ephemeral)                    | 持久化 (persistent)                          |
+| -------- | --------------------------------------- | -------------------------------------------- |
+| 定位     | 预览/试用/一次性任务/敏感即焚           | 开发工作台/带数据库项目/跨日评审展示         |
+| 生命周期 | 闲置 30min 自动关机 + 1h 删除（已实测） | 闲置回收保留期上限 7 天（资源组 DB 硬约束）  |
+| 存储     | 无持久盘                                | 挂 EVS 32G                                   |
+| 配额     | 每用户 1 台（同类复用）                 | 每用户 1 台（同类复用；可与 1 台非持久并存） |
+
+## 生命周期（实测口径）
+
+| 项              | 口径                                           | 状态          |
+| --------------- | ---------------------------------------------- | ------------- |
+| 非持久闲置策略  | 30min 自动关机 + 1h 删除（平台定时任务）       | ✅ 已验证生效 |
+| 持久闲置回收    | 保留期上限 7 天（原 14 天口径作废）            | 平台侧        |
+| 活性检测        | 当前仅 connect 单信号（三信号为后续诉求 G2）   | 现状          |
+| 删除/关机前通知 | 不支持（G6 诉求中）→ 客户端 TTL 播报为补偿方案 | 现状          |
+| 两池实际差异    | 仅 EVS 32GiB 数据盘（非持久池无 disks 字段）   | ✅ 已实证     |
+
+## 容量规划（原始申请口径）
+
+| 资源              | 申请容量    |
+| ----------------- | ----------- |
+| 非持久化 2U4G     | 1000 实例   |
+| 持久化 2U4G       | 300 实例    |
+| 持久化 4U8G       | 200 实例    |
+| overlayer         | 5 GB / 实例 |
+| EVS（持久化挂盘） | 300 TB 总量 |
+
+> 注意：实际池 flavor 为 **3U6G**（需求方 2026-11-02 指定，尾号 54），上述 2U4G/4U8G 为原始申请口径，容量数字需按 3U6G 重新核算。
+
+## 配额与错误码
+
+- 每用户每类型 1 台（同类复用，ephemeral + persistent 可并存 1+1）；账号并发上限 5
+- 429 双错误码（均带 `Retry-After: 60`）：
+  - `HDKIT_QUOTA_EXCEEDED`：用户配额满（上游 `HD.98320022`）→ 重试无效，引导释放/复用已有实例
+  - `HDKIT_CAPACITY_INSUFFICIENT`：池容量不足（上游 `HD.99003001`/`HD.99008001`/`HD.98330021`）→ 建议错峰重试
+- 烧核：`HD.97520422` = 账号核心时长耗尽（沙箱运行消耗核时；客户端对含该码的错误输出友好播报）
+
+## 烧核播报口径
+
+沙箱消耗核时（烧核）时向用户播报：核时来源于**平台赠送 + 活动赚取**（非直接计费口径）。
+
+## 客户端行为（本插件）
+
+- `sandbox_connect` 传 `pool_type`；非法值本地即报错（不发无效请求）；未传由服务端默认 ephemeral
+- connect 返回值富化 `pool` 块（TTL 播报，仅服务端回显 pool_type 时）；exec/upload/deploy/expose 返回值带 `poolMode`/`persistenceHint`
+- 429 结构化 `remediation`（配额满/容量不足差异化引导步骤）+ `retryAfter`
+- 钉扎（可选，运维场景）：`HW_POOL_TEMPLATE_EPHEMERAL`/`HW_POOL_TEMPLATE_PERSISTENT` 环境变量——设置后客户端附带映射 template_id 上送；日常部署无需配置（模板 ID 由服务端权威维护）
+
+## 平台侧关键依赖（G 清单，非 devkit 交付）
+
+- G1 闲置删除策略配置（资源组，驱动 7 天上限回收）
+- G2 活性检测（当前仅 connect 单信号；三信号为后续诉求）
+- G3 状态查询 API（未落地，继续提）
+- G4 销户开机处置（已完成待测试）
+- G5 销户实例回收（已完成待测试）
+- G6 删除/关机前通知（诉求中）
+
+## 已知边界
+
+- 池模板当前为**白名单条件实测**（仅对测试账号加白），公开上线后需复测模板 ID 与口径
+- 上游 429 真实响应结构未实测：服务端映射先按已知错误码实现，联调实测后校准
+- 沙箱实例状态机外的过渡态（`cde.1000/1002` 排队中）由服务端等待超时兜底

package/plugins/huaweicloud-core/src/sandbox/hdkitservice-api.mjs

@@ -3,6 +3,7 @@ import { getProxyDispatcher } from '../proxy/proxy-agent.mjs';
 import { cacheUserHash } from '../telemetry/telemetry.mjs';
 import { detectAgent } from '../telemetry/agent-detect.mjs';
 import { readInstalledVersion } from '../update-check.mjs';
+import { pinnedTemplateFor } from './sandbox-pool.mjs';
 
 function getHdkitBaseUrl() {
   return process.env.HDKITSERVICE_ENDPOINT || 'https://devkit.huaweicloud.com/rest/developer/server/hdkitservice/';
@@ -78,6 +79,43 @@ async function hdkitRequest(method, path, body, timeoutMs = 300000) {
         ],
       };
     }
+    // 429 双错误码结构化处理（两池配额契约）：配额满（用户侧，重试无效）与
+    // 池容量不足（平台侧，错峰重试）给出差异化引导；携带服务端 Retry-After
+    if (code === 'HDKIT_QUOTA_EXCEEDED') {
+      err.retryAfter = resp.headers.get('Retry-After') || undefined;
+      err.remediation = {
+        hint: '沙箱并发配额已满（每账号最多 5 台、每类型 1 台），重试无效：',
+        steps: [
+          '确认已有实例是否够用：connect 对同池实例自动复用，无需重复创建',
+          '释放不再使用的沙箱（控制台或平台回收）后重试',
+          '如需两种生命周期语义并存：ephemeral 与 persistent 各可持有 1 台',
+        ],
+      };
+    }
+    if (code === 'HDKIT_CAPACITY_INSUFFICIENT') {
+      err.retryAfter = resp.headers.get('Retry-After') || undefined;
+      err.remediation = {
+        hint: '平台池容量暂时不足（非账号问题）：',
+        steps: [
+          '稍后错峰重试（devkit提供的免费资源紧张，建议错峰使用）',
+          '急需使用时可尝试另一 pool_type（另一池可能有余量）',
+        ],
+      };
+    }
+    // 烧核播报（缺口#5 代码层）：账号核心时长耗尽——上游码 HD.97520422 经
+    // hdkitservice 以 HDKIT_UPSTREAM_ERROR 包装透传，客户端按消息内错误码识别。
+    // 仅在前面的分支未设置 remediation 时生效（else-if 语义：烧核不覆盖 429 双码/凭证指引）
+    if (!err.remediation && String(data.message || '').includes('HD.97520422')) {
+      err.coreHoursExhausted = true;
+      err.remediation = {
+        hint: '账号核心时长（核时）已耗尽，沙箱无法继续运行：',
+        steps: [
+          '核时按沙箱运行时长消耗，当前账号余额为 0',
+          '更换有核时余额的账号，或等待/申请核时补充',
+          '详见华为云开发者空间核心时长说明',
+        ],
+      };
+    }
     throw err;
   }
 
@@ -107,6 +145,13 @@ export async function hdkitConnect(options = {}) {
   if (options.git) body.git = options.git;
   if (options.template_id) body.template_id = options.template_id;
   if (options.flavor_id) body.flavor_id = options.flavor_id;
+  if (options.pool_type) {
+    // 两池：pool_type 由服务端权威映射（不传默认 ephemeral）。
+    // 可选运维钉扎：配置 HW_POOL_TEMPLATE_* 时附带映射模板（服务端与老服务端均按显式模板处理）
+    body.pool_type = options.pool_type;
+    const pinned = pinnedTemplateFor(options.pool_type);
+    if (pinned && !body.template_id) body.template_id = pinned;
+  }
 
   return await hdkitRequest('POST', 'connect', body);
 }

package/plugins/huaweicloud-core/src/sandbox/sandbox-pool.mjs

@@ -0,0 +1,104 @@
+// 两池沙箱（pool_type）客户端支持。
+// 机制（定稿）：池 = 平台预置模板，客户端传 pool_type（ephemeral/persistent），
+// 服务端权威映射 template_id；显式 template_id 优先（运维钉扎场景）。
+// - 非持久池（默认）：闲置 30min 自动关机 + 1h 删除（平台定时任务，已实测生效）
+// - 持久池：EVS 数据盘跨关机保留，闲置回收保留期上限 7 天
+// - 配额：每用户每类型 1 台（同类复用），账号并发上限 5
+
+const POOL_TYPES = new Set(['ephemeral', 'persistent']);
+
+/** workspaceId → poolType 缓存：exec/upload/deploy 等工具返回值据此附带池上下文 */
+const workspacePool = new Map();
+
+/**
+ * 校验并归一化 pool_type；未传时返回 null（交由服务端默认 ephemeral，不在客户端伪造语义）。
+ * @throws Error 非法值（ephemeral/persistent 之外）
+ */
+export function validatePoolType(raw) {
+  if (raw === undefined || raw === null || raw === '') return null;
+  const normalized = String(raw).trim().toLowerCase();
+  if (!POOL_TYPES.has(normalized)) {
+    throw new Error(
+      `invalid pool_type "${raw}" (expected ephemeral or persistent). ` +
+        'ephemeral = 非持久沙箱（闲置 30min 自动关机、1h 删除）；persistent = 持久沙箱（数据盘保留，闲置回收上限 7 天）',
+    );
+  }
+  return normalized;
+}
+
+/**
+ * 运维钉扎（可选）：设置 HW_POOL_TEMPLATE_EPHEMERAL/PERSISTENT 后，客户端把映射出的
+ * template_id 与 pool_type 一并上送——服务端（及未升级的老服务端）按显式模板处理。
+ * 日常部署无需配置：模板 ID 由服务端 POOL_TEMPLATE_* 环境变量权威维护。
+ */
+export function pinnedTemplateFor(poolType) {
+  if (poolType === 'ephemeral') return process.env.HW_POOL_TEMPLATE_EPHEMERAL || '';
+  if (poolType === 'persistent') return process.env.HW_POOL_TEMPLATE_PERSISTENT || '';
+  return '';
+}
+
+/** 记录 workspace 的池归属（来自服务端 connect 响应的 pool_type 回显） */
+export function rememberWorkspacePool(workspaceId, poolType) {
+  if (workspaceId && poolType) workspacePool.set(workspaceId, poolType);
+}
+
+/** 清理 workspace 池缓存（测试用） */
+export function forgetWorkspacePool(workspaceId) {
+  if (workspaceId === undefined) workspacePool.clear();
+  else workspacePool.delete(workspaceId);
+}
+
+/**
+ * exec/upload/deploy 等工具返回值的池上下文（缺口#2 模式提示）。
+ * 未记录池归属（老服务端/自定义模板）时返回 undefined，不附加任何字段。
+ */
+export function poolContextFor(workspaceId) {
+  const poolType = workspacePool.get(workspaceId);
+  if (poolType === 'ephemeral') {
+    return {
+      poolMode: 'ephemeral',
+      persistenceHint: '非持久沙箱：闲置 30 分钟自动关机、1 小时自动删除，重要数据请及时保存或迁出',
+    };
+  }
+  if (poolType === 'persistent') {
+    return {
+      poolMode: 'persistent',
+      persistenceHint: '持久沙箱：数据盘跨关机保留，闲置回收保留期最长 7 天',
+    };
+  }
+  return undefined;
+}
+
+/**
+ * connect 结果池富化（缺口#1 TTL 播报）。
+ * 仅当服务端回显 pool_type 才播报（两种状态制：服务端未确认池语义不编造）。
+ * 钉扎/自定义模板（服务端回显 null）不播报。
+ * 读取做 pool_type/poolType 双读兜底（与 devStageId 双读同型，防 wire 命名漂移）。
+ */
+export function enrichConnectResult(result) {
+  if (!result || typeof result !== 'object') return result;
+  const poolType = result.pool_type || result.poolType;
+  if (poolType === 'ephemeral') {
+    result.pool = {
+      pool_type: 'ephemeral',
+      lifecycle: 'idle 30min auto-shutdown + 1h auto-delete (platform scheduled task, verified)',
+      ttl_hint:
+        '非持久沙箱：闲置 30 分钟将自动关机、闲置 1 小时将自动删除（平台定时任务已生效）。' +
+        '重要数据请及时保存或迁出；需要跨会话保留数据请改用 pool_type=persistent。',
+    };
+  } else if (poolType === 'persistent') {
+    result.pool = {
+      pool_type: 'persistent',
+      lifecycle: 'EVS data disk retained; idle reclaim within 7 days max',
+      ttl_hint: '持久沙箱：数据盘跨关机保留，闲置回收保留期最长 7 天；长期不用请自行导出数据。',
+    };
+  }
+  return result;
+}
+
+/** 池信息字段并入既有对象结果（非对象结果原样返回） */
+export function withPoolContext(workspaceId, result) {
+  const ctx = poolContextFor(workspaceId);
+  if (!ctx || !result || typeof result !== 'object') return result;
+  return { ...result, ...ctx };
+}

package/plugins/huaweicloud-core/src/tools.mjs

@@ -27,6 +27,13 @@ import {
   getCurrentWorkspaceId,
   setWorkspaceId,
 } from './sandbox/session-manager.mjs';
+import {
+  validatePoolType,
+  rememberWorkspacePool,
+  enrichConnectResult,
+  withPoolContext,
+  forgetWorkspacePool,
+} from './sandbox/sandbox-pool.mjs';
 import {
   hdkitCheckUser,
   hdkitSignAgreement,
@@ -623,7 +630,8 @@ export const TOOL_DEFINITIONS = [
   },
   {
     name: 'huaweicloud_sandbox_close_session',
-    description: 'Close the persistent terminal session for a workspace.',
+    description:
+      'Close the persistent terminal session for a workspace. This closes the agent-side terminal session only — it does NOT delete the sandbox instance. Resource-pool sandbox deletion is developer-initiated (always ask for a second confirmation before guiding a delete) or handled by the platform resource-group idle-reclaim policy within the 7-day cap (v3 caliber); devkit never defers or performs deletion on the user behalf.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -876,7 +884,7 @@ export const TOOL_DEFINITIONS = [
   {
     name: 'huaweicloud_sandbox_connect',
     description:
-      'Connect to a sandbox via hdkitservice. One user one instance - reuses existing sandbox if available, otherwise creates a new one. Returns session_id, dev_stage_id, connection_id, connection_address, and expiresAt (STS credential expiry).',
+      'Connect to a sandbox via hdkitservice. One instance per user per pool — reuses the same-pool sandbox if available, otherwise creates a new one. Quota: 1 instance per pool type (a user may hold 1 ephemeral AND 1 persistent simultaneously; same-type requests reuse the existing instance). On quota exhaustion the API returns HTTP 429 with a Retry-After header and a dual error code: HDKIT_QUOTA_EXCEEDED (retry useless — release or reuse the existing instance) vs HDKIT_CAPACITY_INSUFFICIENT (pool capacity; retry later / off-peak). Returns session_id, dev_stage_id, connection_id, connection_address, expiresAt (STS credential expiry), and pool_type/template_id echo. Ephemeral pool (default): idle auto-shutdown after 30min, auto-delete after 1h — do not keep important data there. Persistent pool: data disk retained (EVS 32G), idle reclaim capped at 7 days.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -885,6 +893,12 @@ export const TOOL_DEFINITIONS = [
           description:
             'Source identifier (default: WEB). Options: VSCODE, CLI, WEB, WEBVNC, WEBPTY, WEBIDE, CURSOR, etc.',
         },
+        pool_type: {
+          type: 'string',
+          enum: ['ephemeral', 'persistent'],
+          description:
+            'Sandbox pool type (default ephemeral). ephemeral = non-persistent: idle auto-shutdown 30min + auto-delete 1h (platform scheduled task, verified) — save important data elsewhere; persistent = data disk retained, idle reclaim within 7 days. Each user may hold one instance per pool type (1+1). Explicit template_id overrides pool_type.',
+        },
         template_id: { type: 'string', description: 'Template ID; overrides server default (only for new sandbox)' },
         flavor_id: { type: 'string', description: 'Flavor ID; overrides server default (only for new sandbox)' },
         env: { type: 'object', description: 'Environment variables to set in the sandbox (only for new sandbox)' },
@@ -1483,7 +1497,10 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       const sandboxUser2 = args.username || 'root';
       const sandboxTimeout2 = args.timeout_ms || 120000;
       const sandboxResult2 = await execWithSession(sandboxWsId2, args.command, sandboxUser2, sandboxTimeout2);
-      return { stdout: sandboxResult2.stdout, exitCode: sandboxResult2.exitCode };
+      return withPoolContext(sandboxWsId2, {
+        stdout: sandboxResult2.stdout,
+        exitCode: sandboxResult2.exitCode,
+      });
     }
     case 'huaweicloud_sandbox_exec_one_shot': {
       const sandboxWsId3 = args.workspace_id || getCurrentWorkspaceId();
@@ -1496,7 +1513,10 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       const sandboxUser3 = args.username || 'root';
       const sandboxTimeout3 = args.timeout_ms || 120000;
       const sandboxResult3 = await execOneShot(sandboxWsId3, args.command, sandboxUser3, sandboxTimeout3);
-      return { stdout: sandboxResult3.stdout, exitCode: sandboxResult3.exitCode };
+      return withPoolContext(sandboxWsId3, {
+        stdout: sandboxResult3.stdout,
+        exitCode: sandboxResult3.exitCode,
+      });
     }
     case 'huaweicloud_sandbox_close_session': {
       const sandboxWsId4 = args.workspace_id || getCurrentWorkspaceId();
@@ -1508,6 +1528,10 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       }
       const sandboxUser4 = args.username || 'root';
       const closed = await closeSession(sandboxWsId4, sandboxUser4);
+      if (closed) {
+        // 池归属缓存随会话关闭清理：长驻进程防只增不减/陈旧池归属
+        forgetWorkspacePool(sandboxWsId4);
+      }
       return closed ? 'ok' : 'not_connected';
     }
     case 'huaweicloud_sandbox_upload_file': {
@@ -1523,12 +1547,9 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       }
       const sandboxUser5 = args.username || 'root';
       const sandboxTimeout5 = args.timeout_ms || 120000;
-      return await uploadFileWithSession(
+      return withPoolContext(
         sandboxWsId5,
-        args.local_path,
-        args.remote_path,
-        sandboxUser5,
-        sandboxTimeout5,
+        await uploadFileWithSession(sandboxWsId5, args.local_path, args.remote_path, sandboxUser5, sandboxTimeout5),
       );
     }
     case 'huaweicloud_sandbox_upload_project': {
@@ -1544,16 +1565,12 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       }
       const sandboxUser6 = args.username || 'root';
       const sandboxTimeout6 = args.timeout_ms || 120000;
-      return await uploadProjectWithSession(
+      return withPoolContext(
         sandboxWsId6,
-        args.local_dir,
-        args.remote_dir,
-        sandboxUser6,
-        sandboxTimeout6,
-        {
+        await uploadProjectWithSession(sandboxWsId6, args.local_dir, args.remote_dir, sandboxUser6, sandboxTimeout6, {
           exclude: args.exclude,
           extract: args.extract,
-        },
+        }),
       );
     }
     case 'huaweicloud_sandbox_deploy_nginx': {
@@ -1569,19 +1586,22 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       }
       const sandboxUser7 = args.username || 'root';
       const sandboxTimeout7 = args.timeout_ms || 60000;
-      return await deployNginx(
+      return withPoolContext(
         sandboxWsId7,
-        {
-          nginxType: args.nginx_type,
-          port: args.port,
-          project: args.project,
-          outputDir: args.output_dir,
-          nodePort: args.node_port,
-          publicPort: args.public_port,
-          configName: args.config_name,
-        },
-        sandboxUser7,
-        sandboxTimeout7,
+        await deployNginx(
+          sandboxWsId7,
+          {
+            nginxType: args.nginx_type,
+            port: args.port,
+            project: args.project,
+            outputDir: args.output_dir,
+            nodePort: args.node_port,
+            publicPort: args.public_port,
+            configName: args.config_name,
+          },
+          sandboxUser7,
+          sandboxTimeout7,
+        ),
       );
     }
     case 'huaweicloud_sandbox_deploy_check': {
@@ -1597,16 +1617,19 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       }
       const sandboxUser8 = args.username || 'root';
       const sandboxTimeout8 = args.timeout_ms || 30000;
-      return await deployCheck(
+      return withPoolContext(
         sandboxWsId8,
-        {
-          port: args.port,
-          project: args.project,
-          outputDir: args.output_dir,
-          frameworkType: args.framework_type,
-        },
-        sandboxUser8,
-        sandboxTimeout8,
+        await deployCheck(
+          sandboxWsId8,
+          {
+            port: args.port,
+            project: args.project,
+            outputDir: args.output_dir,
+            frameworkType: args.framework_type,
+          },
+          sandboxUser8,
+          sandboxTimeout8,
+        ),
       );
     }
     case 'huaweicloud_sandbox_expose_tunnel': {
@@ -1624,11 +1647,14 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
       }
       const sandboxUser9 = args.username || 'root';
       const sandboxTimeout9 = args.timeout_ms || 90000;
-      return await exposeTunnel(
+      return withPoolContext(
         sandboxWsId9,
-        { port: args.port, expiryHours: args.expiry_hours, keepalive: args.keepalive },
-        sandboxUser9,
-        sandboxTimeout9,
+        await exposeTunnel(
+          sandboxWsId9,
+          { port: args.port, expiryHours: args.expiry_hours, keepalive: args.keepalive },
+          sandboxUser9,
+          sandboxTimeout9,
+        ),
       );
     }
     case 'huaweicloud_sandbox_renew_tunnel': {
@@ -1644,11 +1670,14 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
             'or set HW_WORKSPACE_ID environment variable before starting the agent.',
         );
       }
-      return await renewTunnel(
+      return withPoolContext(
         sandboxWsId10,
-        { tunnelId: args.tunnel_id, expiryHours: args.expiry_hours },
-        args.username || 'root',
-        args.timeout_ms || 60000,
+        await renewTunnel(
+          sandboxWsId10,
+          { tunnelId: args.tunnel_id, expiryHours: args.expiry_hours },
+          args.username || 'root',
+          args.timeout_ms || 60000,
+        ),
       );
     }
     case 'huaweicloud_sandbox_keepalive_watchdog': {
@@ -1665,11 +1694,14 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
         );
       }
       const tunnels11 = args.tunnels.map((t) => ({ tunnelId: t.tunnel_id || t.tunnelId, url: t.url }));
-      return await installKeepaliveWatchdog(
+      return withPoolContext(
         sandboxWsId11,
-        { tunnels: tunnels11 },
-        args.username || 'root',
-        args.timeout_ms || 60000,
+        await installKeepaliveWatchdog(
+          sandboxWsId11,
+          { tunnels: tunnels11 },
+          args.username || 'root',
+          args.timeout_ms || 60000,
+        ),
       );
     }
     case 'huaweicloud_sandbox_check_user':
@@ -1677,10 +1709,45 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
     case 'huaweicloud_sandbox_sign_agreement':
       return await hdkitSignAgreement();
     case 'huaweicloud_sandbox_connect': {
-      const connectResult = await hdkitConnect(args);
+      // 两池：客户端校验 pool_type（非法值在本地即报错，不发无效请求）；未传交由服务端默认 ephemeral
+      const connectArgs = { ...args };
+      let poolType;
+      try {
+        poolType = connectArgs.pool_type !== undefined ? validatePoolType(connectArgs.pool_type) : null;
+        if (poolType) connectArgs.pool_type = poolType;
+      } catch (error) {
+        // 非法 pool_type 结构化返回：MCP 错误信封只携带 code+message，指引字段在 throw 路径会丢失（参照 voucher 模式）
+        return { ok: false, code: 'HDKIT_INVALID_POOL_TYPE', message: error.message };
+      }
+      let connectResult;
+      try {
+        connectResult = await hdkitConnect(connectArgs);
+      } catch (error) {
+        // 业务预期失败（429 双码 / 烧核 / 凭证失效）转结构化返回，remediation 才能穿透 MCP 边界；
+        // 其余错误维持抛出（MCP 层透传 code+message）
+        if (
+          error?.code === 'HDKIT_QUOTA_EXCEEDED' ||
+          error?.code === 'HDKIT_CAPACITY_INSUFFICIENT' ||
+          error?.code === 'HDKIT_CRED_INVALID' ||
+          error?.coreHoursExhausted
+        ) {
+          return {
+            ok: false,
+            code: error.code,
+            message: error.message,
+            ...(error.retryAfter !== undefined ? { retryAfter: error.retryAfter } : {}),
+            ...(error.coreHoursExhausted ? { coreHoursExhausted: true } : {}),
+            ...(error.remediation ? { remediation: error.remediation } : {}),
+          };
+        }
+        throw error;
+      }
       const devStageId = connectResult?.dev_stage_id || connectResult?.devStageId;
       if (devStageId) {
         setWorkspaceId(devStageId);
+        // 池归属缓存：exec/upload/deploy 等工具返回值据此附带池模式提示（缺口#2）
+        // 双读兜底与 devStageId 同型（防服务端 wire 命名漂移，QA #1082 配对复审教训）
+        rememberWorkspacePool(devStageId, connectResult?.pool_type || connectResult?.poolType);
         try {
           await execOneShot(devStageId, 'devbridge delete-all 2>/dev/null || true', 'root', 15000);
         } catch {}
@@ -1694,7 +1761,8 @@ export async function callTool(name, rawArgs = {}, opts = {}) {
         } catch {}
         await transferGitRepo(args, devStageId, connectResult);
       }
-      return connectResult;
+      // TTL 播报（缺口#1）：服务端回显 pool_type 才附带生命周期提示
+      return enrichConnectResult(connectResult);
     }
     case 'huaweicloud_sandbox_credentials': {
       const devStageId = args.dev_stage_id || getCurrentWorkspaceId();