@thinkingai/ae-cli 6.0.30 → 6.0.32

package/README.md

@@ -84,7 +84,6 @@ ae-cli auth logout
 | Domain | Commands | Description |
 |--------|----------|-------------|
 | `analysis` | 30+ | Analysis workflows: alerts, reports, dashboards, ad-hoc/drilldown, entity/event details, analysis schema |
-| `analysis_audience` | 10+ | Audience operations: clusters, tags, and cluster/tag definition schema |
 | `analysis_meta` | 20+ | Metadata governance: events/properties, metrics, virtual metadata, project config, tracking plan, mark times, entity catalog |
 | `engage` | 40+ | Hermes Engage MCP: channels, tasks, configs, flows, strategies |
 | `dataops_repo` | 1 | DataOps repo utilities: space discovery |
@@ -96,7 +95,7 @@ ae-cli auth logout
 | `community` | 10+ | Community analysis: posts search, sentiment analysis, topic trends, livestream data |
 | `analysis_common` | 2 | Cross-module common constraints: resource link completion, project ID gate |
 | `team` | 14 | AI Agent Team: manage teams (list/create/update/delete/ai-generate/templates/projects) and execute TeamRuns (start/watch/chat/reply/cancel/result/artifacts) |
-| `kb` | 10 | Knowledge base lifecycle: query / new / add (md/dir/url) / schema / compile / rm-source / remove; retrieval primitives: index / grep / read |
+| `kb` | 11 | Knowledge base lifecycle: query / new / add (md/dir/url) / schema / compile / rm-source / remove; retrieval primitives: list / index / grep / read |
 | `auth` / `config` | 2 | Authentication and host configuration |
 
 ### kb
@@ -112,8 +111,9 @@ Knowledge base lifecycle (`+new` → `+add` → `+schema` → `+compile` → `+s
 - **Remove source** (`+rm-source`): `--name`, `--display-name`
 - **Remove KB** (`+remove`): `--name`
 
-Retrieval primitives for external agents (`+index` → `+grep` → `+read`); these are deterministic file-search endpoints with no server-side LLM, designed for agents (Claude Code / Codex / Cursor) to explore a KB the way they explore a codebase:
+Retrieval primitives for external agents (`+list` → `+index` → `+grep` → `+read`); these are deterministic file-search endpoints with no server-side LLM, designed for agents (Claude Code / Codex / Cursor) to explore a KB the way they explore a codebase:
 
+- **List** (`+list`): optional `--build-status` (default `compiled`), optional `--locale`. Returns accessible knowledge base metadata including `buildStatus`, without `index.md` navigation maps.
 - **Index** (`+index`): optional `--sources` JSON refs (omit to list all accessible KBs), optional `--locale`. Returns each KB's metadata plus its `index.md` navigation map.
 - **Grep** (`+grep`): `--query` / `-q`, optional `--sources`, `--top-k` (1-50, default 10), `--locale`. Returns matched lines with path, line number, breadcrumb and context snippet.
 - **Read** (`+read`): `--source` JSON ref (exactly one KB), `--path` (page path relative to the KB root), optional `--offset` / `--limit` (line window), `--locale`. Returns the full page or a line window.
@@ -124,9 +124,10 @@ Retrieval primitives for external agents (`+index` → `+grep` → `+read`); the
 |--------|-------------|---------|
 | `--host <url>` | Override active AE host URL | from config |
 | `--format <json\|table>` | Output format | json |
-| `--jq <expr>` | Filter expression | - |
-| `--dry-run` | Preview request | false |
-| `--yes` | Skip confirmation | false |
+| `--jq <expr>` | jq 1.8 expression (jq-wasm) over command payload before output envelope | - |
+| `--validate` | Fix params: capability gateway `/validate` only (curated gateway commands). Do not combine with `--dry-run` | false |
+| `--dry-run` | Confirm ready to run: capability gateway `/dry-run` (or local transport preview). Do not combine with `--validate` | false |
+| `--yes` | Skip high-risk write confirmation | false |
 | `--no-update-check` | Skip checking for newer ae-cli versions | false |
 
 ## Skills
@@ -188,7 +189,7 @@ ae-cli is built with:
 - **TypeScript** (~8000 lines of code)
 - **Commander.js** for CLI framework
 - **WebSocket** for MCP server integration
-- **Node.js** runtime (v18+)
+- **Node.js** runtime (v20+)
 
 The project structure:
 ```
@@ -200,7 +201,6 @@ src/
     ├── auth.ts
     ├── config.ts
     ├── te-analysis/
-    ├── te-audience/
     ├── te-meta/
     ├── te-engage/
     ├── te-dataops/
@@ -213,7 +213,6 @@ src/
 
 ```bash
 npm run verify:analysis-tools
-npm run verify:analysis-audience-tools
 npm run verify:analysis-meta-tools
 npm run verify:analysis-common-tools
 ```

package/README.zh.md

@@ -84,7 +84,6 @@ ae-cli auth logout
 | 域 | 命令数 | 描述 |
 |---|---|---|
 | `analysis` | 30+ | 分析工作流：告警、报表、仪表板、即时分析/下钻、实体/事件详情、分析模型 |
-| `analysis_audience` | 10+ | 受众运营：分群、标签及其定义模型 |
 | `analysis_meta` | 20+ | 元数据治理：事件/属性、指标、虚拟元数据、项目配置、埋点方案、标记时间、实体目录 |
 | `engage` | 40+ | Hermes Engage MCP：渠道、任务、配置、流程、策略 |
 | `dataops_repo` | 1 | DataOps 仓库辅助：空间发现 |
@@ -97,7 +96,7 @@ ae-cli auth logout
 | `analysis_common` | 2 | 跨模块通用约束：资源链接补全、项目 ID 门控 |
 | `agent` | 15 | Agent 平台资源管理：模型、MCP 服务、Skill、附件库的增删查和启停 |
 | `team` | 14 | AI Agent Team：团队管理（列表/创建/更新/删除/AI生成/模板/项目）和 TeamRun 执行（启动/监听/对话/回复/取消/结果/产物） |
-| `kb` | 10 | 知识库生命周期：查询 / 新建 / 添加源（md/目录/url）/ schema / 编译 / 删除源 / 删除；检索原语：index / grep / read |
+| `kb` | 11 | 知识库生命周期：查询 / 新建 / 添加源（md/目录/url）/ schema / 编译 / 删除源 / 删除；检索原语：list / index / grep / read |
 | `auth` / `config` | 2 | 身份验证和主机配置 |
 
 ### kb（知识库）
@@ -113,8 +112,9 @@ ae-cli auth logout
 - **删除源** (`+rm-source`)：`--name`，`--display-name`
 - **删除知识库** (`+remove`)：`--name`
 
-面向外部 agent 的检索原语（`+index` → `+grep` → `+read`）；均为确定性文件检索端点、服务端零 LLM 调用，让 agent（Claude Code / Codex / Cursor）像翻代码库一样探索知识库：
+面向外部 agent 的检索原语（`+list` → `+index` → `+grep` → `+read`）；均为确定性文件检索端点、服务端零 LLM 调用，让 agent（Claude Code / Codex / Cursor）像翻代码库一样探索知识库：
 
+- **列表** (`+list`)：可选 `--build-status`（默认 `compiled`）、`--locale`。返回可访问知识库的元信息（含 `buildStatus`），不含 `index.md` 导航地图。
 - **索引** (`+index`)：可选 `--sources` JSON 引用（省略则列出全部可访问知识库），可选 `--locale`。返回每个知识库的元信息及其 `index.md` 导航地图。
 - **检索** (`+grep`)：`--query` / `-q`，可选 `--sources`、`--top-k`（1-50，默认 10）、`--locale`。返回命中行的路径、行号、面包屑与上下文片段。
 - **读取** (`+read`)：`--source` JSON 引用（精确指向一个知识库），`--path`（相对知识库根目录的页面路径），可选 `--offset` / `--limit`（行窗口）、`--locale`。返回页面全文或行窗口。
@@ -125,9 +125,10 @@ ae-cli auth logout
 |---|---|---|
 | `--host <url>` | 覆盖当前 AE 主机 URL | 从配置读取 |
 | `--format <json\|table>` | 输出格式 | json |
-| `--jq <expr>` | 过滤表达式 | - |
-| `--dry-run` | 预览请求 | false |
-| `--yes` | 跳过确认 | false |
+| `--jq <expr>` | jq 1.8 表达式（jq-wasm），作用于命令业务结果，再包进输出信封 | - |
+| `--validate` | 改对参数：仅能力网关 `/validate`（精选网关命令）。勿与 `--dry-run` 同用 | false |
+| `--dry-run` | 确认可以跑：能力网关 `/dry-run`（或其它传输的请求预览）。勿与 `--validate` 同用 | false |
+| `--yes` | 跳过高风险写操作确认 | false |
 | `--no-update-check` | 跳过 ae-cli 新版本检查 | false |
 
 ## Skills
@@ -189,7 +190,7 @@ ae-cli 基于：
 - **TypeScript**（约 8000 行代码）
 - **Commander.js** 作为 CLI 框架
 - **WebSocket** 用于 MCP 服务器集成
-- **Node.js** 运行时（v18+）
+- **Node.js** 运行时（v20+）
 
 项目结构：
 ```
@@ -201,7 +202,6 @@ src/
     ├── auth.ts
     ├── config.ts
     ├── te-analysis/
-    ├── te-audience/
     ├── te-meta/
     ├── te-engage/
     ├── te-dataops/
@@ -214,7 +214,6 @@ src/
 
 ```bash
 npm run verify:analysis-tools
-npm run verify:analysis-audience-tools
 npm run verify:analysis-meta-tools
 npm run verify:analysis-common-tools
 ```

package/dist/{auth-7TQRGLBC.js → auth-7H3HAAJ3.js}

@@ -1,7 +1,7 @@
 import {
   printError,
   printOutput
-} from "./chunk-ZAOL36CG.js";
+} from "./chunk-TNW2CI4W.js";
 import {
   clearCliToken,
   mintCliToken
@@ -302,12 +302,12 @@ function registerAuth(program) {
         activateHostAfterLogin(host, explicitHost);
         logger.info(`Device flow login successful for ${host} (resumed)`);
         emit("Login successful! Token saved securely.");
-        printOutput(loginSummary(host, tokens2), fmt);
+        await printOutput(loginSummary(host, tokens2), fmt);
         return;
       }
       if (opts.wait === false) {
         const authResp = await authorizeDevice(teClaudeBase);
-        printOutput(
+        await printOutput(
           {
             device_code: authResp.device_code,
             user_code: authResp.user_code,
@@ -325,7 +325,7 @@ function registerAuth(program) {
       activateHostAfterLogin(host, explicitHost);
       logger.info(`Device flow login successful for ${host}`);
       emit("Login successful! Token saved securely.");
-      printOutput(loginSummary(host, tokens), fmt);
+      await printOutput(loginSummary(host, tokens), fmt);
     } catch (err) {
       if (err instanceof DeviceFlowUnsupportedError) {
         printError(
@@ -342,13 +342,13 @@ function registerAuth(program) {
   auth.command("status").description("Show authentication status for a host (--host or active host)").option("--host <url>", HOST_OPTION_DESC).action(async (opts) => {
     const host = resolveAuthHost(program, opts);
     if (!host) {
-      printOutput({ authenticated: false, host: "(none)", hint: "Run: ae-cli config set-host <url>" }, program.opts().format || "json");
+      await printOutput({ authenticated: false, host: "(none)", hint: "Run: ae-cli config set-host <url>" }, program.opts().format || "json");
       return;
     }
     const secureEntry = load(host);
     if (secureEntry) {
       const pastStaticExpiry = new Date(secureEntry.accessExpiresAt).getTime() < Date.now();
-      printOutput(
+      await printOutput(
         {
           authenticated: true,
           host,
@@ -364,7 +364,7 @@ function registerAuth(program) {
     }
     const fallbackCliToken = getFallbackCliToken(host);
     if (fallbackCliToken) {
-      printOutput(
+      await printOutput(
         {
           authenticated: true,
           host,
@@ -376,9 +376,9 @@ function registerAuth(program) {
       );
       return;
     }
-    printOutput({ authenticated: false, host, source: "none" }, program.opts().format || "json");
+    await printOutput({ authenticated: false, host, source: "none" }, program.opts().format || "json");
   });
-  auth.command("logout").description("Clear stored credentials (access token, CLI token, and host config) for a host (--host or active host)").option("--host <url>", HOST_OPTION_DESC).action((opts) => {
+  auth.command("logout").description("Clear stored credentials (access token, CLI token, and host config) for a host (--host or active host)").option("--host <url>", HOST_OPTION_DESC).action(async (opts) => {
     const host = resolveAuthHost(program, opts);
     if (!host) {
       printError("config", "No AE host configured.", "Run: ae-cli config set-host <url>");
@@ -389,7 +389,7 @@ function registerAuth(program) {
     removeHost(host);
     process.stderr.write(`[ae-cli] Credentials and config cleared for ${host}
 `);
-    printOutput({ cleared: true, host }, program.opts().format || "json");
+    await printOutput({ cleared: true, host }, program.opts().format || "json");
   });
 }
 export {

package/dist/{capability-KVA55RMK.js → capability-QW4AVJHI.js}

@@ -2,20 +2,21 @@ import {
   normalizeRiskLevel,
   requiresConfirmation
 } from "./chunk-OO6XR6LK.js";
-import {
-  printError,
-  printOutput
-} from "./chunk-ZAOL36CG.js";
 import {
   findGatewayDomain
-} from "./chunk-CWZUGF2J.js";
+} from "./chunk-PTE56QPL.js";
 import {
   CapabilityGatewayError,
   dryRunCapability,
   executeCapability,
   inspectCapability,
-  listCapabilities
-} from "./chunk-OJR23CIK.js";
+  listCapabilities,
+  validateCapability
+} from "./chunk-DYOS6YY7.js";
+import {
+  printError,
+  printOutput
+} from "./chunk-TNW2CI4W.js";
 import {
   PermissionError
 } from "./chunk-NOO24N7W.js";
@@ -135,7 +136,31 @@ function registerCapability(program) {
       return inspectCapability(host, gatewayDomain, capabilityId);
     });
   }).addHelpText("after", "\nExample:\n  ae-cli capability inspect analysis.dashboard.list");
-  capability.command("dry-run").description("Validate and preview one capability invocation without executing it").argument("<capability-id>", "Capability ID, such as analysis.query.export").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
+  capability.command("validate").description(
+    "Validate and normalize capability input only (schema/params). Does not execute business logic. Use when crafting complex payloads (nested objects, qp, share/member payloads) before dry-run/run. Success data: valid, capability_id, normalized_input. Unlike dry-run, does not return risk/output_mode/supports_cancel preview."
+  ).argument("<capability-id>", "Capability ID, such as metadata.data_table.sql_write").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
+    await executeAndPrint(program, async (host) => {
+      const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
+      return validateCapability(host, gatewayDomain, capabilityId, parseCapabilityInput(opts.input));
+    });
+  }).addHelpText(
+    "after",
+    `
+When to use:
+  Prefer validate while iterating complex input (required fields, types, qp shape), then run.
+  Prefer dry-run alone when you need risk / output mode / cancelability or a delete gate.
+  Motto: validate = fix params; dry-run = confirm ready to run.
+  Do not stack validate + dry-run on the same final input by default (dry-run already validates params).
+  Neither mutates business data. Curated gateway commands: global --validate / --dry-run.
+
+Examples:
+  ae-cli capability validate metadata.data_table.sql_write --input '{"project_id":1,"operation":"create",...}'
+  ae-cli metadata data-table sql-write --project-id 1 ... --validate
+  ae-cli capability validate analysis.project_space.create --input input.json`
+  );
+  capability.command("dry-run").description(
+    "Full pre-execution confirmation without running business logic: validates/normalizes input and returns risk, output_mode, and supports_cancel. Use alone when you need that preview or a delete gate (do not stack after validate on the same final input by default). Global --dry-run on curated/capability run also hits this endpoint."
+  ).argument("<capability-id>", "Capability ID, such as analysis.query.export").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
     await executeAndPrint(program, async (host) => {
       const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
       return dryRunCapability(host, gatewayDomain, capabilityId, parseCapabilityInput(opts.input));
@@ -151,6 +176,15 @@ Examples:
     await executeAndPrint(program, async (host, globalOpts) => {
       const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
       const input = parseCapabilityInput(opts.input);
+      if (globalOpts.validate && globalOpts.dryRun) {
+        throw new CapabilityCommandValidationError(
+          "Cannot combine --validate and --dry-run.",
+          "Use --validate to fix parameters; use --dry-run as the pre-execution confirmation."
+        );
+      }
+      if (globalOpts.validate) {
+        return validateCapability(host, gatewayDomain, capabilityId, input);
+      }
       if (globalOpts.dryRun) {
         return dryRunCapability(host, gatewayDomain, capabilityId, input);
       }
@@ -172,7 +206,7 @@ Examples:
     `
 Examples:
   ae-cli capability run analysis.dashboard.list --input '{"project_id":1}'
-  ae-cli capability run analysis.dashboard.list --input input.json --yes`
+  ae-cli capability run analysis.dashboard.list --input input.json`
   );
 }
 async function executeAndPrint(program, action) {
@@ -186,9 +220,14 @@ async function executeAndPrint(program, action) {
   try {
     const result = await action(host, globalOpts);
     if (result !== void 0) {
-      printOutput(result, globalOpts.format ?? "json", globalOpts.jq);
+      await printOutput(result, globalOpts.format ?? "json", globalOpts.jq);
     }
   } catch (error) {
+    if (error?.type === "validation" && String(error?.message || "").includes("--jq")) {
+      printError("validation", error.message, error.hint);
+      process.exitCode = 1;
+      return;
+    }
     printCapabilityError(error);
     process.exitCode = 1;
   }

package/dist/{capability-LKHLZQPD.js → capability-SCRFGODD.js}

@@ -2,20 +2,21 @@ import {
   normalizeRiskLevel,
   requiresConfirmation
 } from "./chunk-OO6XR6LK.js";
-import {
-  printError,
-  printOutput
-} from "./chunk-ZAOL36CG.js";
 import {
   findGatewayDomain
-} from "./chunk-CWZUGF2J.js";
+} from "./chunk-PTE56QPL.js";
 import {
   CapabilityGatewayError,
   dryRunCapability,
   executeCapability,
   inspectCapability,
-  listCapabilities
-} from "./chunk-THBBNYXI.js";
+  listCapabilities,
+  validateCapability
+} from "./chunk-I4A62X3N.js";
+import {
+  printError,
+  printOutput
+} from "./chunk-TNW2CI4W.js";
 import {
   PermissionError
 } from "./chunk-NOO24N7W.js";
@@ -135,7 +136,31 @@ function registerCapability(program) {
       return inspectCapability(host, gatewayDomain, capabilityId);
     });
   }).addHelpText("after", "\nExample:\n  ae-cli capability inspect analysis.dashboard.list");
-  capability.command("dry-run").description("Validate and preview one capability invocation without executing it").argument("<capability-id>", "Capability ID, such as analysis.query.export").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
+  capability.command("validate").description(
+    "Validate and normalize capability input only (schema/params). Does not execute business logic. Use when crafting complex payloads (nested objects, qp, share/member payloads) before dry-run/run. Success data: valid, capability_id, normalized_input. Unlike dry-run, does not return risk/output_mode/supports_cancel preview."
+  ).argument("<capability-id>", "Capability ID, such as metadata.data_table.sql_write").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
+    await executeAndPrint(program, async (host) => {
+      const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
+      return validateCapability(host, gatewayDomain, capabilityId, parseCapabilityInput(opts.input));
+    });
+  }).addHelpText(
+    "after",
+    `
+When to use:
+  Prefer validate while iterating complex input (required fields, types, qp shape), then run.
+  Prefer dry-run alone when you need risk / output mode / cancelability or a delete gate.
+  Motto: validate = fix params; dry-run = confirm ready to run.
+  Do not stack validate + dry-run on the same final input by default (dry-run already validates params).
+  Neither mutates business data. Curated gateway commands: global --validate / --dry-run.
+
+Examples:
+  ae-cli capability validate metadata.data_table.sql_write --input '{"project_id":1,"operation":"create",...}'
+  ae-cli metadata data-table sql-write --project-id 1 ... --validate
+  ae-cli capability validate analysis.project_space.create --input input.json`
+  );
+  capability.command("dry-run").description(
+    "Full pre-execution confirmation without running business logic: validates/normalizes input and returns risk, output_mode, and supports_cancel. Use alone when you need that preview or a delete gate (do not stack after validate on the same final input by default). Global --dry-run on curated/capability run also hits this endpoint."
+  ).argument("<capability-id>", "Capability ID, such as analysis.query.export").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
     await executeAndPrint(program, async (host) => {
       const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
       return dryRunCapability(host, gatewayDomain, capabilityId, parseCapabilityInput(opts.input));
@@ -151,6 +176,15 @@ Examples:
     await executeAndPrint(program, async (host, globalOpts) => {
       const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
       const input = parseCapabilityInput(opts.input);
+      if (globalOpts.validate && globalOpts.dryRun) {
+        throw new CapabilityCommandValidationError(
+          "Cannot combine --validate and --dry-run.",
+          "Use --validate to fix parameters; use --dry-run as the pre-execution confirmation."
+        );
+      }
+      if (globalOpts.validate) {
+        return validateCapability(host, gatewayDomain, capabilityId, input);
+      }
       if (globalOpts.dryRun) {
         return dryRunCapability(host, gatewayDomain, capabilityId, input);
       }
@@ -172,7 +206,7 @@ Examples:
     `
 Examples:
   ae-cli capability run analysis.dashboard.list --input '{"project_id":1}'
-  ae-cli capability run analysis.dashboard.list --input input.json --yes`
+  ae-cli capability run analysis.dashboard.list --input input.json`
   );
 }
 async function executeAndPrint(program, action) {
@@ -186,9 +220,14 @@ async function executeAndPrint(program, action) {
   try {
     const result = await action(host, globalOpts);
     if (result !== void 0) {
-      printOutput(result, globalOpts.format ?? "json", globalOpts.jq);
+      await printOutput(result, globalOpts.format ?? "json", globalOpts.jq);
     }
   } catch (error) {
+    if (error?.type === "validation" && String(error?.message || "").includes("--jq")) {
+      printError("validation", error.message, error.hint);
+      process.exitCode = 1;
+      return;
+    }
     printCapabilityError(error);
     process.exitCode = 1;
   }

package/dist/{chunk-GWZ5MYWE.js → chunk-6LEYLOV3.js}

@@ -168,6 +168,16 @@ async function callMcpTool(url, toolName, args = {}, hostOverride) {
   };
 }
 function parseMcpResult(result) {
+  if (result.isError) {
+    const firstText = result.content.find((item) => item.type === "text")?.text || "";
+    let errorMessage = firstText.trim() || "MCP tool call failed";
+    try {
+      const parsed = safeJsonParse(firstText);
+      errorMessage = mcpResultErrorMessage(parsed) || errorMessage;
+    } catch {
+    }
+    throwMcpError(errorMessage);
+  }
   if (result.content.length > 0 && result.content[0].type === "text") {
     const text = result.content[0].text || "";
     let parsed;
@@ -178,10 +188,7 @@ function parseMcpResult(result) {
     }
     const errMsg = mcpResultErrorMessage(parsed);
     if (errMsg !== null) {
-      if (/no_auth|auth_error|permission|forbidden|unauthor|\u65e0\u6743/i.test(errMsg)) {
-        throw new PermissionError(errMsg);
-      }
-      throw new Error(errMsg);
+      throwMcpError(errMsg);
     }
     return parsed;
   }
@@ -190,6 +197,7 @@ function parseMcpResult(result) {
 function mcpResultErrorMessage(parsed) {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
   if (parsed.success === true || parsed.ok === true) return null;
+  const explicitlyFailed = parsed.success === false || parsed.ok === false;
   const e = parsed.error;
   if (typeof e === "string" && e.trim()) return e;
   if (e && typeof e === "object") {
@@ -198,8 +206,21 @@ function mcpResultErrorMessage(parsed) {
     if (msg && code) return `${code}: ${msg}`;
     if (msg || code) return msg || code;
   }
+  if (explicitlyFailed) {
+    const msg = typeof parsed.message === "string" && parsed.message.trim() ? parsed.message.trim() : void 0;
+    const codeValue = parsed.errorCode ?? parsed.error_code ?? parsed.code;
+    const code = typeof codeValue === "string" && codeValue.trim() ? codeValue.trim() : void 0;
+    if (msg && code) return `${code}: ${msg}`;
+    return msg || code || "MCP tool call failed";
+  }
   return null;
 }
+function throwMcpError(message) {
+  if (/no_auth|auth_error|permission|forbidden|unauthor|\u65e0\u6743/i.test(message)) {
+    throw new PermissionError(message);
+  }
+  throw new Error(message);
+}
 
 export {
   registerMcpMappings,

package/dist/chunk-7OLGDQQ2.js

@@ -0,0 +1,71 @@
+import {
+  resolveGatewayDomain
+} from "./chunk-PTE56QPL.js";
+import {
+  dryRunCapability,
+  executeCapabilityWithEnvelope,
+  validateCapability
+} from "./chunk-DYOS6YY7.js";
+import {
+  withOutputMetadata
+} from "./chunk-TNW2CI4W.js";
+
+// src/core/capability-command.ts
+import { randomBytes } from "crypto";
+function createCapabilityCommand(config) {
+  return {
+    service: config.cliService,
+    resource: config.resource,
+    command: config.command,
+    capabilityId: config.capabilityId,
+    description: config.description,
+    flags: config.flags,
+    risk: config.risk,
+    validate: config.validate,
+    preflight: (ctx) => {
+      config.buildInput(ctx);
+    },
+    validateInput: async (ctx) => {
+      const gatewayDomain = resolveGatewayDomain(config.cliService, config.gatewayDomain);
+      const requestHost = config.requestHost ?? ctx.host();
+      const input = config.buildInput(ctx);
+      return validateCapability(requestHost, gatewayDomain, config.capabilityId, input);
+    },
+    dryRun: async (ctx) => {
+      const gatewayDomain = resolveGatewayDomain(config.cliService, config.gatewayDomain);
+      const requestHost = config.requestHost ?? ctx.host();
+      const input = config.buildInput(ctx);
+      return dryRunCapability(requestHost, gatewayDomain, config.capabilityId, input);
+    },
+    execute: async (ctx) => {
+      const gatewayDomain = resolveGatewayDomain(config.cliService, config.gatewayDomain);
+      const requestHost = config.requestHost ?? ctx.host();
+      const input = withLifecycleRequestId(config, config.buildInput(ctx));
+      announceDispatch(config.capabilityId, input);
+      const result = await executeCapabilityWithEnvelope(requestHost, gatewayDomain, config.capabilityId, input);
+      const data = config.postProcess ? config.postProcess(result.data, input, ctx) : result.data;
+      return withOutputMetadata(data, result.meta);
+    }
+  };
+}
+function withLifecycleRequestId(config, input) {
+  if (!config.flags.some((flag) => flag.name === "request-id")) {
+    return input;
+  }
+  const supplied = input.request_id;
+  const requestId = typeof supplied === "string" && supplied.length > 0 ? supplied : `cli_${randomBytes(16).toString("hex")}`;
+  return { ...input, request_id: requestId };
+}
+function announceDispatch(capabilityId, input) {
+  if (typeof input.request_id !== "string") {
+    return;
+  }
+  process.stderr.write(
+    `[ae-cli] dispatching capability=${capabilityId} request_id=${input.request_id}
+`
+  );
+}
+
+export {
+  createCapabilityCommand
+};