@thinkingai/ae-cli 6.0.39 → 6.0.41

package/dist/{te-engage-F7V55KVW.js → te-engage-6RNGK5GH.js}

@@ -1,16 +1,24 @@
 import {
   createCapabilityCommand
-} from "./chunk-7KQWSBSL.js";
+} from "./chunk-J2N4PB56.js";
 import {
-  registerCapabilityGatewayRoute
-} from "./chunk-PTE56QPL.js";
+  CapabilityGatewayError,
+  buildCapabilityGatewayUrl,
+  fetchCapabilityGateway,
+  requestCapabilityGateway,
+  requestCapabilityGatewayWithEnvelope
+} from "./chunk-5XUSIK27.js";
+import {
+  printError,
+  withOutputMetadata
+} from "./chunk-WZRX4KOH.js";
 import {
-  printError
-} from "./chunk-YTG6Q75E.js";
-import "./chunk-RBNKI5ZW.js";
-import "./chunk-Z3OXWCIA.js";
-import "./chunk-YV52FB5G.js";
-import "./chunk-GJJA4CQZ.js";
+  registerCapabilityGatewayRoute,
+  resolveGatewayDomain
+} from "./chunk-PTE56QPL.js";
+import "./chunk-S5NTSDBS.js";
+import "./chunk-ZQKDZXDO.js";
+import "./chunk-3FY3RJ26.js";
 import {
   CliValidationError
 } from "./chunk-AXDXJTPC.js";
@@ -42,6 +50,9 @@ function createEngageActivityCapabilityCommand(config) {
 function createEngageWorkbenchCapabilityCommand(config) {
   return createEngageCapabilityCommand("engage-workbench", config);
 }
+function createEngageQueryCapabilityCommand(config) {
+  return createEngageCapabilityCommand("engage-query", config);
+}
 
 // src/commands/te-engage/engage-flow/flow/update-remark.ts
 var flowUpdateRemark = createEngageFlowCapabilityCommand({
@@ -78,6 +89,9 @@ function readOptionalString(ctx, name) {
 function readOptionalNumber(ctx, name) {
   return hasFlag(ctx, name) ? ctx.num(name) : void 0;
 }
+function readOptionalBoolean(ctx, name) {
+  return hasFlag(ctx, name) ? ctx.bool(name) : void 0;
+}
 function readOptionalJsonArray(ctx, name) {
   const value = ctx.json(name);
   if (value === void 0) return void 0;
@@ -209,6 +223,375 @@ var flowModifyBaseInfo = createEngageFlowCapabilityCommand({
   })
 });
 
+// src/commands/te-engage/semantic-qp-validation.ts
+var OPERATORS = /* @__PURE__ */ new Set([
+  "eq",
+  "neq",
+  "lt",
+  "lte",
+  "gt",
+  "gte",
+  "exists",
+  "not_exists",
+  "between",
+  "contains",
+  "not_contains",
+  "is_true",
+  "is_false",
+  "regex",
+  "not_regex",
+  "relative_current_time",
+  "relative_event_time",
+  "array_contains",
+  "in_cluster",
+  "not_in_cluster"
+]);
+var AUDIENCE_AGGREGATIONS = /* @__PURE__ */ new Set([
+  "count",
+  "active_days",
+  "sum",
+  "avg",
+  "max",
+  "min",
+  "distinct_count"
+]);
+var METRIC_AGGREGATIONS = /* @__PURE__ */ new Set([
+  "total_count",
+  "user_count",
+  "per_user_count",
+  "sum",
+  "avg",
+  "avg_per_user",
+  "max",
+  "min",
+  "distinct_count",
+  "median",
+  "percentile",
+  "variance",
+  "stddev"
+]);
+var TASK_TRIGGER_PERIOD_SYMBOLS = /* @__PURE__ */ new Set(["TS01", "TS02", "TS03", "TS04"]);
+function validateSemanticAudienceDefinition(value, path) {
+  const definition = object(value, path);
+  rejectUnknown(definition, ["type", "conditions", "include_filter", "exclude_filter"], path);
+  exactString(definition.type, "condition", `${path}.type`);
+  validateGroup(definition.conditions, `${path}.conditions`);
+  optional(definition.include_filter, (item) => validateGroup(item, `${path}.include_filter`));
+  optional(definition.exclude_filter, (item) => validateGroup(item, `${path}.exclude_filter`));
+}
+function validateSemanticEventDefinition(value, path) {
+  const event = object(value, path);
+  rejectUnknown(event, [
+    "type",
+    "event",
+    "operator",
+    "value",
+    "aggregation",
+    "property",
+    "time_range",
+    "filters"
+  ], path);
+  exactString(event.type, "event", `${path}.type`);
+  nonBlankString(event.event, `${path}.event`);
+  optionalEnum(event.operator, OPERATORS, `${path}.operator`);
+  optionalNumber(event.value, `${path}.value`);
+  optionalEnum(event.aggregation, AUDIENCE_AGGREGATIONS, `${path}.aggregation`);
+  optionalString(event.property, `${path}.property`);
+  optional(event.time_range, (item) => validateTimeRange(item, `${path}.time_range`));
+  optional(event.filters, (item) => validateFilterGroup(item, `${path}.filters`));
+}
+function validateSemanticMetricDefinition(value, path) {
+  const metric = object(value, path);
+  if (metric.type === "event") {
+    validateMetricEvent(metric, path, false);
+    return;
+  }
+  if (metric.type === "formula") {
+    rejectUnknown(metric, ["type", "expression", "dependencies", "format"], path);
+    nonBlankString(metric.expression, `${path}.expression`);
+    optionalString(metric.format, `${path}.format`);
+    array(metric.dependencies, `${path}.dependencies`, 1).forEach((dependency, index) => validateMetricEvent(
+      object(dependency, `${path}.dependencies[${index}]`),
+      `${path}.dependencies[${index}]`,
+      true
+    ));
+    return;
+  }
+  invalid(`${path}.type must be event or formula.`);
+}
+function validateEmbeddedSemanticDefinitions(value, path) {
+  walk(value, path);
+}
+function validateTaskTriggerPeriodDefinition(value, path) {
+  const request = object(value, path);
+  if (!isObject(request.triggerConfig)) return;
+  const triggerConfig = request.triggerConfig;
+  if (triggerConfig.triggerDefinition === void 0 || triggerConfig.triggerDefinition === null) return;
+  const definition = object(triggerConfig.triggerDefinition, `${path}.triggerConfig.triggerDefinition`);
+  const rules = array(definition.rules, `${path}.triggerConfig.triggerDefinition.rules`, 1);
+  const primaryRule = object(rules[0], `${path}.triggerConfig.triggerDefinition.rules[0]`);
+  const symbolPath = `${path}.triggerConfig.triggerDefinition.rules[0].periodTimeSymbol`;
+  required(primaryRule.periodTimeSymbol, symbolPath);
+  enumValue(primaryRule.periodTimeSymbol, TASK_TRIGGER_PERIOD_SYMBOLS, symbolPath);
+}
+function walk(value, path) {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => walk(item, `${path}[${index}]`));
+    return;
+  }
+  if (!isObject(value)) return;
+  for (const [key, item] of Object.entries(value)) {
+    const itemPath = `${path}.${key}`;
+    if (item === void 0 || item === null) continue;
+    if (["definitionRequest", "targetDefinitionRequest", "topicDefinitionRequest"].includes(key)) {
+      validateSemanticAudienceDefinition(item, itemPath);
+    } else if (key === "eventDefinition") {
+      validateSemanticEventDefinition(item, itemPath);
+    } else if (key === "triggerDefinition") {
+      validateTriggerDefinition(item, itemPath);
+    } else if (key === "config" && typeof item === "string") {
+      walkJsonString(item, itemPath);
+    } else {
+      walk(item, itemPath);
+    }
+  }
+}
+function validateTriggerDefinition(value, path) {
+  const definition = object(value, path);
+  rejectUnknown(definition, ["rules"], path);
+  array(definition.rules, `${path}.rules`, 1).forEach((ruleValue, ruleIndex) => {
+    const rulePath = `${path}.rules[${ruleIndex}]`;
+    const rule = object(ruleValue, rulePath);
+    array(rule.events, `${rulePath}.events`, 1).forEach((event, eventIndex) => {
+      const eventPath = `${rulePath}.events[${eventIndex}]`;
+      const candidate = object(event, eventPath);
+      if ("eventDefinition" in candidate) {
+        validateSemanticEventDefinition(candidate.eventDefinition, `${eventPath}.eventDefinition`);
+      } else {
+        validateSemanticEventDefinition(candidate, eventPath);
+      }
+    });
+    optional(rule.blackList, (items) => array(items, `${rulePath}.blackList`).forEach((event, index) => validateSemanticEventDefinition(
+      event,
+      `${rulePath}.blackList[${index}]`
+    )));
+  });
+}
+function validateGroup(value, path) {
+  const group = object(value, path);
+  rejectUnknown(group, ["relation", "items"], path);
+  enumValue(group.relation, /* @__PURE__ */ new Set(["and", "or"]), `${path}.relation`);
+  array(group.items, `${path}.items`, 1).forEach((item, index) => validateCondition(item, `${path}.items[${index}]`));
+}
+function validateCondition(value, path) {
+  const condition = object(value, path);
+  switch (condition.type) {
+    case "event":
+      validateSemanticEventDefinition(condition, path);
+      required(condition.time_range, `${path}.time_range`);
+      return;
+    case "user":
+    case "tag":
+    case "cluster":
+      validatePropertyCondition(condition, path);
+      return;
+    case "compound":
+      rejectUnknown(condition, ["type", "group"], path);
+      validateGroup(condition.group, `${path}.group`);
+      return;
+    case "behavior_sequence":
+      validateBehaviorSequence(condition, path);
+      return;
+    default:
+      invalid(`${path}.type is unsupported.`);
+  }
+}
+function validatePropertyCondition(condition, path) {
+  const extended = condition.type === "tag" || condition.type === "cluster";
+  rejectUnknown(condition, [
+    "type",
+    "field",
+    "operator",
+    "values",
+    "time_relative",
+    "time_unit",
+    ...extended ? ["cluster_date_policy", "specified_cluster_date"] : []
+  ], path);
+  validateField(condition.field, `${path}.field`);
+  if (condition.type === "user") enumValue(condition.operator, OPERATORS, `${path}.operator`);
+  else optionalEnum(condition.operator, OPERATORS, `${path}.operator`);
+  optional(condition.values, (item) => array(item, `${path}.values`));
+  optionalString(condition.time_relative, `${path}.time_relative`);
+  optionalString(condition.time_unit, `${path}.time_unit`);
+  optionalString(condition.cluster_date_policy, `${path}.cluster_date_policy`);
+  optionalString(condition.specified_cluster_date, `${path}.specified_cluster_date`);
+}
+function validateBehaviorSequence(condition, path) {
+  rejectUnknown(condition, ["type", "completed", "steps", "time_range", "window"], path);
+  if (typeof condition.completed !== "boolean") invalid(`${path}.completed must be a boolean.`);
+  array(condition.steps, `${path}.steps`, 1).forEach((stepValue, index) => {
+    const stepPath = `${path}.steps[${index}]`;
+    const step = object(stepValue, stepPath);
+    rejectUnknown(step, ["event", "completed", "filters", "relative_to_first", "window"], stepPath);
+    nonBlankString(step.event, `${stepPath}.event`);
+    optionalBoolean(step.completed, `${stepPath}.completed`);
+    optionalBoolean(step.relative_to_first, `${stepPath}.relative_to_first`);
+    if (index === 1 && step.relative_to_first === true) {
+      invalid(`${stepPath}.relative_to_first must be false or omitted for the second step.`);
+    }
+    optional(step.filters, (item) => validateFilterGroup(item, `${stepPath}.filters`));
+    optional(step.window, (item) => validateWindow(item, `${stepPath}.window`));
+  });
+  required(condition.time_range, `${path}.time_range`);
+  validateTimeRange(condition.time_range, `${path}.time_range`);
+  optional(condition.window, (item) => validateWindow(item, `${path}.window`));
+}
+function validateFilterGroup(value, path) {
+  const group = object(value, path);
+  rejectUnknown(group, ["relation", "items"], path);
+  optionalEnum(group.relation, /* @__PURE__ */ new Set(["and", "or"]), `${path}.relation`);
+  array(group.items, `${path}.items`, 1).forEach((filterValue, index) => {
+    const filterPath = `${path}.items[${index}]`;
+    const filter = object(filterValue, filterPath);
+    rejectUnknown(filter, ["field", "operator", "values"], filterPath);
+    validateField(filter.field, `${filterPath}.field`);
+    enumValue(filter.operator, OPERATORS, `${filterPath}.operator`);
+    optional(filter.values, (item) => array(item, `${filterPath}.values`));
+  });
+}
+function validateField(value, path) {
+  if (typeof value === "string") {
+    nonBlankString(value, path);
+    return;
+  }
+  const field = object(value, path);
+  rejectUnknown(field, ["name", "type"], path);
+  nonBlankString(field.name, `${path}.name`);
+  optionalEnum(field.type, /* @__PURE__ */ new Set([
+    "event_property",
+    "user_property",
+    "tag",
+    "cluster"
+  ]), `${path}.type`);
+}
+function validateTimeRange(value, path) {
+  const range = object(value, path);
+  rejectUnknown(range, ["mode", "unit", "value", "start_time", "end_time"], path);
+  if (range.mode === "custom") {
+    nonBlankString(range.start_time, `${path}.start_time`);
+    nonBlankString(range.end_time, `${path}.end_time`);
+    return;
+  }
+  enumValue(range.mode, /* @__PURE__ */ new Set(["recent", "previous"]), `${path}.mode`);
+  optional(range.unit, (unit) => exactString(unit, "day", `${path}.unit`));
+  positiveInteger(range.value, `${path}.value`);
+}
+function validateWindow(value, path) {
+  const window = object(value, path);
+  rejectUnknown(window, ["value", "unit"], path);
+  positiveInteger(window.value, `${path}.value`);
+  nonBlankString(window.unit, `${path}.unit`);
+}
+function validateMetricEvent(metric, path, dependency) {
+  rejectUnknown(metric, [
+    "type",
+    ...dependency ? ["key"] : [],
+    "event",
+    "aggregation",
+    "property",
+    "percentile",
+    "filters",
+    "display_name"
+  ], path);
+  exactString(metric.type, "event", `${path}.type`);
+  if (dependency) nonBlankString(metric.key, `${path}.key`);
+  nonBlankString(metric.event, `${path}.event`);
+  enumValue(metric.aggregation, METRIC_AGGREGATIONS, `${path}.aggregation`);
+  if (!["total_count", "user_count", "per_user_count"].includes(String(metric.aggregation))) {
+    nonBlankString(metric.property, `${path}.property`);
+  }
+  optionalString(metric.property, `${path}.property`);
+  if (metric.aggregation === "percentile") {
+    optionalNumber(metric.percentile, `${path}.percentile`);
+    if (typeof metric.percentile !== "number" || metric.percentile <= 0 || metric.percentile > 100) {
+      invalid(`${path}.percentile must be greater than 0 and at most 100.`);
+    }
+  } else if (metric.percentile !== void 0 && metric.percentile !== null) {
+    invalid(`${path}.percentile is only valid for percentile aggregation.`);
+  }
+  optionalString(metric.display_name, `${path}.display_name`);
+  optional(metric.filters, (item) => validateFilterGroup(item, `${path}.filters`));
+}
+function walkJsonString(value, path) {
+  try {
+    walk(JSON.parse(value), path);
+  } catch (error) {
+    if (error instanceof SyntaxError) invalid(`${path} must contain valid JSON.`);
+    throw error;
+  }
+}
+function object(value, path) {
+  if (!isObject(value)) invalid(`${path} must be a JSON object.`);
+  return value;
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function array(value, path, minLength = 0) {
+  if (!Array.isArray(value) || value.length < minLength) {
+    invalid(`${path} must be an array with at least ${minLength} item(s).`);
+  }
+  return value;
+}
+function rejectUnknown(value, allowed, path) {
+  const supported = new Set(allowed);
+  const unknown = Object.keys(value).find((key) => !supported.has(key));
+  if (unknown) invalid(`Unsupported field ${path}.${unknown}.`);
+}
+function optional(value, validate) {
+  if (value !== void 0 && value !== null) validate(value);
+}
+function required(value, path) {
+  if (value === void 0 || value === null) invalid(`${path} is required.`);
+}
+function nonBlankString(value, path) {
+  if (typeof value !== "string" || value.trim() === "") {
+    invalid(`${path} must be a non-blank string.`);
+  }
+}
+function optionalString(value, path) {
+  optional(value, (item) => nonBlankString(item, path));
+}
+function exactString(value, expected, path) {
+  if (value !== expected) invalid(`${path} must be ${expected}.`);
+}
+function enumValue(value, allowed, path) {
+  if (typeof value !== "string" || !allowed.has(value)) {
+    invalid(`${path} must be one of: ${[...allowed].join(", ")}.`);
+  }
+}
+function optionalEnum(value, allowed, path) {
+  optional(value, (item) => enumValue(item, allowed, path));
+}
+function optionalNumber(value, path) {
+  optional(value, (item) => {
+    if (typeof item !== "number" || !Number.isFinite(item)) invalid(`${path} must be a number.`);
+  });
+}
+function positiveInteger(value, path) {
+  if (!Number.isInteger(value) || value < 1) {
+    invalid(`${path} must be a positive integer.`);
+  }
+}
+function optionalBoolean(value, path) {
+  optional(value, (item) => {
+    if (typeof item !== "boolean") invalid(`${path} must be a boolean.`);
+  });
+}
+function invalid(message) {
+  throw new CliValidationError(message);
+}
+
 // src/commands/te-engage/engage-flow/flow/save.ts
 var allowedOperations = ["build", "preview", "commit"];
 function readRequest(ctx) {
@@ -223,6 +606,7 @@ function readRequest(ctx) {
   if ("sourceFlowUuid" in req) {
     throw new Error("Flag --req.sourceFlowUuid is unsupported; get the source flow and build nodes/edges instead");
   }
+  validateEmbeddedSemanticDefinitions(req, "--req");
   return req;
 }
 var flowSave = createEngageFlowCapabilityCommand({
@@ -246,6 +630,30 @@ var flowSave = createEngageFlowCapabilityCommand({
   buildInput: (ctx) => ({ project_id: ctx.num("project-id"), req: readRequest(ctx) })
 });
 
+// src/commands/te-engage/engage-flow/metric/update.ts
+var flowMetricUpdate = createEngageFlowCapabilityCommand({
+  resource: "metric",
+  command: "update",
+  capabilityId: "engage-flow.metric.update",
+  description: "Update metric settings for a flow canvas.",
+  flags: [
+    { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+    { name: "flow-id", type: "string", required: true, desc: "Logical flow ID." },
+    {
+      name: "metric-map",
+      type: "json",
+      required: true,
+      desc: "Metric configuration map keyed by metric group."
+    }
+  ],
+  risk: "write",
+  buildInput: (ctx) => ({
+    project_id: ctx.num("project-id"),
+    flow_id: ctx.str("flow-id"),
+    metric_map: ctx.json("metric-map")
+  })
+});
+
 // src/commands/te-engage/engage-flow/node-config/schema.ts
 var nodeConfigSchema = createEngageFlowCapabilityCommand({
   resource: "node-config",
@@ -281,6 +689,208 @@ var nodeConfigValidate = createEngageFlowCapabilityCommand({
   })
 });
 
+// src/commands/te-engage/engage-flow/report/shared.ts
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+var flowReportCommonFlags = [
+  { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+  { name: "flow-id", type: "string", required: false, desc: "Logical flow ID." },
+  { name: "flow-uuid", type: "string", required: false, desc: "Flow version UUID." },
+  { name: "request-id", type: "string", required: false, desc: "Query correlation ID. Generated when omitted." },
+  { name: "push-language-code", type: "string", required: false, desc: "Push language code." },
+  { name: "show-time-zone", type: "string", required: false, desc: "Display timezone offset." }
+];
+var flowMetricDetailFlags = [
+  ...flowReportCommonFlags,
+  { name: "node-uuid", type: "string", required: true, desc: "Flow node UUID." },
+  { name: "start-time", type: "string", required: true, desc: "Start date in yyyy-MM-dd format." },
+  { name: "end-time", type: "string", required: true, desc: "End date in yyyy-MM-dd format." },
+  { name: "branch-id", type: "string", required: false, desc: "Optional branch ID." },
+  { name: "indicator-name", type: "string", required: false, desc: "Optional indicator name." },
+  { name: "indicators-uuid", type: "string", required: false, desc: "Optional AB metric indicator UUID." },
+  { name: "data-dim-type", type: "string", required: false, desc: "Data dimension type, usually uv or pv." },
+  { name: "report-mode", type: "string", required: false, desc: "Metric report mode: node or ab. Defaults to node." }
+];
+var flowUserDetailFlags = [
+  { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+  { name: "flow-id", type: "string", required: false, desc: "Logical flow ID." },
+  { name: "flow-uuid", type: "string", required: false, desc: "Flow version UUID." },
+  { name: "request-id", type: "string", required: false, desc: "Query correlation ID. Generated when omitted." },
+  { name: "cluster-def", type: "string", required: false, desc: "Legacy cluster definition JSON. Prefer the report metric fields below." },
+  { name: "indicator-name", type: "string", required: false, desc: "Metric key returned by the corresponding flow report." },
+  { name: "data-view-type", type: "string", required: false, desc: "Data view type. Defaults to 2 (date view)." },
+  { name: "is-summary", type: "boolean", required: false, desc: "Whether to query a summary segment. Defaults to false." },
+  { name: "start-time", type: "string", required: false, desc: "Segment start date in yyyy-MM-dd format." },
+  { name: "end-time", type: "string", required: false, desc: "Segment end date in yyyy-MM-dd format." },
+  { name: "push-language-code", type: "string", required: false, desc: "Optional push language code from the report context." },
+  { name: "user-time-zone", type: "string", required: false, desc: "Optional user timezone." },
+  { name: "show-time-zone", type: "string", required: false, desc: "Optional report display timezone." },
+  { name: "node-uuid", type: "string", required: false, desc: "Flow node UUID." },
+  { name: "branch-id", type: "string", required: false, desc: "Optional branch ID." }
+];
+var flowNodeUserDetailFlags = flowUserDetailFlags.map((flag) => flag.name === "node-uuid" ? { ...flag, required: true } : flag);
+var inlineLimitFlag = {
+  name: "limit",
+  type: "number",
+  required: false,
+  desc: "Maximum number of rows returned inline. Defaults to backend value."
+};
+var timeoutSecondsFlag = {
+  name: "timeout-seconds",
+  type: "number",
+  required: false,
+  desc: "Query or export timeout in seconds. Defaults to backend policy."
+};
+var exportFormatFlags = [
+  {
+    name: "artifact-format",
+    type: "string",
+    required: false,
+    desc: "Export artifact format. Flow report and user detail exports support csv or jsonl. Defaults to jsonl."
+  }
+];
+function validateFlowReportInput(ctx) {
+  if (!ctx.str("flow-id") && !ctx.str("flow-uuid")) {
+    printError("validation", "At least one of --flow-id or --flow-uuid is required");
+    process.exit(1);
+  }
+  validateDate(ctx.str("start-time"), "--start-time");
+  validateDate(ctx.str("end-time"), "--end-time");
+}
+function validateFlowUserDetailInput(ctx) {
+  if (!ctx.str("flow-id") && !ctx.str("flow-uuid")) {
+    printError("validation", "At least one of --flow-id or --flow-uuid is required");
+    process.exit(1);
+  }
+  if (!ctx.str("cluster-def") && (!ctx.str("indicator-name") || !ctx.str("start-time") || !ctx.str("end-time"))) {
+    printError("validation", "Pass either --cluster-def or --indicator-name with --start-time and --end-time");
+    process.exit(1);
+  }
+  validateDate(ctx.str("start-time"), "--start-time");
+  validateDate(ctx.str("end-time"), "--end-time");
+}
+function buildFlowReportInput(ctx) {
+  return {
+    project_id: ctx.num("project-id"),
+    flow_id: ctx.str("flow-id") || void 0,
+    flow_uuid: ctx.str("flow-uuid") || void 0,
+    request_id: ctx.str("request-id") || void 0,
+    push_language_code: ctx.str("push-language-code") || void 0,
+    show_time_zone: ctx.str("show-time-zone") || void 0,
+    node_uuid: ctx.str("node-uuid") || void 0,
+    branch_id: ctx.str("branch-id") || void 0,
+    indicator_name: ctx.str("indicator-name") || void 0,
+    indicators_uuid: ctx.str("indicators-uuid") || void 0,
+    data_dim_type: ctx.str("data-dim-type") || void 0,
+    start_time: ctx.str("start-time") || void 0,
+    end_time: ctx.str("end-time") || void 0,
+    report_mode: ctx.str("report-mode") || void 0,
+    cluster_def: ctx.str("cluster-def") || void 0,
+    limit: ctx.optionalNum("limit"),
+    format: ctx.str("artifact-format") || void 0,
+    timeout_seconds: ctx.optionalNum("timeout-seconds")
+  };
+}
+function buildFlowUserDetailInput(ctx) {
+  return {
+    project_id: ctx.num("project-id"),
+    flow_id: ctx.str("flow-id") || void 0,
+    flow_uuid: ctx.str("flow-uuid") || void 0,
+    request_id: ctx.str("request-id") || void 0,
+    node_uuid: ctx.str("node-uuid") || void 0,
+    branch_id: ctx.str("branch-id") || void 0,
+    cluster_def: ctx.str("cluster-def") || void 0,
+    indicator_name: ctx.str("indicator-name") || void 0,
+    data_view_type: ctx.str("data-view-type") || void 0,
+    is_summary: readOptionalBoolean(ctx, "is-summary"),
+    start_time: ctx.str("start-time") || void 0,
+    end_time: ctx.str("end-time") || void 0,
+    push_language_code: ctx.str("push-language-code") || void 0,
+    user_time_zone: ctx.str("user-time-zone") || void 0,
+    show_time_zone: ctx.str("show-time-zone") || void 0,
+    limit: ctx.optionalNum("limit"),
+    format: ctx.str("artifact-format") || void 0,
+    timeout_seconds: ctx.optionalNum("timeout-seconds")
+  };
+}
+function validateDate(value, flag) {
+  if (value && !ISO_DATE.test(value)) {
+    printError("validation", `${flag} must be in yyyy-MM-dd format`);
+    process.exit(1);
+  }
+}
+
+// src/commands/te-engage/engage-flow/metric-user/export.ts
+var metricUserExport = createEngageFlowCapabilityCommand({
+  resource: "metric-user",
+  command: "export",
+  capabilityId: "engage-flow.metric-user.export",
+  description: "Export users behind a flow metric segment.",
+  flags: [...flowUserDetailFlags, ...exportFormatFlags, timeoutSecondsFlag],
+  risk: "read",
+  validate: validateFlowUserDetailInput,
+  buildInput: buildFlowUserDetailInput
+});
+
+// src/commands/te-engage/engage-flow/metric-user/run.ts
+var metricUserRun = createEngageFlowCapabilityCommand({
+  resource: "metric-user",
+  command: "run",
+  capabilityId: "engage-flow.metric-user.run",
+  description: "Query users behind a flow metric segment inline.",
+  flags: [...flowUserDetailFlags, inlineLimitFlag, timeoutSecondsFlag],
+  risk: "read",
+  validate: validateFlowUserDetailInput,
+  buildInput: buildFlowUserDetailInput
+});
+
+// src/commands/te-engage/engage-flow/node-metric-user/export.ts
+var nodeMetricUserExport = createEngageFlowCapabilityCommand({
+  resource: "node-metric-user",
+  command: "export",
+  capabilityId: "engage-flow.node-metric-user.export",
+  description: "Export users behind a flow node metric segment.",
+  flags: [...flowNodeUserDetailFlags, ...exportFormatFlags, timeoutSecondsFlag],
+  risk: "read",
+  validate: validateFlowUserDetailInput,
+  buildInput: buildFlowUserDetailInput
+});
+
+// src/commands/te-engage/engage-flow/node-metric-user/run.ts
+var nodeMetricUserRun = createEngageFlowCapabilityCommand({
+  resource: "node-metric-user",
+  command: "run",
+  capabilityId: "engage-flow.node-metric-user.run",
+  description: "Query users behind a flow node metric segment inline.",
+  flags: [...flowNodeUserDetailFlags, inlineLimitFlag, timeoutSecondsFlag],
+  risk: "read",
+  validate: validateFlowUserDetailInput,
+  buildInput: buildFlowUserDetailInput
+});
+
+// src/commands/te-engage/engage-flow/node-user/export.ts
+var nodeUserExport = createEngageFlowCapabilityCommand({
+  resource: "node-user",
+  command: "export",
+  capabilityId: "engage-flow.node-user.export",
+  description: "Export users behind a flow node segment.",
+  flags: [...flowNodeUserDetailFlags, ...exportFormatFlags, timeoutSecondsFlag],
+  risk: "read",
+  validate: validateFlowUserDetailInput,
+  buildInput: buildFlowUserDetailInput
+});
+
+// src/commands/te-engage/engage-flow/node-user/run.ts
+var nodeUserRun = createEngageFlowCapabilityCommand({
+  resource: "node-user",
+  command: "run",
+  capabilityId: "engage-flow.node-user.run",
+  description: "Query users behind a flow node segment inline.",
+  flags: [...flowNodeUserDetailFlags, inlineLimitFlag, timeoutSecondsFlag],
+  risk: "read",
+  validate: validateFlowUserDetailInput,
+  buildInput: buildFlowUserDetailInput
+});
+
 // src/commands/te-engage/engage-flow/operation-log/query.ts
 var operationLogQuery = createEngageFlowCapabilityCommand({
   resource: "operation-log",
@@ -295,6 +905,30 @@ var operationLogQuery = createEngageFlowCapabilityCommand({
   buildInput: (ctx) => ({ project_id: ctx.num("project-id"), flow_id: ctx.str("flow-id") })
 });
 
+// src/commands/te-engage/engage-flow/report/metric-detail-export.ts
+var flowReportMetricDetailExport = createEngageFlowCapabilityCommand({
+  resource: "report metric-detail",
+  command: "export",
+  capabilityId: "engage-flow.report.metric-detail.export",
+  description: "Export a flow node metric detail report artifact.",
+  flags: [...flowMetricDetailFlags, ...exportFormatFlags, timeoutSecondsFlag],
+  risk: "read",
+  validate: validateFlowReportInput,
+  buildInput: buildFlowReportInput
+});
+
+// src/commands/te-engage/engage-flow/report/metric-detail-run.ts
+var flowReportMetricDetailRun = createEngageFlowCapabilityCommand({
+  resource: "report metric-detail",
+  command: "run",
+  capabilityId: "engage-flow.report.metric-detail.run",
+  description: "Query a flow node metric detail report inline.",
+  flags: [...flowMetricDetailFlags, inlineLimitFlag, timeoutSecondsFlag],
+  risk: "read",
+  validate: validateFlowReportInput,
+  buildInput: buildFlowReportInput
+});
+
 // src/commands/te-engage/engage-flow/version/list.ts
 var versionList = createEngageFlowCapabilityCommand({
   resource: "version",
@@ -316,9 +950,18 @@ var commands = [
   flowSave,
   nodeConfigSchema,
   nodeConfigValidate,
+  flowMetricUpdate,
   flowModifyBaseInfo,
   flowManage,
   flowDelete,
+  flowReportMetricDetailRun,
+  flowReportMetricDetailExport,
+  metricUserRun,
+  metricUserExport,
+  nodeUserRun,
+  nodeUserExport,
+  nodeMetricUserRun,
+  nodeMetricUserExport,
   operationLogQuery,
   // testRun,
   versionList,
@@ -1042,6 +1685,12 @@ var presetEventUpdate = createEngageSettingCapabilityCommand({
     { name: "recharge-event-definition", type: "json", required: false, desc: "Semantic recharge event definition." }
   ],
   risk: "write",
+  validate: (ctx) => {
+    for (const name of ["add-event-definition", "active-event-definition", "recharge-event-definition"]) {
+      const definition = ctx.json(name);
+      if (definition !== void 0) validateSemanticEventDefinition(definition, `--${name}`);
+    }
+  },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
     add_event_definition: ctx.json("add-event-definition") || void 0,
@@ -1085,23 +1734,7 @@ var commonMetricGet = createEngageSettingCapabilityCommand({
 // src/commands/te-engage/engage-setting/common-metric/metric-qp-validation.ts
 var VALID_WINDOW_TIME_UNITS = /* @__PURE__ */ new Set(["minute", "hour", "day"]);
 function validateMetricDefinitionFlag(definition) {
-  if (definition === null || typeof definition !== "object" || Array.isArray(definition)) {
-    printError(
-      "validation",
-      "--metric-definition must be a JSON object.",
-      "Pass a semantic event or formula metric definition."
-    );
-    process.exit(1);
-  }
-  const type = definition.type;
-  if (type !== "event" && type !== "formula") {
-    printError(
-      "validation",
-      "--metric-definition.type must be event or formula.",
-      "Do not pass legacy type=0/1 metric_qp."
-    );
-    process.exit(1);
-  }
+  validateSemanticMetricDefinition(definition, "--metric-definition");
 }
 function validateMetricWindowTimeUnitFlag(unit) {
   if (VALID_WINDOW_TIME_UNITS.has(unit)) {
@@ -1587,6 +2220,16 @@ var presetMetricSet = createEngageSceneCapabilityCommand({
     { name: "attend-event-definition", type: "json", required: false, desc: "Semantic attend event definition." }
   ],
   risk: "write",
+  validate: (ctx) => {
+    for (const name of [
+      "impression-event-definition",
+      "click-event-definition",
+      "attend-event-definition"
+    ]) {
+      const definition = ctx.json(name);
+      if (definition !== void 0) validateSemanticEventDefinition(definition, `--${name}`);
+    }
+  },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
     config_id: ctx.str("config-id"),
@@ -1865,9 +2508,13 @@ var strategyCreate = createEngageSceneCapabilityCommand({
     }
   ],
   risk: "write",
+  validate: (ctx) => {
+    const payload = readRequiredJsonObject(ctx, "payload");
+    validateEmbeddedSemanticDefinitions(payload, "--payload");
+  },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
-    payload: ctx.json("payload")
+    payload: readRequiredJsonObject(ctx, "payload")
   })
 });
 
@@ -1964,9 +2611,13 @@ var strategyUpdate = createEngageSceneCapabilityCommand({
     }
   ],
   risk: "write",
+  validate: (ctx) => {
+    const payload = readRequiredJsonObject(ctx, "payload");
+    validateEmbeddedSemanticDefinitions(payload, "--payload");
+  },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
-    payload: ctx.json("payload")
+    payload: readRequiredJsonObject(ctx, "payload")
   })
 });
 
@@ -2022,7 +2673,10 @@ var strategyPredict = createEngageSceneCapabilityCommand({
   ],
   risk: "read",
   validate: (ctx) => {
-    readRequiredJsonObject(ctx, "definition-request");
+    validateSemanticAudienceDefinition(
+      readRequiredJsonObject(ctx, "definition-request"),
+      "--definition-request"
+    );
   },
   buildInput: (ctx) => ({
     project_id: ctx.num("project-id"),
@@ -2513,6 +3167,7 @@ var TOPIC_TASK_EXCLUSION_FIELDS = /* @__PURE__ */ new Set([
 ]);
 function validateStandaloneActivityPayload(value) {
   const payload = requireObject(value);
+  validateEmbeddedSemanticDefinitions(payload, "payload");
   validateTriggerType(payload.triggerType, "triggerType");
   validateScheduleFields(payload);
   validateExperiment(payload.expConfig, "expConfig");
@@ -2536,6 +3191,7 @@ function validateStandaloneActivityPayload(value) {
 }
 function validateActivityTopicPayload(value) {
   const payload = requireObject(value);
+  validateEmbeddedSemanticDefinitions(payload, "payload");
   validateTriggerType(payload.triggerType, "triggerType");
   validateScheduleFields(payload);
   validateExperiment(payload.expConfig, "expConfig");
@@ -2610,7 +3266,7 @@ function validateScheduleFields(payload) {
 }
 function validateExperiment(value, field) {
   if (value === void 0 || value === null) return;
-  if (!isObject(value)) {
+  if (!isObject2(value)) {
     fail(
       `${field} must be omitted or set to {"enableExp":false}.`,
       "ACTIVITY_EXPERIMENT_UNSUPPORTED",
@@ -2641,7 +3297,7 @@ function validateSingleContentGroup(value, field) {
   }
 }
 function requireObject(value, field = "payload") {
-  if (!isObject(value)) {
+  if (!isObject2(value)) {
     fail(
       `${field} must be a JSON object.`,
       "ACTIVITY_PAYLOAD_INVALID",
@@ -2653,7 +3309,7 @@ function requireObject(value, field = "payload") {
 }
 function containsAnyKey(value, keys) {
   if (Array.isArray(value)) return value.some((item) => containsAnyKey(item, keys));
-  if (!isObject(value)) return false;
+  if (!isObject2(value)) return false;
   return Object.entries(value).some(
     ([key, item]) => keys.has(key) && hasValue(item) || containsAnyKey(item, keys)
   );
@@ -2662,10 +3318,10 @@ function hasValue(value) {
   if (value === void 0 || value === null) return false;
   if (typeof value === "string") return value.trim().length > 0;
   if (Array.isArray(value)) return value.length > 0;
-  if (isObject(value)) return Object.keys(value).length > 0;
+  if (isObject2(value)) return Object.keys(value).length > 0;
   return true;
 }
-function isObject(value) {
+function isObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function fail(message, code, field, hint) {
@@ -3074,6 +3730,121 @@ var channelRefStats = createEngageTaskCapabilityCommand({
   })
 });
 
+// src/commands/te-engage/engage-task/task-data-shared.ts
+var ISO_DATE2 = /^\d{4}-\d{2}-\d{2}$/;
+var taskMetricDetailFlags = [
+  { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+  { name: "task-id", type: "string", required: true, desc: "Engagement task ID." },
+  { name: "start-time", type: "string", required: true, desc: "Start date in yyyy-MM-dd format." },
+  { name: "end-time", type: "string", required: true, desc: "End date in yyyy-MM-dd format." },
+  { name: "metric-id-list", type: "json", required: false, desc: "Optional metric setting ID JSON array." },
+  { name: "group-type", type: "number", required: false, desc: "Optional metric grouping mode: 1, 2, 3, or 4." },
+  { name: "push-language-code", type: "string", required: false, desc: "Optional push content language code." },
+  { name: "show-time-zone", type: "string", required: false, desc: "Display timezone offset, such as 8.0 or -5.0." },
+  { name: "request-id", type: "string", required: false, desc: "Caller-provided report request ID." }
+];
+var taskDataDetailFlags = [
+  { name: "project-id", type: "number", required: true, alias: "p", desc: "Numeric project ID." },
+  { name: "task-id", type: "string", required: true, desc: "Engagement task ID." },
+  { name: "detail-type", type: "string", required: true, desc: "Detail mode: time, instance, or instance_daily." },
+  { name: "start-time", type: "string", required: true, desc: "Start date in yyyy-MM-dd format." },
+  { name: "end-time", type: "string", required: true, desc: "End date in yyyy-MM-dd format." },
+  { name: "task-instance-id", type: "string", required: false, desc: "Task instance ID. Required when detail-type is instance_daily." },
+  { name: "data-dim-type", type: "string", required: false, desc: "Data dimension type: uv or pv." },
+  { name: "retention-type", type: "string", required: false, desc: "Optional retention mode: retention or lost." },
+  { name: "data-view-type", type: "number", required: false, desc: "Triggered-task detail view type: 2 or 3." },
+  { name: "push-language-code", type: "string", required: false, desc: "Optional push content language code." },
+  { name: "show-time-zone", type: "string", required: false, desc: "Display timezone offset, such as 8.0 or -5.0." },
+  { name: "request-id", type: "string", required: false, desc: "Caller-provided report request ID." }
+];
+function validateTaskMetricDetailInput(ctx) {
+  validateDateRange(ctx);
+  const metricIdList = ctx.json("metric-id-list");
+  if (metricIdList != null && !Array.isArray(metricIdList)) {
+    printError("validation", "--metric-id-list must be a JSON array");
+    process.exit(1);
+  }
+}
+function validateTaskDataDetailInput(ctx) {
+  validateDateRange(ctx);
+  const detailType = ctx.str("detail-type");
+  if (!["time", "instance", "instance_daily"].includes(detailType)) {
+    printError("validation", "--detail-type must be time, instance, or instance_daily");
+    process.exit(1);
+  }
+  if (detailType === "instance_daily" && !ctx.str("task-instance-id")) {
+    printError("validation", "--task-instance-id is required when --detail-type is instance_daily");
+    process.exit(1);
+  }
+}
+function buildTaskMetricDetailInput(ctx) {
+  return {
+    project_id: ctx.num("project-id"),
+    task_id: ctx.str("task-id"),
+    start_time: ctx.str("start-time"),
+    end_time: ctx.str("end-time"),
+    metric_id_list: ctx.json("metric-id-list") || void 0,
+    group_type: ctx.optionalNum("group-type"),
+    push_language_code: ctx.str("push-language-code") || void 0,
+    show_time_zone: ctx.str("show-time-zone") || void 0,
+    request_id: ctx.str("request-id") || void 0
+  };
+}
+function buildTaskDataDetailInput(ctx) {
+  return {
+    project_id: ctx.num("project-id"),
+    task_id: ctx.str("task-id"),
+    detail_type: ctx.str("detail-type"),
+    task_instance_id: ctx.str("task-instance-id") || void 0,
+    start_time: ctx.str("start-time"),
+    end_time: ctx.str("end-time"),
+    data_dim_type: ctx.str("data-dim-type") || void 0,
+    retention_type: ctx.str("retention-type") || void 0,
+    data_view_type: ctx.optionalNum("data-view-type"),
+    push_language_code: ctx.str("push-language-code") || void 0,
+    show_time_zone: ctx.str("show-time-zone") || void 0,
+    request_id: ctx.str("request-id") || void 0
+  };
+}
+function validateDateRange(ctx) {
+  validateDate2(ctx.str("start-time"), "--start-time");
+  validateDate2(ctx.str("end-time"), "--end-time");
+  if (ctx.str("start-time") > ctx.str("end-time")) {
+    printError("validation", "--start-time must be earlier than or equal to --end-time");
+    process.exit(1);
+  }
+}
+function validateDate2(value, flag) {
+  if (value && !ISO_DATE2.test(value)) {
+    printError("validation", `${flag} must be in yyyy-MM-dd format`);
+    process.exit(1);
+  }
+}
+
+// src/commands/te-engage/engage-task/data-detail/query.ts
+var dataDetailQuery = createEngageTaskCapabilityCommand({
+  resource: "data-detail",
+  command: "query",
+  capabilityId: "engage-task.task-data.detail",
+  description: "Query task data-detail report data.",
+  flags: taskDataDetailFlags,
+  risk: "read",
+  validate: validateTaskDataDetailInput,
+  buildInput: buildTaskDataDetailInput
+});
+
+// src/commands/te-engage/engage-task/effect/query.ts
+var taskEffectQuery = createEngageTaskCapabilityCommand({
+  resource: "effect",
+  command: "query",
+  capabilityId: "engage-task.task-data.metric-detail",
+  description: "Query task metric-detail report data.",
+  flags: taskMetricDetailFlags,
+  risk: "read",
+  validate: validateTaskMetricDetailInput,
+  buildInput: buildTaskMetricDetailInput
+});
+
 // src/commands/te-engage/engage-task/group/create.ts
 var groupCreate = createEngageTaskCapabilityCommand({
   resource: "group",
@@ -3203,7 +3974,7 @@ var operationLogQuery2 = createEngageTaskCapabilityCommand({
 });
 
 // src/commands/te-engage/engage-task/push-record/query.ts
-var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+var ISO_DATE3 = /^\d{4}-\d{2}-\d{2}$/;
 var pushRecordQuery = createEngageTaskCapabilityCommand({
   resource: "push-record",
   command: "query",
@@ -3231,11 +4002,11 @@ var pushRecordQuery = createEngageTaskCapabilityCommand({
   validate: (ctx) => {
     const startDate = ctx.str("start-date");
     const endDate = ctx.str("end-date");
-    if (startDate && !ISO_DATE.test(startDate)) {
+    if (startDate && !ISO_DATE3.test(startDate)) {
       printError("validation", "--start-date must be in yyyy-MM-dd format");
       process.exit(1);
     }
-    if (endDate && !ISO_DATE.test(endDate)) {
+    if (endDate && !ISO_DATE3.test(endDate)) {
       printError("validation", "--end-date must be in yyyy-MM-dd format");
       process.exit(1);
     }
@@ -3517,12 +4288,14 @@ var taskSave = createEngageTaskCapabilityCommand({
       name: "req",
       type: "json",
       required: true,
-      desc: "Task save JSON; custom audiences use targetConfig.definitionRequest."
+      desc: "Task save JSON; triggered tasks require periodTimeSymbol on the primary trigger rule."
     }
   ],
   risk: "write",
   validate: (ctx) => {
-    readRequiredJsonObject(ctx, "req");
+    const req = readRequiredJsonObject(ctx, "req");
+    validateEmbeddedSemanticDefinitions(req, "--req");
+    validateTaskTriggerPeriodDefinition(req, "--req");
   },
   buildInput: (ctx) => ({ project_id: ctx.num("project-id"), req: readRequiredJsonObject(ctx, "req") })
 });
@@ -3552,6 +4325,8 @@ var commands6 = [
   taskBuildSaveGuide,
   taskSave,
   taskManage,
+  taskEffectQuery,
+  dataDetailQuery,
   channelRefStats,
   groupCreate,
   groupDelete,
@@ -3572,6 +4347,148 @@ var commands6 = [
 ];
 var engage_task_default = commands6;
 
+// src/commands/te-engage/engage-query/artifact/download.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+var artifactDownload = {
+  service: "engage-query",
+  resource: "artifact",
+  command: "download",
+  description: "Download a generated engagement query artifact.",
+  flags: [
+    { name: "run-id", type: "string", required: true, desc: "Query or export run ID." },
+    { name: "artifact-id", type: "string", required: true, desc: "Artifact ID returned by an export capability." },
+    { name: "output", type: "string", required: true, desc: "Local output file path. Use a file path, not a directory." }
+  ],
+  risk: "read",
+  dryRun: (ctx) => ({
+    method: "GET",
+    url: buildCapabilityGatewayUrl(
+      ctx.host(),
+      resolveGatewayDomain("engage-query", "engage"),
+      artifactPath(ctx.str("run-id"), ctx.str("artifact-id"))
+    ),
+    output_path: resolve(ctx.str("output"))
+  }),
+  execute: async (ctx) => {
+    const runId = ctx.str("run-id");
+    const artifactId = ctx.str("artifact-id");
+    const outputPath = resolve(ctx.str("output"));
+    await ensureArtifactReady(ctx.host(), runId, artifactId);
+    const resp = await fetchArtifact(ctx.host(), runId, artifactId);
+    const bytes = Buffer.from(await resp.arrayBuffer());
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, bytes);
+    return {
+      run_id: runId,
+      artifact_id: artifactId,
+      output_path: outputPath,
+      bytes: bytes.length,
+      content_type: resp.headers.get("content-type") ?? void 0,
+      content_encoding: resp.headers.get("content-encoding") ?? void 0,
+      content_disposition: resp.headers.get("content-disposition") ?? void 0
+    };
+  }
+};
+function artifactPath(runId, artifactId) {
+  return `runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactId)}/download`;
+}
+async function ensureArtifactReady(host, runId, artifactId) {
+  const descriptor = await inspectRun(host, runId);
+  const descriptorArtifactId = descriptor.artifact_id ?? descriptor.artifactId;
+  const artifactStatus = descriptor.artifact_status ?? descriptor.artifactStatus;
+  const errorMessage = descriptor.error_message ?? descriptor.errorMessage;
+  if (descriptorArtifactId && descriptorArtifactId !== artifactId) {
+    throw new CapabilityGatewayError(
+      `artifact_id ${artifactId} does not belong to run_id ${runId}`,
+      "ARTIFACT_RUN_MISMATCH",
+      400,
+      "Use the run_id and artifact_id pair from the same export response."
+    );
+  }
+  const ready = descriptor.status === "SUCCEEDED" && (artifactStatus === "READY" || artifactStatus === "COMPLETED");
+  if (ready) {
+    return;
+  }
+  const reason = errorMessage ? `; error=${errorMessage}` : "";
+  throw new CapabilityGatewayError(
+    `Artifact is not ready: run_status=${descriptor.status ?? "UNKNOWN"}, artifact_status=${artifactStatus ?? "UNKNOWN"}${reason}`,
+    "ARTIFACT_NOT_READY",
+    409,
+    "Run ae-cli engage-query run inspect --run-id <run_id> until status=SUCCEEDED and artifact_status=READY or COMPLETED, then retry artifact download. If status is FAILED or CANCELED, do not retry download."
+  );
+}
+async function inspectRun(host, runId) {
+  return await requestCapabilityGateway(
+    host,
+    resolveGatewayDomain("engage-query", "engage"),
+    `runs/${encodeURIComponent(runId)}`
+  );
+}
+async function fetchArtifact(host, runId, artifactId) {
+  return fetchCapabilityGateway(
+    host,
+    resolveGatewayDomain("engage-query", "engage"),
+    artifactPath(runId, artifactId),
+    "GET",
+    void 0,
+    "application/octet-stream"
+  );
+}
+
+// src/commands/te-engage/engage-query/query/cancel.ts
+var queryCancel = createEngageQueryCapabilityCommand({
+  resource: "query",
+  command: "cancel",
+  capabilityId: "engage-query.query.cancel",
+  description: "Cancel one running engagement query or export run.",
+  flags: [
+    { name: "run-id", type: "string", required: true, desc: "Query or export run ID." },
+    { name: "reason", type: "string", required: false, desc: "Optional cancellation reason." }
+  ],
+  risk: "write",
+  buildInput: (ctx) => ({
+    run_id: ctx.str("run-id"),
+    reason: ctx.str("reason") || void 0
+  })
+});
+
+// src/commands/te-engage/engage-query/run/inspect.ts
+var runInspect = {
+  service: "engage-query",
+  resource: "run",
+  command: "inspect",
+  description: "Inspect one engagement query or export run status.",
+  flags: [
+    { name: "run-id", type: "string", required: true, desc: "Query or export run ID." }
+  ],
+  risk: "read",
+  dryRun: (ctx) => ({
+    method: "GET",
+    url: buildCapabilityGatewayUrl(
+      ctx.host(),
+      resolveGatewayDomain("engage-query", "engage"),
+      `runs/${encodeURIComponent(ctx.str("run-id"))}`
+    )
+  }),
+  execute: async (ctx) => {
+    const result = await requestCapabilityGatewayWithEnvelope(
+      ctx.host(),
+      resolveGatewayDomain("engage-query", "engage"),
+      `runs/${encodeURIComponent(ctx.str("run-id"))}`
+    );
+    return withOutputMetadata(result.data, result.meta);
+  }
+};
+
+// src/commands/te-engage/engage-query/index.ts
+var commands7 = [
+  runInspect,
+  artifactDownload,
+  queryCancel
+];
+var engage_query_default = commands7;
+
 // src/commands/te-engage/index.ts
 registerCapabilityGatewayRoute("engage-flow", { gatewayDomain: "engage" });
 registerCapabilityGatewayRoute("engage-task", { gatewayDomain: "engage" });
@@ -3579,15 +4496,17 @@ registerCapabilityGatewayRoute("engage-setting", { gatewayDomain: "engage" });
 registerCapabilityGatewayRoute("engage-scene", { gatewayDomain: "engage" });
 registerCapabilityGatewayRoute("engage-activity", { gatewayDomain: "engage" });
 registerCapabilityGatewayRoute("engage-workbench", { gatewayDomain: "engage" });
-var commands7 = [
+registerCapabilityGatewayRoute("engage-query", { gatewayDomain: "engage" });
+var commands8 = [
   ...engage_flow_default,
   ...engage_task_default,
   ...engage_setting_default,
   ...engage_scene_default,
   ...engage_activity_default,
-  ...engage_workbench_default
+  ...engage_workbench_default,
+  ...engage_query_default
 ];
-var te_engage_default = commands7;
+var te_engage_default = commands8;
 export {
   te_engage_default as default
 };