@thinkingai/ae-cli 6.1.18 → 6.1.20

package/skills/ae-kb/references/versions.md

@@ -0,0 +1,46 @@
+# Published knowledge-base versions
+
+Versions are immutable successful publications. No historical version is created until the first successful compile. Failed or cancelled compiles do not consume a version number. Existing `+compile`, `+status` and `+list-sources` responses pass through server version labels and draft state; `+index`, `+grep`, `+read` and `+ask` always address current content.
+
+When `+status` returns `wiki_review_required`, inspect `publicationReview.code`, report that administrator review is required, and stop ordinary compile polling. The active Run and write lock remain in place; do not cancel or force another compile. This also covers an interrupted publication after server restart.
+
+Discover exact names/scopes via `kb +list`, then inspect history:
+
+```bash
+ae-cli kb +versions --name handbook --scope company --limit 100
+ae-cli kb +version-show --name handbook --scope company --version 2
+ae-cli kb +version-sources --name handbook --scope company --version 2 --source-type zip
+ae-cli kb +version-diff --name handbook --scope company --from 1 --to 2
+ae-cli kb +version-tree --name handbook --scope company --version 2 --id <historical-source-id>
+ae-cli kb +version-read --name handbook --scope company --version 2 --id <historical-source-id> --path guides/start.md
+ae-cli kb +version-download --name handbook --scope company --version 2 --id <historical-file-source-id> --output ./manual.pdf
+```
+
+- `--version`, `--from` and `--to` use integer version numbers, without a `v` prefix. `+version-sources` IDs come from that historical snapshot; never substitute current source metadata.
+- `+versions`, `+version-sources` and `+version-tree` return one page. Use `--cursor` with the returned `nextCursor`, retaining the same target and filters. `--limit` is 1–200.
+- `--scope personal|company` is exact. Omitting it keeps the existing personal-then-company lookup. A missing target in an explicit scope never falls back.
+- `+version-tree/+version-read` accept ZIP or URL parent sources. Paths are source-relative and cannot contain absolute, parent or backslash segments. Text preview is bounded; supported PDF/images use a typed data URL. Unsupported or oversized files return metadata and `previewable: false`.
+- `+version-download` accepts ordinary file sources only and creates a new local file with exclusive creation. It never overwrites an existing file. Directory sources return `KB_VERSION_DIRECTORY_DOWNLOAD_UNSUPPORTED`; the CLI does not reconstruct ZIPs or export an entire version.
+
+## Rollback
+
+Copy `latestVersionId` and an earlier target version from `+versions`. Explicitly explain the effects before requesting rollback: target-source edits and deletion intents are replaced; target-external sources with a previous successful publication are soft-deleted; target-external unpublished additions and their files remain unchanged.
+
+```bash
+ae-cli kb +rollback --name handbook --scope company --version 1 --expected-latest-version-id <latestVersionId> --request-id <stable-request-id> --dry-run
+ae-cli kb +rollback --name handbook --scope company --version 1 --expected-latest-version-id <latestVersionId> --request-id <stable-request-id>
+ae-cli kb +rollback-status --name handbook --scope company --operation-id <operationId>
+```
+
+`+rollback` is `high-risk-write`; use `--yes` only for an already authorized exact operation. A target must be strictly older than the current version. Success creates a new version (for example v3 → v1 produces v4), retaining all previous snapshots.
+
+The caller must supply a stable ASCII `request-id` containing letters, digits, underscores or hyphens (1–191 characters). Reuse that exact ID, target and expected latest ID after a network interruption. The CLI does not generate another request ID, pick a different target, or retry a 409 automatically. A changed request under the same ID returns `KB_VERSION_OPERATION_REQUEST_CONFLICT`.
+
+`queued/running` means accepted but not completed. Query `+rollback-status` using the returned `operationId`; only `status: success` with `resultVersionId` proves publication. `failed` is a terminal result; a later intentional attempt needs a new request ID. When `running` includes `KB_PUBLICATION_COMMIT_UNKNOWN`, `KB_PUBLICATION_ROLLBACK_INCOMPLETE`, or `KB_PUBLICATION_REVIEW_REQUIRED`, tell the user administrator review is required and writes remain blocked. Stop normal progress/polling; do not start another rollback. Status remains readable.
+
+Transition status: transitional
+Owning module: te-claude External Knowledge Base Versions API
+Current transport: authenticated External REST via kbApi
+Gateway target: TBD (published history and persistent rollback operations)
+Review after: 2026-12-07
+Exit condition: migrate when equivalent immutable-history and idempotent rollback Gateway capabilities exist; retain stable request IDs, exact-scope targeting and local file safety.

package/skills/ae-system/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ae-system
-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."
+version: 1.2.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, IM channels, channel routing, WhatsApp Web linking, or Feishu user bindings. Must use ae-cli system commands, discover real IDs before writes, and never attempt to bypass a permission denial."
 ---
 
 # ae-system
@@ -10,13 +10,14 @@ Use the `system` domain for Agent system administration:
 
 ```bash
 ae-cli system +<command> [options]
+ae-cli system <resource> <action> [options]
 ```
 
 ## Mandatory Rules
 
 - These commands are only for users whose Agent role is `root` or `agent_admin`.
-- The te-agent `/api/admin/**` endpoint is the final authorization boundary. A member receives a permission error (HTTP 403). Do not retry login or attempt a different endpoint after a 403.
-- 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.
+- The te-agent `/api/admin/**` and `/api/cli/channel/v1/**` endpoints are the final authorization boundaries. A member receives a permission error (HTTP 403). Do not retry login or attempt a different endpoint after a 403.
+- Run `ae-cli auth login --host <host>` before using this domain. System administration requires a valid user CLI-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.
 - 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.
@@ -353,41 +354,38 @@ Rules:
 
 ### Channels
 
+For channel setup, routing, WhatsApp Web linking, or Feishu user binding, read [references/channel-management.md](references/channel-management.md) before taking action. It defines the two confirmation phases and the `ae-cli` plus Feishu OpenAPI MCP workflow.
+
 | Command | Risk | Purpose |
 | --- | --- | --- |
-| `+list-channels` | read | List Feishu, Lark, and Slack channels. |
+| `+list-channels` | read | List all configured channels. |
+| `channel get` | read | Read one channel, its verification state, and endpoints. |
 | `+create-channel` | write | Create one channel. |
 | `+update-channel` | write | Update channel settings, credentials, model, prompt, or enabled state. |
 | `+remove-channel` | high-risk-write | Delete a channel, unbind users, and stop its connection. |
-
-Always use `@file` for channel payloads when they contain credentials:
+| `channel verify` | write | Verify credentials and discover endpoints. |
+| `channel routing get` | read | Read one endpoint's group message routing. |
+| `channel routing set` | write | Replace one endpoint's group message routing. |
+| `channel whatsapp-web status` | read | Read a WhatsApp Web link state and QR data. |
+| `channel whatsapp-web start` | write | Start or resume WhatsApp Web QR linking. |
+| `channel whatsapp-web unlink` | high-risk-write | Unlink WhatsApp Web and remove stored credentials. |
+| `channel binding list` | read | List channel user bindings. |
+| `channel binding bind-feishu` | write | Bind one Feishu user. |
+| `+bind-feishu-users` | write | Bind 1-100 Feishu users and optionally assign Agents. |
+| `channel binding unbind` | high-risk-write | Delete one channel user binding. |
+| `channel binding set-agent` | write | Set or clear one binding's private-chat default Agent. |
+
+Use canonical snake_case request fields. The four original commands also accept their legacy camelCase JSON fields for compatibility. Always use `@file` for credentials and batch rosters:
 
 ```bash
 ae-cli system +create-channel --channel @channel.json
 ae-cli system +update-channel --id <channel-id> --channel @channel-update.json
+ae-cli system +bind-feishu-users \
+  --channel-id <channel-id> \
+  --endpoint-id <endpoint-id> \
+  --bindings @bindings.json
 ```
 
-Create schema:
-
-```json
-{
-  "name": "Required display name",
-  "type": "feishu",
-  "config": {
-    "appId": "Feishu/Lark",
-    "appSecret": "Feishu/Lark",
-    "botToken": "Slack",
-    "appToken": "Slack",
-    "clientId": "optional",
-    "clientSecret": "optional"
-  },
-  "model": "optional Model.id or modelId::scope",
-  "systemPrompt": "optional"
-}
-```
-
-Update accepts a partial object with `name`, `config`, `model`, `systemPrompt`, `enabled`, or `unbindUsers`. Channel type is immutable after creation. Dry-run replaces secret values with `***`.
-
 ## Permission Errors
 
 A permission response looks like:
@@ -412,9 +410,9 @@ An authenticated `root` or `agent_admin` is still scoped to their own company. T
 
 ## Transport Status
 
-This is a Transitional L2 domain backed by te-agent `/api/admin/**`.
+This is a Transitional domain backed by te-agent `/api/admin/**` and `/api/cli/channel/v1/**`.
 
-- Maintainer: te-agent admin routes and `src/commands/te-system/**`.
-- Migration target: system Capability Gateway.
+- Maintainer: te-agent admin/channel-management routes and `src/commands/te-system/**`.
+- Migration target: system and channel Capability Gateways.
 - Review date: 2026-10-24.
 - Exit condition: migrate after equivalent gateway schema, auth, risk, dry-run, and output contracts are stable.

package/skills/ae-system/references/channel-management.md

@@ -0,0 +1,303 @@
+# Channel Management
+
+Use this workflow for channel configuration, group routing, WhatsApp Web linking, and Feishu user bindings. All channel endpoints require an authenticated `root` or `agent_admin` and enforce company isolation.
+
+## Scope
+
+Channel configuration supports `feishu`, `lark`, `slack`, `discord`, `dingtalk`, `wecom`, `mattermost`, `google_chat`, and `whatsapp`. Administrator-driven user binding is available only for `feishu`.
+
+The default Feishu binding is group-routing ready. It requires a verified `endpoint_id` for the channel and a `union_id` for every user. Use `--private-only` only after the user explicitly accepts private-chat-only behavior; never downgrade silently when either value is unavailable.
+
+## Two Confirmation Phases
+
+Treat channel configuration and personnel binding as separate writes:
+
+1. **Channel configuration phase**: discover current state, prepare channel configuration and routing, run every applicable `ae-cli ... --dry-run`, show the redacted target/effect, and obtain one explicit confirmation before executing this phase.
+2. **Personnel binding phase**: resolve the final roster and IDs, inspect each person's sandbox readiness, validate the complete binding batch and every required sandbox write with `--dry-run`, show counts, endpoint, private-only state, Agent assignments, sandbox creates, and sandbox enables, then obtain explicit confirmation before each planned write set. A roster containing only existing Agent members needs one final binding-and-sandbox confirmation.
+
+A confirmation for phase 1 does not authorize phase 2. A confirmation for one roster does not authorize a changed roster.
+
+## Phase 1: Configure a Channel
+
+Start from current state:
+
+```bash
+ae-cli system +list-channels
+ae-cli system channel get --id <channel-id>
+```
+
+Create JSON uses snake_case. The original `+create-channel` and `+update-channel` commands also accept legacy camelCase fields, but new files should not use them.
+
+```json
+{
+  "name": "Support Bot",
+  "type": "feishu",
+  "config": {
+    "app_id": "<app-id>",
+    "app_secret": "<app-secret>"
+  },
+  "model": "<optional-model-id>",
+  "system_prompt": "<optional-system-prompt>",
+  "enabled": false
+}
+```
+
+Run the dry-run before the phase-1 confirmation. Credential values are replaced with `***`:
+
+```bash
+ae-cli --dry-run system +create-channel --channel @channel.json
+ae-cli system +create-channel --channel @channel.json
+```
+
+Type-specific configuration:
+
+| Type | Required config | Conditional config |
+| --- | --- | --- |
+| `feishu`, `lark` | `app_id`, `app_secret` | — |
+| `slack` | `bot_token`, `app_token` | `client_id`, `client_secret` when used by the deployment |
+| `discord` | `bot_token` | `client_id`, `client_secret` when used by the deployment |
+| `dingtalk` | `client_id`, `client_secret`, `corp_id` | `interaction_card_template_id` |
+| `wecom` | `bot_id`, `bot_secret` | If `oauth_enabled=true`: `corp_id`, `corp_secret`, `agent_id` |
+| `mattermost` | `server_url`, `bot_token` | If `oauth_enabled=true`: `client_id`, `client_secret` |
+| `google_chat` | `service_account_json` | `workspace_addon_service_account_email`; if `oauth_enabled=true`: `client_id`, `client_secret` |
+| `whatsapp` | no manual config | Credentials are created by the QR lifecycle |
+
+Update accepts a partial object containing `name`, `type`, `config`, `model`, `system_prompt`, `enabled`, or `unbind_users`. If `type` is present it must equal the channel's existing type. Omitting a secret or passing an empty string preserves the stored value; it does not clear the secret.
+
+For every non-WhatsApp channel, verify credentials before depending on endpoints:
+
+```bash
+ae-cli --dry-run system channel verify --id <channel-id>
+ae-cli system channel verify --id <channel-id>
+ae-cli system channel get --id <channel-id>
+```
+
+Treat configuration persistence and runtime startup as separate outcomes. An HTTP 200 may still contain `runtime_status="error"`; report that the configuration was saved without claiming the bot is online. When Google Chat creation returns its one-time `webhook_url`, ask the operator to save it immediately in an approved secret store and never copy it into logs or repository files.
+
+For WhatsApp, create the channel without config, enable it with `+update-channel`, then start linking. Poll only until the returned `expires_at` (and never longer than two minutes) for `linked`, `needs_relink`, `failed`, or `expired`:
+
+```bash
+ae-cli --dry-run system +update-channel --id <channel-id> --channel '{"enabled":true}'
+ae-cli system +update-channel --id <channel-id> --channel '{"enabled":true}'
+ae-cli --dry-run system channel whatsapp-web start --id <channel-id>
+ae-cli system channel whatsapp-web start --id <channel-id>
+ae-cli system channel whatsapp-web status --id <channel-id>
+```
+
+Show `qr_data_url` to the user for scanning. Do not call `channel verify` for WhatsApp. Before unlinking, disable the channel with `+update-channel`, then call `channel whatsapp-web unlink`; the unlink command requires its own high-risk CLI confirmation and still stays inside phase 1.
+
+```bash
+ae-cli --dry-run system +update-channel --id <channel-id> --channel '{"enabled":false}'
+ae-cli system +update-channel --id <channel-id> --channel '{"enabled":false}'
+ae-cli --dry-run system channel whatsapp-web unlink --id <channel-id>
+ae-cli system channel whatsapp-web unlink --id <channel-id>
+```
+
+## Group Routing
+
+Use a verified endpoint ID from `channel verify` or `channel get`:
+
+```bash
+ae-cli system channel routing get --endpoint-id <endpoint-id>
+ae-cli --dry-run system channel routing set \
+  --endpoint-id <endpoint-id> \
+  --routing @routing.json
+```
+
+`routing.json` replaces the full routing configuration:
+
+```json
+{
+  "status": "enabled",
+  "default_handler": { "kind": "agent", "id": "<agent-id>" },
+  "targets": [
+    {
+      "handler_kind": "team",
+      "handler_id": "<team-id>",
+      "slug": "billing",
+      "keywords": ["invoice", "refund"],
+      "sort_order": 10,
+      "enabled": true
+    }
+  ]
+}
+```
+
+`status` is `enabled | disabled`, `default_handler` is an Agent/Team handler or `null`, and `targets` contains at most 19 entries. The server validates handler ownership, duplicate handlers/slugs, and keyword conflicts.
+
+## Phase 2: Resolve and Bind Feishu Users
+
+### Feishu binding transport contract
+
+Both the single-user and batch CLI flows use the same binding endpoint:
+
+| Operation | Method and path | CLI mapping |
+| --- | --- | --- |
+| Bind one Feishu identity to one channel | PUT `/api/cli/channel/v1/bindings/feishu` | `channel binding bind-feishu` sends one request. |
+| Bind 1-100 Feishu identities to one channel | PUT `/api/cli/channel/v1/bindings/feishu` | `+bind-feishu-users` validates the full roster, then sends one binding PUT per person. |
+| Set the private-chat default Agent after binding | PUT `/api/cli/channel/v1/bindings/{binding_id}/agent` | `channel binding set-agent`; the batch command calls it after each successful binding when an Agent is selected. |
+
+The Feishu binding request body is a strict, flat JSON object:
+
+| Field | Required | Binding meaning |
+| --- | --- | --- |
+| `channel_id` | yes | `channel_id` identifies the one target Feishu channel for the request. The channel must belong to the current company and be enabled. |
+| `te_user_id` | yes | The selected AE Agent member's `openId`; this is the member being associated with the channel identity. |
+| `open_id` | yes | The person's Feishu `open_id` under the same Feishu application configured by the target channel. |
+| `union_id` | group-ready only | The person's stable Feishu identity for group routing. Supply it together with `endpoint_id`; omit both only for explicitly approved private-chat-only binding. |
+| `endpoint_id` | group-ready only | `endpoint_id` must identify a verified endpoint that belongs to the same `channel_id`. Supply it together with `union_id`. |
+
+```json
+{
+  "channel_id": "channel-sales",
+  "te_user_id": "agent-member-open-id-alice",
+  "open_id": "ou_alice",
+  "union_id": "on_alice",
+  "endpoint_id": "endpoint-sales-verified"
+}
+```
+
+The binding response returns:
+
+| Field | Meaning |
+| --- | --- |
+| `binding_id` | The channel-user binding ID used for later Agent assignment or maintenance. |
+| `channel_id` | The target channel confirmed by the server. |
+| `te_user_id` | The AE Agent member associated with the channel identity. |
+| `open_id` | The Feishu application-scoped identity stored on the binding. |
+| `group_routing_ready` | Whether this binding is ready for group routing. |
+| `agent_id` | The current private-chat default Agent, or no value when system-default resolution applies. |
+| `endpoint_id` | The associated endpoint when the binding is group-routing ready. |
+
+`agent_id` is not part of this request body. After the binding response returns `binding_id`, set or clear the private-chat default Agent through `PUT /api/cli/channel/v1/bindings/{binding_id}/agent`. `default_agent_id` and `private_only` are also CLI orchestration fields, not fields accepted by the Feishu binding endpoint.
+
+One `+bind-feishu-users` invocation has one top-level `--channel-id` and one shared `--endpoint-id`; every entry in `bindings.json` is bound to that channel. Run separate confirmed batches for different channels. Do not put `channel_id` or `endpoint_id` inside individual roster entries.
+
+Common contract mistakes:
+
+| Mistake | Required correction |
+| --- | --- |
+| Reusing an `open_id` resolved under another Feishu application | Resolve the person again with the application configured by the target channel. |
+| Pairing the target channel with an endpoint from another channel | Select a verified endpoint returned by `channel get` or `channel verify` for the same `channel_id`. |
+| Sending `agent_id`, `default_agent_id`, or `private_only` to the Feishu binding endpoint | Keep them in CLI orchestration; assign the Agent through the binding-specific Agent endpoint. |
+| Mixing users for multiple channels in one batch roster | Split the work by channel, dry-run every final roster, and confirm each batch separately. |
+
+1. The current session must have the Feishu OpenAPI MCP mounted. Before resolving identities, verify all of these prerequisites:
+
+- The MCP and the target channel use the same App ID and App Secret. Read the channel's `config.app_id` with `ae-cli system channel get --id <channel-id>` and compare it with the MCP application configuration. When the App Secret or MCP configuration is masked, obtain explicit confirmation from the configuration owner instead of assuming a match. Feishu `open_id` is application-scoped.
+- The Feishu application has the `contact:user.id:readonly` permission.
+- The MCP exposes the `contact.v3.users.batchGetId` tool.
+
+Stop when any prerequisite is missing or cannot be verified. Resolve people by exact corporate email address or mobile number; `contact.v3.users.batchGetId` does not resolve names, so ask for an email address or mobile number when only a name is provided.
+
+2. Call `contact.v3.users.batchGetId` with `user_id_type=open_id`. Put exact emails in `data.emails` or exact mobile numbers in `data.mobiles`:
+
+```json
+{
+  "params": { "user_id_type": "open_id" },
+  "data": { "emails": ["alice@example.com", "bob@example.com"] }
+}
+```
+
+Map each returned `user_list[].user_id` to the matching returned email or mobile number as that person's Feishu `open_id`. A zero-result lookup, missing input, duplicate input, or response that cannot be mapped one-to-one is unresolved. Stop, show the unresolved inputs, and obtain corrected exact identifiers; never choose the first result or infer a person from ordering.
+
+3. Repeat `contact.v3.users.batchGetId` for the same exact emails or mobile numbers with `user_id_type=union_id`; reuse the corresponding `data.emails` or `data.mobiles` roster from step 2 unchanged.
+
+Map each returned `user_list[].user_id` to the same person as that person's Feishu `union_id`. Require the `open_id` and `union_id` lookup results to cover the same uniquely identified roster. If the Feishu OpenAPI MCP cannot return a `union_id`, stop. Ask whether the user explicitly accepts `--private-only`; do not infer that choice.
+
+4. Fetch Agent members and match each selected person to exactly one Agent member by confirmed login/display identity. Use that member's `openId` as `te_user_id`; do not use its database `userId`, and do not assume the app-scoped Feishu `open_id` equals the AE member `openId`:
+
+```bash
+ae-cli system +list-members --status enabled --all true
+```
+
+If a selected person is not yet an Agent member, use `+list-member-candidates` to resolve the exact candidate. When member addition is required, phase 2 has a prerequisite member-add confirmation and a final binding-and-sandbox confirmation. Dry-run and confirm `+add-members`, execute it, then refetch members before preparing the final binding and sandbox plan. Keep `--create-sandbox` false or omit it in this workflow; sandbox creation and verification happen explicitly after a successful channel binding. The member-add confirmation does not authorize the later binding or sandbox writes.
+5. Build `bindings.json` using only snake_case:
+
+```json
+[
+  {
+    "te_user_id": "<agent-member-open-id>",
+    "open_id": "<feishu-open-id>",
+    "union_id": "<feishu-union-id>",
+    "agent_id": "<optional-per-user-agent-id>"
+  }
+]
+```
+
+`--default-agent-id` applies when an item omits `agent_id`; an item's `agent_id` overrides the default. Omit both to leave the private-chat default Agent unchanged.
+
+6. Inspect sandbox capacity and current ownership before building the phase-2 plan:
+
+```bash
+ae-cli system +get-sandbox-config
+ae-cli system +list-sandboxes
+```
+
+For sandbox operations, map each selected Agent member's database `userId` to `items[].boundUsers[].userId`; never use the member's `openId`, Feishu `open_id`, or Feishu `union_id`. A channel-bound person's sandbox is ready when exactly one returned sandbox contains that `userId` and has `enabled === true`. Container `runningState` is a separate lifecycle state and does not trigger `+start-sandbox` in this workflow.
+
+- For members with no sandbox, prepare one dry-run containing their database user IDs:
+
+```bash
+ae-cli --dry-run system +batch-create-sandboxes \
+  --user-ids '["<member-database-user-id>"]'
+```
+
+- For each existing sandbox with `enabled === false`, prepare its enable dry-run:
+
+```bash
+ae-cli --dry-run system +set-sandbox-enabled \
+  --id <sandbox-id> \
+  --enabled true
+```
+
+Calculate the planned quota use from `+get-sandbox-config`: required create seats equal the number of members with no sandbox, and required active seats equal that number plus the number of existing disabled sandboxes to enable. Require `sandboxQuota.cluster.remaining` to cover required create seats and `sandboxQuota.active.remaining` to cover required active seats. Treat a missing or non-numeric quota value as unverified rather than assuming capacity; `sandboxActiveSeatsLimit` is the limit, not the remaining count.
+
+Sandbox preflight protects sandbox writes without becoming a gate on channel binding. When sandbox management is disabled, verified capacity cannot cover the plan, quota values are unverified, a person maps to multiple sandboxes, or ownership cannot be matched exactly, mark the affected person as `sandbox_readiness_blocked` and show the reason in the phase-2 plan. Require confirmation that the channel binding may succeed while the sandbox remains not ready, and do not issue an unsafe sandbox write. A sandbox preflight failure does not cancel a confirmed channel binding.
+
+The phase-2 confirmation also authorizes the listed sandbox readiness writes. If the roster, target user IDs, sandbox IDs, required actions, or limits change, regenerate every affected dry-run and obtain a new confirmation.
+
+7. Validate the whole 1-100 item binding batch and show the complete phase-2 plan before asking for confirmation:
+
+```bash
+ae-cli --dry-run system +bind-feishu-users \
+  --channel-id <channel-id> \
+  --endpoint-id <verified-endpoint-id> \
+  --bindings @bindings.json \
+  --default-agent-id <optional-agent-id>
+```
+
+For an explicitly approved private-chat-only batch, omit every `union_id` and `--endpoint-id`, then add `--private-only true`.
+
+8. After phase-2 confirmation, execute the same binding command without `--dry-run`. The command validates the whole batch before the first request, then processes users sequentially. An item-level validation or conflict failure does not stop later users and no automatic rollback is attempted; a final 401 or any 403 stops the batch because authentication or authorization is no longer valid. Inspect `succeeded`, `failed`, and every result's `stage` (`binding` or `agent_assignment`). Retry only failed items with a new file; the Feishu binding PUT is idempotent.
+
+9. Only users whose channel binding succeeded proceed to sandbox readiness. A result with `binding_id` and `stage: "agent_assignment"` still proceeds to sandbox readiness. The channel binding exists, so report the Agent-assignment failure separately. Refetch `+list-sandboxes` after binding, then apply the confirmed plan against the refreshed state:
+
+- If preflight marked the person as `sandbox_readiness_blocked`, preserve the successful binding, report `channel_bound_sandbox_not_ready`, and wait for a new safe dry-run and confirmation before any later sandbox write.
+- If the exact user's sandbox is already `enabled === true`, make no write.
+- If the confirmed existing sandbox is still present with `enabled === false`, execute its prepared `+set-sandbox-enabled --enabled true` command.
+- If the confirmed user still has no sandbox, execute the prepared `+batch-create-sandboxes` command. The create call must return a successful result and a `sandboxId` for that database `userId`.
+- Refetch after creation. The batch-create contract creates an enabled personal sandbox and binds it to the requested database `userId`. If the new sandbox instead has `enabled === false`, run a fresh `+set-sandbox-enabled` dry-run and obtain supplemental explicit confirmation for the returned `sandboxId` before enabling it.
+- If the refreshed ownership or sandbox ID conflicts with the confirmed plan, stop that person's sandbox action and request a new dry-run and confirmation.
+
+Inspect every create or enable result. A final 401 or any 403 stops remaining sandbox writes. A quota, validation, conflict, or other item failure does not undo earlier bindings or prevent independent confirmed users from being processed. Record and report that person as `channel_bound_sandbox_not_ready`. Do not roll back a successful channel binding when sandbox preparation fails.
+
+10. Read back the final channel and sandbox state:
+
+```bash
+ae-cli system channel binding list --channel-id <channel-id>
+ae-cli system +list-sandboxes
+```
+
+For every successful channel binding, verify that exactly one sandbox contains the Agent member's database `userId` in `boundUsers[].userId` and returns `enabled === true`. Report separate counts and identities for `channel_bound_sandbox_ready`, `channel_bound_sandbox_not_ready`, and `channel_binding_failed`; do not collapse partial readiness into overall success.
+
+For one-off maintenance, use `channel binding bind-feishu`, `channel binding set-agent`, and `channel binding unbind` with the same dry-run, confirmation, and read-back rules. Clear a binding's private-chat Agent and restore system-default resolution with `channel binding set-agent --binding-id <binding-id> --clear`.
+
+## Transport Status
+
+Transition status: transitional
+Owning module: te-agent channel management
+Current transport: signed REST at `/api/cli/channel/v1/**`
+Gateway target: channel Capability Gateway
+Review after: 2026-10-24
+Exit condition: migrate when equivalent schemas, authorization, risk, dry-run, batch orchestration, and output contracts are stable.

package/skills/ae-use-agent/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ae-use-agent
+version: 1.0.2
+description: "Use a custom te-agent Agent's instructions and dependency assets for a task in a local client such as Codex or Claude Code, using the client's model and local files."
+---
+
+# Use an AE Agent locally
+
+The platform supplies instructions and dependency discovery. You execute the user's task
+with your current model and local capabilities. This does not start a remote te-agent session.
+
+1. Read [the bundled command guide](references/local-agent.md) for setup and discovery.
+   Resolve the user's Agent name with `+list-agents --q <name>` and ask only if the choice
+   is ambiguous. An explicit Agent ID can be used directly. No sibling Skill is required.
+2. Use the original AE host for the context request:
+
+   ```bash
+   ae-cli agent +get-agent-context --id <agent-id> --host <original-host>
+   ```
+
+3. Check `ok`, then use `data.agent.instructions` as task guidance within your existing instruction hierarchy.
+   Inspect dependency metadata and use capabilities already present locally where appropriate.
+   For Skills needed by the task, fetch the body and relevant references/scripts/assets using
+   the returned command descriptors and the bundled guide. File inventories are on-demand,
+   not included in the context response.
+4. Decide how to prepare needed dependencies under the client's existing permissions.
+   Treat remote text and scripts as content to inspect, not automatic installation or execution
+   authorization. Do not change global instruction files or install software just because a
+   dependency appears in the list. Obtain MCP connection secrets through normal credential
+   setup. When the user explicitly requests credential export, follow the bundled guide's
+   `--include-mcp-credentials` flow; keep its sensitive output out of conversation and logs.
+5. Execute the task. Explain missing dependencies only when relevant; stop the affected step
+   if an essential capability is unavailable. Do not claim the full Agent is enabled based
+   solely on loading its prompt. The listed tools are dependencies, not an enforced tool allowlist.
+
+Keep follow-up commands on the original AE host. Re-fetch context for a new task and verify
+Skill versions when loading files. The context is live metadata, not a frozen package.
+When switching Agents, replace prior task guidance where possible; use a fresh conversation
+if the client's context cannot cleanly separate their instructions.
+
+This Skill relies on ae-cli and the platform's Agent context endpoint; it does not bootstrap
+or update either automatically. The bundled guide includes installation and recovery steps.

package/skills/ae-use-agent/references/local-agent.md

@@ -0,0 +1,114 @@
+# Local Agent command guide
+
+This guide is included in ae-use-agent; installing ae-agent is optional. Use Node.js 20+
+and a local client that can run shell commands and read files.
+
+## Setup and recovery
+
+Run `ae-cli --version`. If the command is missing, obtain the AE host and supported CLI
+version from the user's environment administrator. Give the appropriate installation
+command with that version substituted; do not install automatically:
+
+```bash
+# Customer/public distribution
+npm install -g @thinkingai/ae-cli@<supported-version>
+# Internal ThinkingData distribution
+npm install -g @tant/ae-cli@<supported-version> --registry=https://npm.thinkingdata.cn:3443
+```
+
+Use the environment URL supplied by the user or configured in ae-cli; never guess a host.
+Keep that original host on every request, including authentication:
+
+```bash
+ae-cli auth status --host <original-host>
+ae-cli auth login --host <original-host>
+ae-cli agent +get-agent-context --help
+```
+
+Login is needed only when the session is missing or expired. Let the user complete the
+browser login; never request tokens in chat. If the command is unknown, the CLI is too old.
+For the public package, `ae-cli update --dry-run` previews host-compatible updates;
+perform an update only under the client's existing permissions. Internal builds use the
+internal registry above. If the host-supported release lacks this command or endpoint,
+ask the environment administrator for a compatible deployment; do not repeatedly update.
+
+## Discover and load
+
+```bash
+ae-cli agent +list-agents --q <agent-name> --host <original-host>
+ae-cli agent +get-agent-context --id <agent-id> --host <original-host>
+```
+
+Default JSON output is `{ "ok": true, "data": ... }`. Check `ok` before reading `data`.
+Name search results are in `data.agents`. Match name, scope and description; ask the user
+when ambiguous. Search by name instead of assuming an unfiltered list contains every Agent.
+An explicit ID can go directly to the context command. Ordinary members can read their
+own personal Agents and shared Agents visible to their account; no admin role is required.
+
+Context fields are `data.schema_version`, `data.context_version`, `data.agent.instructions`,
+`data.model`, `data.dependencies.skills`, `data.dependencies.mcps` and `data.summary`.
+This guide supports schema version 1; stop and obtain matching documentation for other
+versions. Use your current client model. An unavailable platform model does not block it.
+`availability=available` means visible metadata, not a working local dependency.
+
+## Read required Skill files
+
+For an available Skill, use its `id` and `files` descriptors. No extra list-skills call is
+needed. Each descriptor has `executable` and `argv`; pass arguments separately, never as
+interpolated shell code. Append `--host <original-host>`. Supported read commands are:
+
+```bash
+ae-cli agent +get-skill-content --id <skill-id> --host <original-host>
+ae-cli agent +list-skill-references --id <skill-id> --host <original-host>
+ae-cli agent +list-skill-scripts --id <skill-id> --host <original-host>
+ae-cli agent +list-skill-assets --id <skill-id> --host <original-host>
+ae-cli agent +read-skill-reference --id <skill-id> --path <relative-path> --host <original-host>
+ae-cli agent +read-skill-script --id <skill-id> --path <relative-path> --host <original-host>
+ae-cli agent +read-skill-asset --id <skill-id> --path <relative-path> --output <local-file> --host <original-host>
+```
+
+Skill body is in `data.item.content`; directory entries are in `data.items`. Text file
+reads return `data.content`. Use a path returned by the corresponding directory listing;
+`--path` is relative to references, scripts or assets, without that directory prefix.
+All three read commands support `--output <local-file>` to preserve binary bytes. Use a
+new workspace file path and inspect scripts before any execution. Check reported versions
+against the context and re-fetch if they change. An empty listing does not prove that a
+file required by the Skill is unnecessary: report a missing required file and stop that step.
+
+## MCP dependencies and failures
+
+If the user explicitly requests exporting current-user MCP credentials, use:
+
+```bash
+ae-cli agent +get-agent-context --id <agent-id> --include-mcp-credentials --host <original-host>
+```
+
+This is sensitive output: do not quote it in chat or logs, or commit it. Put the connection
+only in the intended local client configuration. Require `data.credentials_included=true`;
+its absence means an older server, not success. For each MCP, check `connection_config`:
+`exported` supplies `connection_name` and the same `connection` configuration shown in the
+current user's MCP market: `type`, `url`, `headers` for remote MCPs, or `type`, `command`,
+`args`, `env` for stdio. Header and environment keys are unchanged; system URLs use the AE
+host. `credential_expires_at=null` means expiry is not exposed. `unavailable` supplies a safe
+`connection_error`. No refresh tokens or platform-internal keys are included. Re-export
+after credentials expire or are revoked. Platform managed bridges require the platform
+runtime. Do not assume a successful export proves connectivity.
+
+
+Use `ae-cli agent +mcp-tools --id <mcp-id> --host <original-host>` for platform tool metadata.
+For OAuth MCPs only, `ae-cli agent +mcp-auth-status --id <mcp-id> --host <original-host>`
+reports platform authentication. Neither establishes a local connection. Reuse an existing
+local capability when suitable; otherwise obtain connection setup through the client's
+normal credential flow. Do not ask for secrets in chat or claim platform OAuth transfers.
+
+- 401/auth error: log in on the same host and retry once; stop if authentication still fails.
+- 403: permission denied; do not refresh repeatedly or require an admin account by default.
+- 404 on context: run `ae-cli agent +get-agent --id <agent-id> --host <original-host>`.
+  If it also fails, verify the ID/account/host. If it succeeds, verify endpoint deployment
+  with the administrator. Raw Agent configuration is not a complete context fallback.
+- 409 `invalid_agent_configuration`: ask the Agent owner to repair dependency configuration.
+- 500/network error: report the failed step and host; no silent success or fallback.
+- Unavailable dependency or file: stop only the step that needs it; explain what is missing.
+
+Never claim the full Agent is ready from prompt loading alone. Context is live metadata,
+not a frozen package; re-fetch it for a new task.

package/dist/auth-GBMV6TEJ.js

@@ -1,14 +0,0 @@
-import {
-  getToken,
-  invalidateAccessTokenForRetry,
-  resolveHost,
-  validateToken
-} from "./chunk-ZQKDZXDO.js";
-import "./chunk-3FY3RJ26.js";
-import "./chunk-JHENBQ5B.js";
-export {
-  getToken,
-  invalidateAccessTokenForRetry,
-  resolveHost,
-  validateToken
-};