@larktask/aamp-feishu-task-agent 0.1.0-dev.173 → 0.1.1-dev.2

package/README.md

@@ -1,7 +1,7 @@
 # aamp-feishu-task-agent
 
-One-click manager for binding local Codex/Cursor agents to user-owned Feishu
-Bots and running the corresponding Task bridges.
+One-click manager for binding local Codex/Cursor/Trae/WorkBuddy agents to
+user-owned Feishu Bots and running the corresponding Task bridges.
 
 ## Install and bind
 
@@ -26,11 +26,82 @@ The package installs the short command `feishu-task-agent`. Running that short
 command without arguments shows help. Running the standalone Bootstrap without
 arguments is equivalent to `install`.
 
-Only `codex` and `cursor` are supported by this flow. `--agent codex|cursor`
-fixes the Agent for every new binding in that command instead of prompting.
+The supported canonical agent names are `codex`, `cursor`, `coco`, `traex`,
+`traecli`, `workbuddy`, `workbuddy_ai`, and `aime`.
+`--agent codex|cursor|coco|traex|traecli|workbuddy|workbuddy_ai|aime` fixes the Agent
+for every new binding in that command instead of prompting.
+Selection menus, saved bindings, and startup output display these canonical
+`agent_type` values verbatim. The removed `trae` value is not accepted as a
+command-line alias or stored binding type; affected bindings must be created
+again with `coco`.
 The Task Agent flow only supports the Online environment. Environment-switch
 arguments are not supported.
 
+The Trae-family choice uses this order:
+
+1. `traex` → Trae CLI Next（内部版）
+2. `coco` → Trae CLI（内部版） and the existing Next upgrade prompt
+3. only when `coco` is absent, `traecli` → TraeCode CLI
+
+For the internal Trae CLI flow, accepting the upgrade prompt runs the Trae CLI
+Next installer and continues with `traex`. A new pending `coco` binding is
+normalized and saved as `traex`, so subsequent startup output uses `traex`.
+Declining the upgrade cancels the current binding or startup without
+invoking legacy `login`, `login status`, or ACP commands, and leaves saved
+bindings unchanged. Native ACP startup is exactly `traex acp serve`; the
+generated command intentionally omits `--yolo` and never adds a bypass or
+approval flag.
+
+TraeCode CLI is stored as `agent_type: traecli` and starts native ACP with
+`traecli acp serve`. If that command is unavailable, the launcher asks before
+running `traecli update`, then checks ACP again. It runs
+`traecli doctor --json` without entering the TUI; model errors ask you to open
+TraeCode CLI and use `/model`. The launcher never runs a TraeCode login/status
+command and never falls back to CLI Bridge.
+
+A saved `traecli` binding remains TraeCode CLI even after `traex` is installed.
+Ready `coco` bindings keep their stored identity and mailbox, while runtime
+startup output displays the resolved raw type `traex` or `traecli` that will
+actually be used.
+
+`workbuddy` is detected only from the standard macOS WorkBuddy.app installation:
+`/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy`.
+The launcher uses the app-bundled `codebuddy --acp` command.
+It does not run a WorkBuddy login command. Open WorkBuddy and complete login
+before starting a binding. Startup verifies login by creating and immediately
+closing a temporary ACP session without sending a model prompt. Nonstandard
+paths and non-macOS installations are not auto-detected.
+
+`workbuddy_ai` is the international WorkBuddy AI application. It is detected
+only at
+`/Applications/WorkBuddy AI.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy`.
+Its persisted and displayed Agent type remains the literal `workbuddy_ai`.
+When both WorkBuddy applications are installed, `workbuddy` and
+`workbuddy_ai` are offered independently. The Task Agent does not run a login
+command for either product; complete login in the selected desktop app.
+
+`aime` is the ByteDance-internal remote AIME Agent. It is offered only when a
+short `ping aime.bytedance.net` probe succeeds; an explicit `--agent aime`
+selection uses the same gate before any AIME install or login. The launcher
+installs the exact AIME version pinned by the bootstrap as
+`@tengchengwei/aime-acp@<version>` from `https://bnpm.byted.org` into
+the shared `$HOME/.aamp/npm-global` prefix, removes the obsolete unscoped
+`aime-acp` package when present, then runs the scoped package's absolute
+`dist/bin.js` entry with `--site cn`.
+Readiness is authoritative only after `auth status`/`auth login` and
+`doctor --site cn --json` succeed; ping is only the one-click visibility gate.
+The generated bridge config rejects attachments and limits AIME task dispatch
+to one task at a time because AIME is remote and does not use the local
+workspace. All other Agents default to local execution; AIME is explicitly
+configured as remote. It reads requested Feishu/Lark data with its own
+remote-native capabilities and identity, without a local `lark-cli` profile or
+user OAuth. The local Feishu Bridge still uses Bot App credentials and is the
+only writer of the current Task's comment, status, and delivery. Remote
+attachments and local file delivery are unsupported; use text or HTTP(S) links.
+`aamp-feishu-task-bridge` is deprecated and is not an AIME implementation
+target. AIME `auth`/`doctor` success proves adapter readiness only, not access
+to a particular Feishu group.
+
 ## Commands
 
 ```bash
@@ -43,16 +114,22 @@ feishu-task-agent update
 feishu-task-agent help
 ```
 
-- `install` collects one or more pairs, then serially pairs and starts them.
-  The initial successful Bridge processes remain running.
+- `install` preserves saved pairs and atomically saves each accepted pair as
+  pending before it starts any Bridge. If the Bot App ID is already bound,
+  replacement requires explicit confirmation. A startup failure leaves the
+  pending pair available for a later `start` retry; successful Bridge processes
+  remain running.
 - `start` multi-selects saved pairs. Selecting `全部` takes precedence over any
   other selection. If no pair is configured, the terminal prints the full
-  install command.
+  install command. Its final summary retains the successful/planned count and
+  lists the concrete successful, failed, and cancelled pairs.
 - `list` prints saved Agent-Bot pairs and never prints App Secrets.
-- `add` completes Bot selection/creation and lark-cli authorization, then saves
-  each pair as pending. It does not acquire an Agent lease, perform ACP pairing,
-  or start any Bridge. The first subsequent `start` completes pairing, creates
-  runtime configuration, and keeps the selected Bridges running.
+- `add` uses the same confirmed atomic add/replace behavior and saves each pair
+  as pending. It does not acquire an Agent lease, perform ACP pairing, or start
+  any Bridge. When another Task Agent is already running, its Bridges are not
+  hot-switched or stopped; the saved configuration is used by the next `start`.
+  The first subsequent `start` completes pairing, creates runtime configuration,
+  and keeps the selected Bridges running.
 - `remove` multi-selects pairs, with a `全部` option. It only removes saved
   pairing records; Bridges that are already running are not stopped.
 - `update` refreshes the installed short command and package.
@@ -63,7 +140,8 @@ and Enter to confirm the selection.
 
 Bridge startup is serial. A failure is printed and recorded, then the next pair
 is attempted. The command exits as a startup failure only when every selected
-pair fails. Within one command invocation, all Bots for the same Agent/AAMP
+pair fails. User-cancelled Coco selections are reported separately and
+are not recorded as system failures. Within one command invocation, all Bots for the same Agent/AAMP
 host reuse one ACP Bridge process. Independent invocations do not attach to an
 existing process; an Agent lease prevents competing runtimes from being
 started for the same Agent identity.
@@ -107,12 +185,30 @@ version. They remain visible to `list` and can be deleted with `remove`, but
 `start` skips them with an explicit error and continues with the next binding.
 
 If a saved `lark-cli` profile is missing, `start` recreates it from the stored
-App ID/App Secret and resumes user authorization. If the persisted Agent or
-Feishu Bridge mailbox identity is missing or has changed, startup rejects that
-pair and asks the user to bind it again instead of reporting a false success.
-The same Online `LARKSUITE_CLI_CONFIG_DIR` is passed to Feishu Bridge, Agent
-Bridge, and the local Codex/Cursor process so task execution resolves the exact
-profile created during binding.
+App ID/App Secret. User OAuth is optional by default and never blocks Task/IM
+Bridge startup. The embedded version-2 scope manifest configures only the Task
+and IM application capabilities used by this package; it does not expand
+Base, Calendar, Mail, Minutes, VC, Wiki, or other user domains. Existing bot
+profiles are rewritten with `domains: ["task"]` when they are saved again.
+
+`FEISHU_USER_AUTH_MODE` controls the local user capability policy:
+
+- `optional` (default) reuses an existing valid token, records unavailable
+  optional capabilities, and continues without opening a browser.
+- `required` requests the fixed Task user scope set once and fails only when
+  those explicit scopes remain missing. The command never passes `--domain`.
+- `disabled` skips user capability checks and runs Task-only.
+
+Granted and missing user scopes are recorded without credentials under
+`~/.aamp/feishu-bridge/auth-capabilities/<profile>.json`. Legacy
+`FEISHU_USER_AUTH_EXCLUDES` values are intersected with the current explicit
+request, so stale or tenant-invisible scope names cannot create a new failure.
+
+If the persisted Agent or Feishu Bridge mailbox identity is missing or has
+changed, startup rejects that pair and asks the user to bind it again instead
+of reporting a false success. The same Online `LARKSUITE_CLI_CONFIG_DIR` is
+passed to Feishu Bridge, Agent Bridge, and the local Codex/Cursor/Trae process
+so task execution resolves the exact profile created during binding.
 
 ## Local logs and diagnostics
 

package/bin/agent-metadata.mjs

@@ -0,0 +1,54 @@
+import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export const TASK_AGENT_METADATA = Object.freeze({
+  codex: Object.freeze({ executionLocation: 'local' }),
+  cursor: Object.freeze({ executionLocation: 'local' }),
+  coco: Object.freeze({ executionLocation: 'local' }),
+  traex: Object.freeze({ executionLocation: 'local' }),
+  traecli: Object.freeze({ executionLocation: 'local' }),
+  workbuddy: Object.freeze({ executionLocation: 'local' }),
+  workbuddy_ai: Object.freeze({ executionLocation: 'local' }),
+  aime: Object.freeze({
+    executionLocation: 'remote',
+    attachmentPolicy: 'reject',
+    taskDispatchConcurrency: 1,
+  }),
+})
+
+export const TASK_AGENT_TYPES = Object.freeze(Object.keys(TASK_AGENT_METADATA))
+
+export function resolveTaskAgentMetadata(agentType) {
+  const normalized = String(agentType ?? '').trim()
+  const metadata = TASK_AGENT_METADATA[normalized]
+  if (!metadata) throw new Error(`Unknown Task Agent type: ${normalized || '(empty)'}`)
+  return { ...metadata }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    return false
+  }
+}
+
+if (isMainModule()) {
+  if (process.argv[2] !== '--json' || !process.argv[3] || process.argv[4]) {
+    console.error('Usage: node agent-metadata.mjs --json <agent-type>')
+    process.exitCode = 2
+  } else {
+    try {
+      const agentType = process.argv[3].trim()
+      process.stdout.write(`${JSON.stringify({
+        schemaVersion: 1,
+        agentType,
+        ...resolveTaskAgentMetadata(agentType),
+      })}\n`)
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error))
+      process.exitCode = 1
+    }
+  }
+}