@thinkingai/ae-cli 6.0.40 → 6.0.41

package/skills/ae-engage/references/flow-node-user.md

@@ -0,0 +1,122 @@
+# Flow node-user
+
+Use this reference when the user asks for users behind a node-level data segment on the flow canvas.
+
+Mapped CLI commands:
+
+- `ae-cli engage-flow node-user run`
+- `ae-cli engage-flow node-user export`
+
+Mapped capabilities:
+
+- `engage-flow.node-user.run`
+- `engage-flow.node-user.export`
+
+Hermes SQL source: `FlowNodeReportDataService#buildClusterUserSql`.
+
+## Choose the command
+
+- Use `run` for a bounded inline preview of users in the selected node data segment.
+- Use `export` for the full user-detail artifact.
+- Use `metric-user` for process-level flow metric cells.
+- Use `node-metric-user` for node metric cells.
+
+## Required input
+
+- `--project-id`
+- one of `--flow-id` or `--flow-uuid`
+- `--node-uuid`
+- either `--cluster-def '<cluster_def_json>'` or all of `--indicator-name`, `--start-time`, and `--end-time`
+
+## Optional input
+
+- `--branch-id`
+- `--request-id`
+- `--data-view-type` (default: `2`)
+- `--is-summary`
+- `--push-language-code`
+- `--user-time-zone`
+- `--show-time-zone`
+- `run` only: `--limit`
+- `export` only: `--artifact-format csv|jsonl` (default: `jsonl`)
+- `--timeout-seconds`
+
+Only pass fields listed above. Hermes rejects extra top-level fields for this capability.
+
+## Segment selector contract
+
+Prefer the explicit report fields. Set `--indicator-name` to the metric key returned by the node report and reuse the report date range. Hermes builds the internal cluster definition.
+
+`--cluster-def` remains available for compatibility. When used, it must come from the selected node report segment; do not invent it.
+
+Required keys:
+
+- `indicatorName`
+- `dataViewType`
+- `isSummary`
+
+Date keys depend on `isSummary`:
+
+- `isSummary=true`: require `filterStartDate` and `filterEndDate`
+- `isSummary=false`: require `startDate` and `endDate`
+
+Dates must use `yyyy-MM-dd`, and start must be earlier than or equal to end.
+
+## Examples
+
+Inline preview:
+
+```bash
+ae-cli engage-flow node-user run \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid node_uuid_123 \
+  --indicator-name entry \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --limit 100 \
+  --timeout-seconds 120
+```
+
+Export all matched users:
+
+```bash
+ae-cli engage-flow node-user export \
+  --project-id 1 \
+  --flow-id flow_id_123 \
+  --node-uuid node_uuid_123 \
+  --indicator-name entry \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --artifact-format csv \
+  --timeout-seconds 21600
+```
+
+## Export lifecycle
+
+`export` returns `run_id` and `artifact_id`. Poll and download with:
+
+```bash
+ae-cli engage-query run inspect --run-id <run_id>
+ae-cli engage-query artifact download \
+  --run-id <run_id> \
+  --artifact-id <artifact_id> \
+  --output ./flow-node-users.csv.gz
+```
+
+Downloaded artifacts are gzip-compressed; keep the `.gz` suffix. Cancel running async work with:
+
+```bash
+ae-cli engage-query query cancel --run-id <run_id>
+```
+
+## Output shape
+
+- `run` returns `rows`, `total`, and `column_meta`.
+- `export` writes one row per matched user. The primary column is usually `#user_id`.
+
+## Common mistakes
+
+- `--node-uuid` is required and must be the canvas node UUID.
+- Do not use this for node metric cells; use `node-metric-user` so Hermes routes to the metric SQL builder.
+- Use `--data-view-type`, not the report-only `--data-dim-type`, when selecting users without `--cluster-def`.

package/skills/ae-engage/references/push-record-query.md

@@ -23,4 +23,35 @@ ae-cli engage-task push-record query \
 
 ## Output
 
-Returns `record_type`, `items`, `total`, and pagination metadata when the selected backend record type is paginated. Records include available trigger, planned-send, actual-send, success, channel-exception, status, and failure-reason fields.
+Returns `record_type`, `items`, `total`, and pagination metadata when the selected backend record type is paginated.
+
+The count fields depend on `record_type`:
+
+| `record_type` | Actual push field | Successful push field |
+| --- | --- | --- |
+| `scheduled` | `actual_trigger_num` | `trigger_num` |
+| `user_time_zone` | `actual_trigger_num` | `trigger_num` |
+| `triggered` | `actual_push_num` | `push_success_num` |
+
+Scheduled records and nested user-time-zone execution records use stable English `status_name`
+values:
+
+| `status` | `status_name` |
+| --- | --- |
+| `0` | `Waiting` |
+| `1` | `Ready` |
+| `2` | `Pushing` |
+| `3` | `Sent` |
+| `4` | `Retrying` |
+| `5` | `Failed` |
+
+Top-level user-time-zone task instances use a separate status enum:
+
+| `status` | `status_name` |
+| --- | --- |
+| `0` | `Sending` |
+| `1` | `Sent` |
+| `2` | `Finished` |
+
+Use `status` and the count fields for automated assertions. `status_name` never returns an internal
+`hermes.*` localization key.

package/skills/ae-engage/references/save-task.md

@@ -221,6 +221,13 @@ Rules:
 - do not guess template IDs
 - `groupContentList` maximum size is `5`
 - `occasionKeys` are parsed from content automatically and are not accepted as input
+- when `expConfig.enableExp=true`, each `groupContentList` item must include
+  `expGroupName`, `expGroupType`, `percentageInExperiment`, and `order`, and the list must
+  mirror `expConfig.expGroupList` one-to-one by `expGroupName`
+- capability `engage-task.task.save` rejects misaligned experiment `groupContentList`
+  (`TASK_EXPERIMENT_GROUP_CONTENT_INVALID`) before the inner save service runs
+- do not submit experiment content as content-only objects such as
+  `{"contentList":[...]}` without the group association fields
 
 Content guidance:
 
@@ -257,6 +264,8 @@ Rules:
 - if `triggerDefinition` is needed, build it from semantic event definitions and resolve real
   event/property names through Analysis metadata
 - always set the A rule's `eventTriggerType` explicitly
+- always set the A rule's `periodTimeSymbol` to `TS01`, `TS02`, `TS03`, or `TS04`; it is
+  required even when `periodStart` and `periodEnd` are present
 - Hermes compiles the semantic event and then validates the final persisted trigger-rule envelope
 - for semantic event-trigger tasks, Hermes backfills missing task-level `startDate` / `endDate`
   from the A rule's `periodStart` / `periodEnd`; explicit task-level dates remain authoritative

package/skills/ae-engage/references/task-data-detail.md

@@ -2,10 +2,17 @@
 
 Query a task detail report through the L3 Capability Gateway.
 
-Mapped command: `ae-cli capability run engage-task.task-data.detail --input '<json>'`
+Mapped command: `ae-cli engage-task data-detail query`
+
+Capability ID: `engage-task.task-data.detail`
 
 Required input: `project_id`, `task_id`, `detail_type`, `start_time`, `end_time`. `detail_type` is `time`, `instance`, or `instance_daily`; the last form also requires `task_instance_id`.
 
 ```bash
-ae-cli capability run engage-task.task-data.detail --input '{"project_id":1,"task_id":"task_123","detail_type":"time","start_time":"2026-04-01","end_time":"2026-04-07"}'
+ae-cli engage-task data-detail query \
+  --project-id 1 \
+  --task-id task_123 \
+  --detail-type time \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07
 ```

package/skills/ae-engage/references/task-metric-detail.md

@@ -2,10 +2,17 @@
 
 Query a task metric detail report through the L3 Capability Gateway.
 
-Mapped command: `ae-cli capability run engage-task.task-data.metric-detail --input '<json>'`
+Mapped command: `ae-cli engage-task effect query`
+
+Capability ID: `engage-task.task-data.metric-detail`
 
 Required input: `project_id`, `task_id`, `start_time`, `end_time`. Optional input includes `request_id`, `push_language_code`, `metric_id_list`, `group_type`, and `show_time_zone`.
 
 ```bash
-ae-cli capability run engage-task.task-data.metric-detail --input '{"project_id":1,"task_id":"task_123","start_time":"2026-04-01","end_time":"2026-04-07"}'
+ae-cli engage-task effect query \
+  --project-id 1 \
+  --task-id task_123 \
+  --start-time 2026-04-01 \
+  --end-time 2026-04-07 \
+  --metric-id-list '["metric_1"]'
 ```

package/skills/ae-engage/references/task-submit-approval.md

@@ -27,6 +27,8 @@ Provide exactly one of `--task-id` or `--request`.
 
 - Prefer `task save` followed by `submit-approval --task-id`. The server loads the persisted draft, validates its
   trigger rule, and reuses the existing save-and-submit approval workflow.
+- Never put `taskId` or `task_id` inside `--request`. Existing drafts must use `--task-id`; embedded task IDs fail
+  with `REQUEST_TASK_ID_NOT_ALLOWED` so request fields are never silently discarded.
 - Do not reconstruct or pass `trigger_rule`. It is an internal persisted field.
 - The legacy `--request` mode remains available for existing callers.
 - Required body fields (server validates): `task_name`, `channel_type`, `channel_id`, `group_content_list`, `target_cluster_type`, `trigger_type`, `completion_indicator_def`, `frequency_limits`, `enable_channel_touch_limits`, `group_id`, `trigger_time_strategy`.
@@ -41,5 +43,6 @@ Provide exactly one of `--task-id` or `--request`.
 |---|---|
 | `APPROVAL_INPUT_INVALID` | neither or both of `task_id` and `request` supplied |
 | `REQUEST_REQUIRED` | `--request` missing or not an object |
+| `REQUEST_TASK_ID_NOT_ALLOWED` | `request.taskId` or `request.task_id` supplied; use `--task-id` |
 | `REQUEST_FIELDS_REQUIRED` | required body fields absent/blank |
 | `CAPABILITY_EXECUTION_FAILED` | unmapped domain failure; check `invocation_id` / Hermes logs |

package/skills/ae-metadata/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-metadata
-version: 1.0.0
+version: 1.0.1
 description: "AE/TE metadata capability-gateway CLI: metadata data-table management and property dimension-table binding. Metadata CLI routes through the analysis gateway. Input-file upload and event/property detail belong to ae-analysis."
 ---
 
@@ -30,6 +30,7 @@ Safety:
 - Ordinary writes (`data-table *-write`, `property-bindings-update`, dimension-table bind/create) execute without `--yes`. Delete commands are `high-risk-write`: dry-run first, summarize impact, wait for explicit confirmation, then execute with `--yes`.
 - **Before any command**, read the matching `references/<name>.md` (filename = command with spaces → underscores, e.g. `metadata data-table list` → `metadata_data_table_list.md`).
 - Never invent `project_id`, event/property names, `input_file_id`, or `data_table_id`. Discover names via `ae-analysis` and data table IDs via `metadata data-table list`.
+- `metadata data-table download` is an async artifact command: plain invocation submits, `--wait` waits, and `--output <file>` waits then streams atomically. Resume with `analysis run wait`; local interruption never cancels the remote run.
 
 ## When to Use
 

package/skills/ae-metadata/references/metadata_data_table_download.md

@@ -5,6 +5,7 @@
 ```bash
 ae-cli metadata data-table download --project-id <project_id> --data-table-id <id>
 ae-cli metadata data-table download --project-id <project_id> --data-table-id <id> --request-id cli_0123456789abcdef0123456789abcdef --timeout-seconds 120
+ae-cli metadata data-table download --project-id <project_id> --data-table-id <id> --output <file>
 ```
 
 | Parameter | Required | Description |
@@ -12,6 +13,13 @@ ae-cli metadata data-table download --project-id <project_id> --data-table-id <i
 | `--project-id` / `-p` | Yes | Numeric project ID. |
 | `--data-table-id` | Yes | Data table ID. |
 | `--request-id` | No | Optional `cli_<32 lowercase hex>` request ID. |
-| `--timeout-seconds` | No | Timeout in seconds, 1 to 7200. |
+| `--timeout-seconds` | No | Remote runtime in seconds, 1 to 21600. |
+| `--wait` | No | Wait for run `SUCCEEDED` and artifact `COMPLETED`. |
+| `--output` | No | Wait, then stream and atomically publish the artifact to this file. |
+| `--force` | No | Replace an existing `--output` file atomically; invalid without `--output`. |
 
-Use this command when the user needs an exported data-table artifact.
+Use this command when the user needs an exported data-table artifact. Plain
+invocation submits only. `--output` implies `--wait`; resume an interrupted
+wait with `ae-cli analysis run wait --run-id <run_id> [--output <file>]`.
+Local interruption never cancels the remote run. Do not use this command for
+inline data-table metadata; use `metadata data-table get` instead.

package/skills/ae-metadata/references/metadata_data_table_list.md

@@ -5,7 +5,7 @@
 ## Command
 
 ```bash
-ae-cli metadata data-table list --project-id <project_id>
+ae-cli metadata data-table list --project-id <project_id> --limit 50 --offset 0
 ae-cli metadata data-table list --project-id <project_id> --dry-run
 ```
 
@@ -14,14 +14,17 @@ ae-cli metadata data-table list --project-id <project_id> --dry-run
 | Parameter | Required | Description |
 |---|---|---|
 | `--project-id` / `-p` | Yes | Numeric project ID. |
+| `--limit` / `-l` | No | Page size. Default: 50, maximum: 200. |
+| `--offset` / `-o` | No | Zero-based page offset. Default: 0. |
 
 ## Request Body
 
 ```json
-{ "project_id": 1 }
+{ "project_id": 1, "limit": 50, "offset": 0 }
 ```
 
 ## Decision Rules
 
 - Use this command to discover `data_table_id` before get, delete, download, or property binding.
 - If the list is empty, do not invent IDs; create/upload a table first or ask for the target table.
+- Read rows from `data.items`; pagination metadata is always `total`, `limit`, `offset`, `has_more`, and `next_offset`.

package/skills/ae-system/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-system
-version: 1.0.0
-description: "AE Agent system administration CLI for root and agent administrators. Use when the user asks to manage Agent members, sandboxes, company model visibility/defaults, usage statistics, cost quotas, balance alerts, or IM channels. Must use ae-cli system commands, discover real IDs before writes, and never attempt to bypass a permission denial."
+version: 1.1.0
+description: "AE Agent system administration CLI for root and agent administrators. Use when the user asks to manage Agent members, sandboxes and shared tools, company model visibility/defaults/pricing, usage statistics and exports, cost quotas, balance alerts, or IM channels. Must use ae-cli system commands, discover real IDs before writes, and never attempt to bypass a permission denial."
 ---
 
 # ae-system
@@ -19,11 +19,13 @@ ae-cli system +<command> [options]
 - Run `ae-cli auth login --host <host>` before using this domain. System administration requires a user access-token session; sandbox identity headers are not an authorization substitute.
 - `+npm-install` is the exception that must also run inside a Linux te-agent sandbox because it packages the installed Linux files. It still requires the logged-in user to be `root` or `agent_admin`.
 - Discover real IDs with a list command before any update or delete. Never guess a user, sandbox, model, quota rule, or channel ID.
-- Read and ordinary write commands run without confirmation. Commands marked `high-risk-write` require confirmation unless the user explicitly authorizes `--yes`.
+- Before every write, run `--dry-run`, show the target and effect, and obtain explicit user confirmation. The CLI itself prompts only for `high-risk-write`; `--yes` can bypass that prompt and is not a security boundary.
 - Use `--dry-run` to inspect method, path, query, and redacted body without executing.
 - JSON inputs accept inline JSON, `@file`, or `-` for stdin. Prefer `@file` for channel credentials and other sensitive values.
 - Successful output is JSON by default. Use `--format table` only when a human-readable table is more useful.
 - After each command, check stderr and `_notice.host_compat`. If present, show the version warning and its update commands before the business result.
+- Do not treat an absent ae-cli command as proof that an HTTP endpoint is unreachable. An Agent with Bash/network access can construct requests directly; server authentication, role checks, company isolation, and resource ownership are the actual controls.
+- Do not call `DELETE /api/admin/members?openId=...` or `/api/internal/sandboxes/**` through ad-hoc HTTP. They are intentionally excluded from this Skill because other systems own those integration contracts.
 
 ## Command Groups
 
@@ -37,6 +39,7 @@ ae-cli system +<command> [options]
 | `+set-member-status` | write | Enable or disable a member. |
 | `+set-member-role` | write | Change a non-root member between `agent_admin` and `member`. |
 | `+remove-member` | high-risk-write | Remove a non-root member. |
+| `+get-member-stats` | read | Get one member's token usage and recent conversation count. |
 
 Examples:
 
@@ -77,6 +80,7 @@ Optional flags are `--rule-id` and `--create-sandbox true|false`.
 | Command | Risk | Purpose |
 | --- | --- | --- |
 | `+list-sandboxes` | read | List company sandboxes. |
+| `+get-sandbox-config` | read | Read feature status and create/active seat limits. |
 | `+batch-create-sandboxes` | write | Create personal sandboxes for 1-100 users. |
 | `+update-sandbox` | write | Update a sandbox description. |
 | `+set-sandbox-enabled` | write | Enable or disable a sandbox. |
@@ -106,9 +110,33 @@ Use Agent database user IDs from `+list-members`, not TE openIds, for sandbox co
 | --- | --- | --- |
 | `+upload-sandbox-tool` | write | Validate, ZIP, and upload an existing tool directory. |
 | `+npm-install` | write | Install one exact npm CLI version in a temporary sandbox directory, generate `tool.json`, and upload it. |
+| `+list-sandbox-tools` | read | List preset and custom tools for the current company. |
+| `+sync-sandbox-tools` | write | Synchronize preset tools from the server manifest. |
+| `+get-sandbox-tool-distribution` | read | Read the sandboxes currently receiving one tool. |
+| `+set-sandbox-tool-enabled` | write | Enable or disable one registered tool. |
+| `+remove-sandbox-tool` | high-risk-write | Delete a fully reclaimed tool registration. |
+| `+activate-sandbox-tools` | write | Activate selected commands on selected or all running sandboxes. |
+| `+deactivate-sandbox-tools` | write | Remove managed command shims from selected or all running sandboxes. |
+| `+refresh-sandbox-tool-status` | write | Refresh observed tool state on target sandboxes. |
+| `+list-sandbox-tool-operations` | read | List activation/deactivation history. |
 
 Uploaded tools are registered for the current company with `enabled=false`. Upload does not activate the tool in any running sandbox. Review and enable/activate it through sandbox tool management after upload.
 
+For activate/deactivate/status operations:
+
+```bash
+ae-cli system +activate-sandbox-tools \
+  --target-mode selected \
+  --sandbox-ids '["<sandbox-id>"]' \
+  --tool-ids '["<tool-id>"]'
+```
+
+- `--target-mode selected` requires 1-50 `--sandbox-ids`; `all-running` forbids them.
+- `--tool-ids` contains 1-20 real IDs from `+list-sandbox-tools`.
+- `--command-names-by-tool-id` optionally limits an operation to named commands.
+- `--expected-tool-snapshots-by-id` carries the version/package/command snapshot returned by the server for optimistic concurrency checks.
+- JSON maps accept inline JSON, `@file`, or stdin. Use dry-run and user confirmation before distribution changes.
+
 #### Preferred npm Flow
 
 Run this inside the target Linux te-agent sandbox:
@@ -189,6 +217,9 @@ Upload contract:
 | --- | --- | --- |
 | `+list-system-models` | read | List system models and company visibility. |
 | `+set-system-model-enabled` | write | Toggle a system model for the current company. |
+| `+get-model-sync-settings` | read | Read the default visibility policy for newly synchronized system models. |
+| `+set-model-sync-settings` | write | Update the new-system-model visibility policy. |
+| `+get-system-model-price-rules` | read | Read one managed system model's stored pricing snapshot. |
 | `+list-company-models` | read | List company models, including disabled models. |
 | `+set-company-model-enabled` | write | Toggle a company model for all company users. |
 | `+get-default-models` | read | Read the `AE_AGENT` and `AI_QA` default slots. |
@@ -211,11 +242,16 @@ ae-cli system +set-default-model --model-id <model-id> --biz-type AE_AGENT
 | --- | --- | --- |
 | `+get-usage-summary` | read | Get token/cost summary for a relative or absolute range. |
 | `+get-usage-details` | read | Get paginated usage grouped by user, model, date, or application type. |
+| `+get-agent-tool-calls` | read | Get Agent tool-call count for a range, optionally refreshing the cache. |
+| `+get-usage-combinations` | read | Drill one parent group into the remaining dimensions. |
+| `+export-usage` | read | Stream filtered one-dimension usage groups to CSV. |
+| `+export-usage-details` | read | Stream full or drill-down multi-dimension details to CSV. |
 
 Examples:
 
 ```bash
 ae-cli system +get-usage-summary --days 30
+ae-cli system +get-usage-summary --days 30 --refresh true
 
 ae-cli system +get-usage-details \
   --start-date 2026-07-01 \
@@ -223,12 +259,26 @@ ae-cli system +get-usage-details \
   --group-by user \
   --page 1 \
   --page-size 20
+
+ae-cli system +get-usage-combinations \
+  --start-date 2026-07-01 \
+  --end-date 2026-07-24 \
+  --parent-dimension user \
+  --open-id <open-id>
+
+ae-cli system +export-usage \
+  --start-date 2026-07-01 \
+  --end-date 2026-07-24 \
+  --group-by user \
+  --output ./system-usage.csv
 ```
 
 Summary range:
 
 - Use `--days 1..365`, or provide both `--start-date` and `--end-date`.
 - Dates use `YYYY-MM-DD`.
+- Do not combine `--days` with an absolute date pair.
+- `--refresh true` is available on `+get-usage-summary` and `+get-agent-tool-calls` and bypasses the overview cache.
 
 Details flags:
 
@@ -239,11 +289,22 @@ Details flags:
 - `--sort-by`: `totalTokens | cost | share | requestCount`.
 - `--sort-dir`: `asc | desc`.
 
+Combination drill-down requires exactly one parent selector:
+
+- `user` → `--open-id` only.
+- `model` → `--model-id` and `--model-scope` only.
+- `app_type` → `--app-type` only.
+- `date` → `--date` only, inside the selected range.
+
+CSV exports require an explicit `--output`. The target is created exclusively: an existing file is never overwritten, and an HTTP or stream failure removes the incomplete file. The JSON result reports the absolute local path, bytes written, server filename, and content type.
+
 ### Cost Control
 
 | Command | Risk | Purpose |
 | --- | --- | --- |
 | `+get-cost-summary` | read | Get company cost, quota, and usage summary. |
+| `+get-balance` | read | Get the current model account balance and currency. |
+| `+list-over-limit-users` | read | List members over cost or token quota limits. |
 | `+get-balance-alert` | read | Get balance alert config and current status. |
 | `+set-balance-alert` | write | Enable, update, or disable the balance alert. |
 | `+list-quota-rules` | read | List cost/token quota rules. |
@@ -347,6 +408,8 @@ On this response:
 2. Do not recommend re-login unless the server returned 401 instead.
 3. Tell the user that `root` or `agent_admin` is required.
 
+An authenticated `root` or `agent_admin` is still scoped to their own company. The current service checks the database role and company against the session, and audited member, channel, sandbox-tool, and sandbox-management routes apply company/resource ownership checks. Never use that statement as a claim that every unreviewed admin route is safe.
+
 ## Transport Status
 
 This is a Transitional L2 domain backed by te-agent `/api/admin/**`.