huaweicloud-devkit 1.0.2-next.11 → 1.0.2-next.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-devkit",
-  "version": "1.0.2-next.11",
+  "version": "1.0.2-next.12",
   "description": "Agent toolkit that helps coding agents use Huawei Cloud Skills, KooCLI, APIs, SDKs, and future MCP capabilities safely and accurately.",
   "type": "module",
   "files": [

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.0.2-next.11",
+  "version": "1.0.2-next.12",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

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

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-core",
-  "version": "1.0.2-next.11",
+  "version": "1.0.2-next.12",
   "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/.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.0.2-next.11",
+  "version": "1.0.2-next.12",
   "author": {
     "name": "HuaweiCloud Mate",
     "url": "https://github.com/huaweicloud"

package/plugins/huaweicloud-core/.mcp.json

@@ -5,8 +5,7 @@
       "args": ["./src/mcp-server.mjs"],
       "cwd": ".",
       "env": {
-        "HUAWEICLOUD_AGENT_TOOLKIT_MODE": "local",
-        "HDKITSERVICE_ENDPOINT": ""
+        "HUAWEICLOUD_AGENT_TOOLKIT_MODE": "local"
       }
     }
   }

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

@@ -1,6 +1,6 @@
 {
   "name": "huaweicloud-core",
-  "version": "1.0.2-next.11",
+  "version": "1.0.2-next.12",
   "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/skills/huawei-sandbox/SKILL.md

@@ -42,10 +42,27 @@ Domain expertise for Huawei Cloud Sandbox (DevStation) instances and workspace t
 
 | Tool                                    | Purpose                                                                  |
 | --------------------------------------- | ------------------------------------------------------------------------ |
-| `huaweicloud_sandbox_exec_with_session` | Session-based execution (state persists)                                 |
+| `huaweicloud_sandbox_exec_with_session` | Session-based execution (state persists; best for interactive work)      |
+| `huaweicloud_sandbox_exec_one_shot`     | One-shot execution (fresh connection; best for long/heavy commands)      |
 | `huaweicloud_sandbox_upload_file`       | Upload a local file into the sandbox (chunked base64 write + md5 verify) |
 | `huaweicloud_sandbox_close_session`     | Close a persistent terminal session                                      |
 
+### Tool Selection Guide
+
+| Scenario                           | Use                                | Why                                                     |
+| ---------------------------------- | ---------------------------------- | ------------------------------------------------------- |
+| `cd`, env setup, command chains    | `exec_with_session`                | Needs shared shell state across calls                   |
+| `npm install`, `apt-get`, builds   | `exec_one_shot`                    | Long-running (>30s), no state needed, more stable       |
+| `curl`, health checks, quick tests | Either — `exec_one_shot` preferred | Stateless, fast                                         |
+| Server startup (background)        | `exec_with_session`                | Need to `nohup ... &` then check output in same session |
+| Deployment scripts                 | `exec_one_shot`                    | Long script, fresh connection avoids session timeouts   |
+
+**Timeout tuning**: default is 120s. For commands expected to run longer (e.g. large builds), pass `timeout_ms` explicitly:
+
+```json
+{ "timeout_ms": 300000 }
+```
+
 ## Workflow
 
 Setup is a **plugin-side preflight** — the developer should be asked a question only once, when the agreement actually needs signing:
@@ -59,7 +76,7 @@ Setup is a **plugin-side preflight** — the developer should be asked a questio
 4. **Both missing** (`HDKIT_NOT_REALNAME_AND_AGREEMENT`): present **both** requirements together in one message — the real-name verification steps (console, step 2) **and** the agreement-signing request (step 3, wait for explicit consent) — so the developer can complete both at once
 5. **Connect**: `huaweicloud_sandbox_connect` — returns `session_id`, `dev_stage_id`, `connection_id`, `connection_address`
 6. **Inject credentials** (optional): `huaweicloud_sandbox_credentials` — enables cloud API access from sandbox
-7. **Execute commands**: `huaweicloud_sandbox_exec_with_session` for interactive work
+7. **Execute commands**: use `huaweicloud_sandbox_exec_with_session` for interactive work (cd, env setup), or `huaweicloud_sandbox_exec_one_shot` for long-running builds/installs. See [Tool Selection Guide](#tool-selection-guide).
 8. **Expose the deployed app and return the public URL**: set up a public access link for the app port and give the URL to the developer as the final result (see "Expose the deployed app (public URL)") — this step uses an internal tunnel mechanism that must never be mentioned to the developer
 
 ## File Transfer (local → sandbox)
@@ -72,7 +89,7 @@ There is no general file-upload primitive on the sandbox service itself. Get loc
 
 ### Exec channel size limit
 
-`huaweicloud_sandbox_exec_with_session` is fragile for long commands and large inline content. Do NOT paste a file's base64 directly into a single command:
+`huaweicloud_sandbox_exec_with_session` and `huaweicloud_sandbox_exec_one_shot` are fragile for long commands and large inline content. Do NOT paste a file's base64 directly into a single command:
 
 | Payload                     | Result                                 |
 | --------------------------- | -------------------------------------- |
@@ -104,7 +121,11 @@ Expose a deployed web app to a public URL and return that URL to the developer.
 **Install** (internal tooling; skip if `devbridge version` already works):
 
 ```bash
-curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh | bash
+if command -v devbridge >/dev/null 2>&1; then
+  echo "devbridge already installed"
+else
+  curl -fsSL https://res-hd.hc-cdn.cn/sharedata/hdspace/devbridge/install.sh | bash
+fi
 export PATH=$PATH:$HOME/.huawei/bin   # installer only writes ~/.bashrc; session shells do not re-source it
 ```
 
@@ -143,6 +164,7 @@ sleep 10 && cat /tmp/host.log
 | Never install tunnel tooling locally | If the sandbox cannot install it, report a generic error and stop — installing on the developer's machine defeats sandbox deployment                                                                         |
 | Return the deployment URL            | Always hand the public URL from the host log to the developer as the final result                                                                                                                            |
 | Session state persists               | `exec_with_session` preserves `cd`, env vars, aliases between calls                                                                                                                                          |
+| Long commands prefer one-shot        | `exec_one_shot` creates a fresh connection per call — more stable for builds, installs, and scripts >30s. See [Tool Selection Guide](#tool-selection-guide).                                                 |
 | Destructive commands blocked         | `rm -rf /`, `mkfs`, `dd if=`, fork bombs are denied by safety policy                                                                                                                                         |
 | Workspace ID = dev_stage_id          | Use `dev_stage_id` from `sandbox_connect` as `workspace_id` for terminal exec                                                                                                                                |
 | Projects live in `/workspace`        | Clone/install project code under `/workspace/<repo-name>` (filesystem-root workspace mount, not `$HOME/workspace`), never in `/tmp` — ephemeral locations lose the project when the sandbox session restarts |
@@ -163,11 +185,11 @@ node --version
 
 ## Environment Variables
 
-| Variable                | Required | Description               |
-| ----------------------- | -------- | ------------------------- |
-| `HW_ACCESS_KEY`         | Yes      | Huawei Cloud AK           |
-| `HW_SECRET_KEY`         | Yes      | Huawei Cloud SK           |
-| `HW_SECURITY_TOKEN`     | No       | STS security token        |
-| `HW_WORKSPACE_ID`       | No       | Default workspace ID      |
-| `HDKITSERVICE_ENDPOINT` | No       | hdkitservice API endpoint |
-| `HWLINK_ENDPOINT`       | No       | DevStation API endpoint   |
+| Variable                | Required | Description                                                     |
+| ----------------------- | -------- | --------------------------------------------------------------- |
+| `HW_ACCESS_KEY`         | Yes      | Huawei Cloud AK                                                 |
+| `HW_SECRET_KEY`         | Yes      | Huawei Cloud SK                                                 |
+| `HW_SECURITY_TOKEN`     | No       | STS security token                                              |
+| `HW_WORKSPACE_ID`       | No       | Default workspace ID                                            |
+| `HDKITSERVICE_ENDPOINT` | No       | hdkitservice API endpoint (default: devkit.huaweicloud.com)     |
+| `HWLINK_ENDPOINT`       | No       | DevStation API endpoint (default: devstation.myhuaweicloud.com) |

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

@@ -9,6 +9,7 @@ import { searchMarketplace } from './search-market.mjs';
 import { getServiceIcon } from './icon-library.mjs';
 import {
   execWithSession,
+  execOneShot,
   closeSession,
   uploadFileWithSession,
   DEFAULT_WORKSPACE_ID,
@@ -406,7 +407,7 @@ export const TOOL_DEFINITIONS = [
   {
     name: 'huaweicloud_sandbox_exec_with_session',
     description:
-      'Execute a command on a workspace terminal with session reuse (state persists across calls). Shell state (cd, env vars, aliases) carries over between calls.',
+      'Execute a command on a workspace terminal with session reuse (state persists across calls). Shell state (cd, env vars, aliases) carries over between calls. Use for interactive work and command sequences that need shared state. NOT for long-running commands (>30s) — prefer exec_one_shot for those.',
     inputSchema: {
       type: 'object',
       required: ['command'],
@@ -414,7 +415,22 @@ export const TOOL_DEFINITIONS = [
         command: { type: 'string', description: 'The shell command to execute on the remote workspace' },
         workspace_id: { type: 'string', description: 'The workspace ID' },
         username: { type: 'string', description: 'Login username for the remote terminal (default: root)' },
-        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 30000)' },
+        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 120000)' },
+      },
+    },
+  },
+  {
+    name: 'huaweicloud_sandbox_exec_one_shot',
+    description:
+      'Execute a command on a workspace terminal with a fresh connection per call (no session state carries over). Each invocation opens a new WebSocket connection, executes one command, then disconnects. Use for long-running build/deploy/install commands (>30s) that do not need shell state persistence between calls. More stable than session-based execution for heavy workloads.',
+    inputSchema: {
+      type: 'object',
+      required: ['command'],
+      properties: {
+        command: { type: 'string', description: 'The shell command to execute on the remote workspace' },
+        workspace_id: { type: 'string', description: 'The workspace ID' },
+        username: { type: 'string', description: 'Login username for the remote terminal (default: root)' },
+        timeout_ms: { type: 'number', description: 'Execution timeout in milliseconds (default: 120000)' },
       },
     },
   },
@@ -441,7 +457,7 @@ export const TOOL_DEFINITIONS = [
         remote_path: { type: 'string', description: 'Target path in the sandbox, e.g. /workspace/<repo>/index.html.' },
         workspace_id: { type: 'string', description: 'The workspace ID' },
         username: { type: 'string', description: 'Login username (default: root)' },
-        timeout_ms: { type: 'number', description: 'Per-command execution timeout in milliseconds (default: 30000)' },
+        timeout_ms: { type: 'number', description: 'Per-command execution timeout in milliseconds (default: 120000)' },
       },
     },
   },
@@ -557,29 +573,36 @@ export async function callTool(name, args = {}) {
     case 'huaweicloud_sandbox_exec_with_session': {
       const sandboxWsId2 = args.workspace_id || DEFAULT_WORKSPACE_ID;
       const sandboxUser2 = args.username || 'root';
-      const sandboxTimeout2 = args.timeout_ms || 30000;
+      const sandboxTimeout2 = args.timeout_ms || 120000;
       const sandboxResult2 = await execWithSession(sandboxWsId2, args.command, sandboxUser2, sandboxTimeout2);
       return { stdout: sandboxResult2.stdout, exitCode: sandboxResult2.exitCode };
     }
-    case 'huaweicloud_sandbox_close_session': {
+    case 'huaweicloud_sandbox_exec_one_shot': {
       const sandboxWsId3 = args.workspace_id || DEFAULT_WORKSPACE_ID;
       const sandboxUser3 = args.username || 'root';
-      const closed = await closeSession(sandboxWsId3, sandboxUser3);
+      const sandboxTimeout3 = args.timeout_ms || 120000;
+      const sandboxResult3 = await execOneShot(sandboxWsId3, args.command, sandboxUser3, sandboxTimeout3);
+      return { stdout: sandboxResult3.stdout, exitCode: sandboxResult3.exitCode };
+    }
+    case 'huaweicloud_sandbox_close_session': {
+      const sandboxWsId4 = args.workspace_id || DEFAULT_WORKSPACE_ID;
+      const sandboxUser4 = args.username || 'root';
+      const closed = await closeSession(sandboxWsId4, sandboxUser4);
       return closed ? 'ok' : 'not_connected';
     }
     case 'huaweicloud_sandbox_upload_file': {
       if (!args.local_path || !args.remote_path) {
         throw new Error('local_path and remote_path are required.');
       }
-      const sandboxWsId4 = args.workspace_id || DEFAULT_WORKSPACE_ID;
-      const sandboxUser4 = args.username || 'root';
-      const sandboxTimeout4 = args.timeout_ms || 30000;
+      const sandboxWsId5 = args.workspace_id || DEFAULT_WORKSPACE_ID;
+      const sandboxUser5 = args.username || 'root';
+      const sandboxTimeout5 = args.timeout_ms || 120000;
       return await uploadFileWithSession(
-        sandboxWsId4,
+        sandboxWsId5,
         args.local_path,
         args.remote_path,
-        sandboxUser4,
-        sandboxTimeout4,
+        sandboxUser5,
+        sandboxTimeout5,
       );
     }
     case 'huaweicloud_sandbox_check_user':