evolcore 0.0.35 → 0.0.37

package/dist/cli/aun-commands.js

@@ -9,10 +9,12 @@ import { isValidAid as validSendAid } from '../aun/aid/validation.js';
 import { AGENT_DELEGATION_TOKEN_ENV, readDelegationCredential } from '../core/auth/agent-delegation.js';
 import { isManagementRole } from '../config/builtin-roles.js';
 import { readBestTaskRuntimeContext } from './task-context.js';
-import { assertEcSingleLine } from './cli-argv.js';
+import { assertEcSingleLine, parseTimeArg, TIME_ARG_FORMATS } from './cli-argv.js';
 import { canonicalizeEvolcoreCommandArgv } from '../core/permission/ec-command-parser.js';
 import { ManagedGroupOperationError } from '../aun/msg/managed-operation.js';
 import { parseDuration } from '../trigger/parser.js';
+import { isTopicThreadId, safeFormatMainTopicId } from '../core/thread/topic-id.js';
+import { parseJsonObjectArgument } from '../core/permission/ec-command-parser.js';
 // ==================== AID ====================
 function resolveAunPath(args) {
     const idx = args.indexOf('--aun-path');
@@ -194,9 +196,9 @@ async function runManagedAid(args, formatJson) {
                 console.log(`✓ 头像已更新${response.result.avatar ? `: ${response.result.avatar}` : ''}${response.result.sha256 ? ` (sha256: ${response.result.sha256})` : ''}`);
     }
 }
-function failManagedGroup(formatJson, code, error) {
+function failManagedGroup(formatJson, code, error, details = {}) {
     if (formatJson)
-        console.log(JSON.stringify({ ok: false, code, error }));
+        console.log(JSON.stringify({ ok: false, code, error, ...details }));
     else
         console.error(`❌ ${error}`);
     process.exit(1);
@@ -465,6 +467,8 @@ Commands:
   agentmd get <aid> 下载 agent.md → 验签 → 本地持久化
   agentmd set <aid> <field> <value> 修改一个字段并签名上传
   avatar <aid> --file <path> | --url <https-url>  上传头像并更新 agent.md
+  bind <ownerAid> [--subject <subjectAid>]      发起 Ownership 2.1 绑定
+  bind status [--subject <subjectAid>]         核验协议 Owner、任务和同步状态
 
 Options:
   --format json     输出 JSON 格式
@@ -485,6 +489,11 @@ Options:
   ec aid agentmd set mybot.agentid.pub description "A helpful agent"`);
         return;
     }
+    if (sub === 'bind') {
+        const { cmdAidBind } = await import('./aid-bind-command.js');
+        await cmdAidBind(args.slice(1));
+        return;
+    }
     const isAgentmdHelp = sub === 'agentmd' && (!args[1] || isHelpFlag(args[1]));
     if (process.env.EVOLCORE_SESSION_ID && !wantsHelp(args) && !isAgentmdHelp) {
         await runManagedAid(args, formatJson);
@@ -617,11 +626,11 @@ Options:
             process.exit(1);
         }
         try {
-            const result = await aidCreate(aid, { aunPath, force });
+            const result = await aidCreate(aid, { aunPath, force, type: 'service' });
             let agentmdUploaded = result.alreadyExisted;
             let agentmdError;
             if (!result.alreadyExisted) {
-                const content = buildInitialAgentMd({ aid });
+                const content = buildInitialAgentMd({ aid, type: 'service' });
                 try {
                     await agentmdPut(content, { aid, aunPath });
                     agentmdUploaded = true;
@@ -1318,8 +1327,10 @@ Options:
  *
  * `ec msg send --thread T2 --check-every 5m` 发送成功后自动创建。
  *
- * 使用 `interval` 而非 `delay`：周期触发，只有显式
- * `ec trigger cancel` 或 `ec trigger update --every <新时长>` 才改变其状态。
+ * 使用 `interval` 而非 `delay`：周期触发，由显式
+ * `ec trigger delete`（结束，不留残留）/ `ec trigger update --every <新时长>`（调整周期）改变状态。
+ * `ec trigger cancel` 只是 disable，定义仍留在磁盘上，复查这种用完即弃的 Trigger
+ * 不该走 cancel，否则会积压大量永不触发的死定义。
  * 一次性 Trigger 会静默消失，无法承担「一直跟进直到显式结束」的语义。
  */
 export function buildThreadCheckTrigger(input) {
@@ -1332,21 +1343,24 @@ export function buildThreadCheckTrigger(input) {
         enabled: true,
         createdAt: now,
         updatedAt: now,
-        // T10: labels 携带 kind + 业务上下文，渲染层按 kind=thread-check 路由到专属模板
         labels: {
-            kind: 'thread-check',
+            kind: 'cross-thread-review',
             originThreadId: input.originThreadId,
             targetThreadId: input.targetThreadId,
             originPeer: input.originPeer,
             checkEvery: input.checkEvery,
+            ...(input.originalText ? { originalText: input.originalText } : {}),
+            // labels 只收字符串（validation.ts 校验）；scheduler 读取时用 Number() 还原。
+            ...(input.firstSentAt ? { firstSentAt: String(input.firstSentAt) } : {}),
+            ...(input.originThreadName ? { originThreadName: input.originThreadName } : {}),
+            ...(input.targetThreadName ? { targetThreadName: input.targetThreadName } : {}),
         },
         ...(input.origin ? { origin: input.origin } : {}),
         // 周期触发：每 everyMs 唤醒一次，直到显式取消/调整
         source: { type: 'interval', everyMs: input.everyMs },
         execution: {
-            type: 'trigger_session',
+            type: 'target_session',
             prompt: input.prompt,
-            thread: 'by_trigger',
             onError: 'retry',
             noopSentinel: '[[NOOP]]',
         },
@@ -1355,7 +1369,8 @@ export function buildThreadCheckTrigger(input) {
             target: {
                 channelKey: input.channelKey,
                 channelId: input.targetChannelId,
-                session: 'thread',
+                // 话题走 `thread`；主话题走 `main`（threadId 是主话题规范 id，仅作身份记录）。
+                session: isTopicThreadId(input.targetThreadId) ? 'thread' : 'main',
                 threadId: input.targetThreadId,
                 chatType: input.feedbackChatType ?? 'private',
             },
@@ -1363,6 +1378,41 @@ export function buildThreadCheckTrigger(input) {
         reliability: { concurrency: 'forbid', missedPolicy: 'run_once', retry: { maxAttempts: 0, backoffMs: 30_000 } },
     };
 }
+/**
+ * 构造跨话题复查的通知正文模板。
+ *
+ * 关键约束（见 docs/thread-chain/cross-thread-review-design.md §3.4）：
+ * - 只带**数据上下文**（话题名/ID、时间、次数、周期、Trigger id、原消息），
+ *   **不带任何操作命令**——命令与决策判据由 thread-ops skill 提供；
+ * - T1 的 threadId 必须列出：回 T1 汇报或查空洞期都要用它做 `--thread` / `history` 参数；
+ * - T2 的 threadId 不列：收到通知的会话本身就在 T2；
+ * - `【跨话题复查】` 是信封头关键字，供 skill 的关键词触发使用；
+ * - 原消息放最后：正文可能较长，前置字段保持可扫读。
+ *
+ * 模板用 `{{...}}` 占位，触发时由 `renderTemplate` 渲染（scheduler.ts 每次 fire
+ * 都会重新渲染，因此"第几次/已过多久"必须在渲染期计算，不能写死）。
+ */
+export function buildCrossThreadReviewPrompt(input) {
+    const truncated = input.originalText && input.originalText.length > 500
+        ? `${input.originalText.slice(0, 500)}…`
+        : input.originalText;
+    return [
+        '【跨话题复查】第 {{run.number}} 次',
+        '',
+        `来源话题：${input.originThreadName}（对端 ${input.originPeerName}）`,
+        `来源话题 ID：${input.originThreadId}`,
+        `当前话题：${input.targetThreadName}（对端 ${input.targetPeerName}）`,
+        `发送于：{{trigger.labels.firstSentAtTime}}`,
+        `已过：{{run.elapsed}}`,
+        `复查周期：${input.checkEvery}（每 ${input.checkEvery} 提醒一次，直到处理）`,
+        '',
+        `Trigger：${input.triggerId}`,
+        ...(input.extra?.trim() ? ['', input.extra.trim()] : []),
+        '',
+        '原消息：',
+        truncated || '（非文本消息）',
+    ].join('\n');
+}
 /**
  * 解析并校验 `--check-every`。返回 `{ durationMs }` 或错误。
  * 私聊与群聊两条跨话题发送路径共用，保证错误码一致。
@@ -1388,19 +1438,54 @@ function parseCheckEveryArgs(checkEveryRaw, hasCheckEvery) {
  * 设计见 `docs/thread-chain/thread-context-mechanism.md` §十、`thread-cli-spec-v2.md` §3.4。
  * 任意一步失败都不影响消息已发出的事实：返回 `triggerId` 为 undefined 时调用方照常输出发送结果。
  */
+/** Trigger 名称里的话题片段：主话题 id 缩成 `main`（名称不承担身份）。 */
+function triggerTopicLabel(topicId) {
+    if (!topicId)
+        return 'unknown';
+    return isTopicThreadId(topicId) ? topicId : 'main';
+}
 async function applyCrossThreadSendEffects(input) {
     const runtime = await readBestTaskRuntimeContext();
-    const originThreadId = runtime?.threadId || 'main';
     const originPeer = runtime?.channelId || input.targetChannelId;
+    // 来源话题 id：话题用原 id；主话题用"本端+对端"拼出的规范 id。
+    // 这里给的是**展示与持久化用**的身份，不会写进线上报文。
+    const originThreadId = isTopicThreadId(runtime?.threadId)
+        ? runtime.threadId
+        : (safeFormatMainTopicId(input.selfAid, originPeer) ?? '');
     const originSessionId = runtime?.sessionId;
     if (!originSessionId)
         return { inboxWritten: false };
+    // 话题名：从索引取，取不到时降级到 threadId 或 'main'。
+    // 从 index.js 聚合入口引入：单文件实现路径会绕过测试里对 '../core/thread/index.js'
+    // 的 vi.mock，导致 mock 未覆盖时整个模块被真实加载而报错。
+    // 取值全部包在 try/catch 里：话题名只是通知里的展示信息，索引读失败不能影响
+    // "消息已经发出去了"这个事实，也不能阻止复查创建。
+    let originThreadName = originThreadId || originPeer;
+    let originPeerName = originPeer;
+    let targetThreadName = input.targetThreadId;
+    let targetPeerName = input.targetChannelId;
+    try {
+        const { ThreadService } = await import('../core/thread/index.js');
+        const originEntry = isTopicThreadId(originThreadId)
+            ? ThreadService.findThreadById(input.selfAid, originThreadId)
+            : ThreadService.findMainSessionEntry?.(input.selfAid, originPeer);
+        const targetEntry = isTopicThreadId(input.targetThreadId)
+            ? ThreadService.findThreadById(input.selfAid, input.targetThreadId)
+            : ThreadService.findMainSessionEntry?.(input.selfAid, input.targetChannelId);
+        originThreadName = originEntry?.name || originThreadName;
+        originPeerName = originEntry?.peerName || originPeerName;
+        targetThreadName = targetEntry?.name || targetThreadName;
+        targetPeerName = targetEntry?.peerName || targetPeerName;
+    }
+    catch {
+        // 索引不可用时保留 threadId / AID 作为降级展示值
+    }
     // Trigger 的 id 与 name 是两个不同的东西（见 src/trigger/validation.ts:727）：
-    //   id   = `trig_<ts>_<8位hex>` —— 唯一的持久化标识，`ec trigger show/update/cancel` 只认它
+    //   id   = `trig_<ts>_<8位hex>` —— 唯一的持久化标识，`ec trigger show/update/delete` 只认它
     //   name = `check-<目标threadId>-from-<来源threadId>-<唯一后缀>` —— 人读标签，不参与定位
     //
     // 这里**在 IPC 之前**就把 id 定下来，有三个理由：
-    //   1. prompt 里要写 `ec trigger cancel <id>`，而 prompt 是 definition 的一部分，
+    //   1. prompt 里要写 `ec trigger delete <id>`，而 prompt 是 definition 的一部分，
     //      create 之前就得拼完，拿不到 daemon 的返回值；
     //   2. definition 带上 id 后 daemon 直接采用（normalizeV3Phase2 认 `raw.id`），
     //      落盘 id 与 prompt 中的 id 天然一致，不存在"返回值和 prompt 两套值"的漂移；
@@ -1412,24 +1497,19 @@ async function applyCrossThreadSendEffects(input) {
     // (目标, 来源) 对第二次发送就撞 `trigger name already exists`（assertUnique 按 name 去重），
     // 结果消息照发、inbox 照写、Trigger 静默不建 —— 完全无感知。
     // 每次 `--check-every` 都该有自己的 new Trigger（要复用应走 update），所以追加唯一后缀。
-    const triggerName = `check-${input.targetThreadId}-from-${originThreadId}-${triggerSeed.split('_')[1]}`;
-    const userPromptPart = input.triggerPromptExtra
-        ? input.triggerPromptExtra
-        : `请检查该话题的最新进度，根据情况：继续等待、调整周期（ec trigger update ${triggerId} --every <时长>）或结束复查（ec trigger cancel ${triggerId}）。`;
-    const prompt = [
-        `【Trigger 复查】话题 ${input.targetThreadId}（对端 ${input.targetChannelId}）`,
-        `这是周期复查：每 ${input.checkEveryLabel} 唤醒一次，直到你显式结束它。`,
-        ``,
-        userPromptPart,
-        ``,
-        `参考命令：`,
-        `  ec thread history ${input.targetChannelId}/${input.targetThreadId} --limit 10`,
-        `  ec thread history ${originPeer}/${originThreadId} --after ${Date.now()}`,
-        `  ec trigger cancel ${triggerId}`,
-        `  ec trigger update ${triggerId} --every <时长>`,
-        `Trigger id：${triggerId}`,
-        `Trigger 名称：${triggerName}`,
-    ].join('\n');
+    const triggerName = `check-${triggerTopicLabel(input.targetThreadId)}-from-${triggerTopicLabel(originThreadId)}-${triggerSeed.split('_')[1]}`;
+    const prompt = buildCrossThreadReviewPrompt({
+        triggerId,
+        originThreadId,
+        originThreadName,
+        originPeerName,
+        targetThreadName,
+        targetPeerName,
+        checkEvery: input.checkEveryLabel,
+        firstSentAt: input.timestamp,
+        originalText: input.contentSummary,
+        extra: input.triggerPromptExtra,
+    });
     let createdTriggerId;
     try {
         const { formatChannelKey } = await import('../core/channel-loader.js');
@@ -1446,6 +1526,10 @@ async function applyCrossThreadSendEffects(input) {
             originThreadId,
             originPeer,
             feedbackChatType: input.feedbackChatType,
+            originalText: input.contentSummary,
+            firstSentAt: input.timestamp,
+            originThreadName,
+            targetThreadName,
         });
         const triggerRes = await ipcQuery(resolvePaths().socket, {
             type: 'trigger.create',
@@ -1498,6 +1582,7 @@ Commands:
   send <from> <to> --file <path> [--as <type>]         发送文件（image|video|voice|file）
   send <from> <to> --link <url> [--title T]            发送链接卡片
   send <from> <to> --payload <json>                    发送自定义 payload
+  request get <self-aid> <request-id>                  查询已登记请求状态
   pull <from> [--after-seq N] [--limit N] --app <name> 拉取收件箱（必须使用独立 slot）
   ack <from> <seq> [--app <name>]                      确认已读
   recall <from> <message-id> [<message-id>...]         撤回消息
@@ -1514,6 +1599,9 @@ Options:
   --app <name>          指定应用 slot（独立消费通道，不影响 daemon）
   --aun-path <path>     指定 AUN keystore 根
   --format json         输出 JSON 格式
+  --payload '<json>'    发送任意 JSON payload，不添加聊天字段
+  --return none|required  是否等待关联响应（required 建立请求记录）
+  --timeout <duration>  required 的等待期限和 AUN volatile TTL，如 30s、60s、2m（默认 60s，最大 3600s）
   --encrypt             强制端到端加密（未指定时使用 daemon 默认值）
   --no-encrypt          强制明文发送（优先于 --encrypt）
   --thread <id>         指定目标话题 ID（话题必须存在于本端索引；from/to 可省略）
@@ -1525,10 +1613,11 @@ Options:
   --channel-name <name> 历史渠道实例名（非 AUN 渠道必须匹配 Agent 配置）
   --channel-key <key>   非 AUN 已落盘渠道的完整实例键（与 --peer-id 成对）
   --peer-id <id>        非 AUN 渠道的原生对端 ID（与 --channel-key 成对）
-  --check-every <duration> 跨话题发送后自动创建**周期**复查 Trigger（如 5m/30m/2h），跨话题时**必填**
-                         每 duration 唤醒一次，直到显式 ec trigger cancel 结束
+  --check-every <duration> 跨话题发送后自动创建**跨话题复查**（如 5m/30m/2h），跨话题时**必填**
+                         每 duration 向**目标话题**投递一条【跨话题复查】通知（不新建会话），
+                         由目标话题侧的 agent 在自己的上下文里决定结束/调整周期/继续
                          Trigger 名：check-<目标threadId>-from-<来源threadId>-<唯一后缀>
-                         取消/调整用返回的 trigger_id（trig_…），show/update/cancel 只认 id
+                         结束/调整用返回的 trigger_id（trig_…），show/update/delete 只认 id
   --content-type <mime> 显式覆盖 MIME（仅 --file 模式）
   --as <type>           附件类型：image|video|voice|file（仅 --file 模式）
   --text <说明>          附件说明文字（仅 --file 模式）
@@ -1545,6 +1634,8 @@ Options:
   ec msg send alice.agentid.pub bob.agentid.pub --file ./pic.png
   ec msg send alice.agentid.pub bob.agentid.pub --file ./demo.mp4 --as video
   ec msg send alice.agentid.pub bob.agentid.pub --link https://example.com --title "AUN"
+  ec msg send alice.agentid.pub bob.agentid.pub --payload '{"type":"query"}' --return required --timeout 60s --format json
+  ec msg request get alice.agentid.pub request-123 --format json
   ec msg pull alice.agentid.pub --app my-bot
   ec msg ack alice.agentid.pub 42 --app my-bot
   ec msg recall alice.agentid.pub msg-uuid-1 msg-uuid-2
@@ -1584,6 +1675,41 @@ Options:
     }
     // P1b.6.2: 托管会话 send 时，from/to 可省略——从 runtime 和话题索引推断
     // history --thread 时同理：from/to 均可省略
+    //
+    // 本端来源：托管会话里恒取**当前会话的本端**（`runtime.selfAid`）——这正是
+    // "主话题 id 隐含本端"成立的前提。显式 `--self` 只用于宿主终端（下方分支），
+    // 托管会话里写了就必须与当前本端一致，不允许拿它去冒充别的本端。
+    if (sub === 'request' && args[1] === 'get') {
+        const aid = args[2];
+        const requestId = args[3];
+        if (!aid || !requestId) {
+            console.error('usage: ec msg request get <self-aid> <request-id> [--format json]');
+            process.exit(1);
+        }
+        const runtime = await readBestTaskRuntimeContext();
+        if (runtime?.selfAid && runtime.selfAid.replace(/^@/, '') !== aid) {
+            console.error(`request status is limited to the delegated self AID: ${runtime.selfAid}`);
+            process.exit(1);
+        }
+        const result = await ipcQuery(resolvePaths().socket, {
+            type: 'aun-msg-request-get', aid, requestId,
+            sessionId: process.env.EVOLCORE_SESSION_ID,
+            delegationToken: readDelegationCredential(),
+        }, 10_000);
+        if (!result) {
+            console.error('unable to connect to the EvolCore daemon');
+            process.exit(1);
+        }
+        if (formatJson)
+            console.log(JSON.stringify(result));
+        else if (!result.ok)
+            console.error(`request query failed: ${result.error}`);
+        else
+            console.log(`request_id=${requestId} state=${result.request?.state ?? 'unknown'} message_id=${result.request?.outboundMessageId ?? '-'}`);
+        if (!result.ok)
+            process.exit(1);
+        return;
+    }
     if (process.env.EVOLCORE_SESSION_ID && (sub === 'send' || (sub === 'history' && getArgValue(args, '--thread')))) {
         const { isValidAid: checkAid } = await import('../aun/aid/index.js');
         const hasFrom = typeof args[1] === 'string' && checkAid(args[1]);
@@ -1592,13 +1718,36 @@ Options:
             const runtime = await readBestTaskRuntimeContext();
             if (runtime?.selfAid) {
                 const inferredFrom = runtime.selfAid.replace(/^@/, '');
+                const explicitSelf = getArgValue(args, '--self')?.replace(/^@/, '');
+                if (explicitSelf && explicitSelf !== inferredFrom) {
+                    console.error(`❌ 当前会话的本端是 ${inferredFrom}，--self 不能指定 ${explicitSelf}；跨本端发送只能由该本端自己的会话发起`);
+                    process.exit(1);
+                }
                 let inferredTo;
                 const threadArg = getArgValue(args, '--thread');
                 if (threadArg) {
-                    const { ThreadService } = await import('../core/thread/index.js');
-                    inferredTo = ThreadService.findThreadById(inferredFrom, threadArg)?.peer;
+                    // 目标对端只能从话题引用里推导：主话题 id 自带另一端，话题查本端索引。
+                    // 解析失败必须直接失败——回落到"当前对端"会把一条本应发往别处的消息
+                    // 静默投进当前会话。
+                    const { resolveThreadRef } = await import('../core/thread/topic-id.js');
+                    const resolved = resolveThreadRef(threadArg, inferredFrom);
+                    if (resolved.kind === 'main') {
+                        inferredTo = resolved.peer;
+                    }
+                    else if (resolved.kind === 'thread') {
+                        const { ThreadService } = await import('../core/thread/index.js');
+                        inferredTo = resolved.peer ?? ThreadService.findThreadById(inferredFrom, resolved.threadId)?.peer;
+                    }
+                    else if (resolved.kind === 'invalid') {
+                        console.error(`❌ ${resolved.error}`);
+                        process.exit(1);
+                    }
+                    if (!inferredTo) {
+                        console.error(`❌ 无法从话题引用确定目标对端: ${threadArg}（话题必须存在于本端索引）`);
+                        process.exit(1);
+                    }
                 }
-                if (!inferredTo) {
+                else {
                     inferredTo = runtime.channelId?.replace(/^@/, '');
                 }
                 if (!hasFrom && !hasTo && inferredTo) {
@@ -1613,6 +1762,45 @@ Options:
             }
         }
     }
+    // 宿主终端的简化式：`ec msg send '<正文>' --self <selfAid> --thread <ref>`
+    // 没有托管会话上下文，本端只能由 --self 给出；对端由话题引用推导。
+    // 这和托管会话里的简化式是同一语义，只是本端来源不同。
+    if (sub === 'send' && !process.env.EVOLCORE_SESSION_ID) {
+        const { isValidAid: checkAid } = await import('../aun/aid/index.js');
+        const selfArg = getArgValue(args, '--self')?.replace(/^@/, '');
+        const threadArg = getArgValue(args, '--thread');
+        const hasFrom = typeof args[1] === 'string' && checkAid(args[1]);
+        const hasTo = typeof args[2] === 'string' && checkAid(args[2]);
+        if (threadArg && (!hasFrom || !hasTo)) {
+            if (!selfArg || !checkAid(selfArg)) {
+                console.error('❌ 省略 <from> <to> 时必须用 --self <本端AID> 指定本端（对端由 --thread 推导）');
+                process.exit(1);
+            }
+            const { resolveThreadRef } = await import('../core/thread/topic-id.js');
+            const resolved = resolveThreadRef(threadArg, selfArg);
+            if (resolved.kind === 'invalid' || resolved.kind === 'current') {
+                console.error(`❌ ${resolved.kind === 'invalid' ? resolved.error : '无效的话题引用'}`);
+                process.exit(1);
+            }
+            let peer;
+            if (resolved.kind === 'main')
+                peer = resolved.peer;
+            else {
+                const { ThreadService } = await import('../core/thread/index.js');
+                peer = resolved.peer ?? ThreadService.findThreadById(selfArg, resolved.threadId)?.peer;
+            }
+            if (!peer) {
+                console.error(`❌ 无法从话题引用确定目标对端: ${threadArg}（话题必须存在于本端索引）`);
+                process.exit(1);
+            }
+            if (!hasFrom && !hasTo)
+                args.splice(1, 0, selfArg, peer);
+            else if (!hasFrom)
+                args.splice(1, 0, selfArg);
+            else
+                args.splice(2, 0, peer);
+        }
+    }
     const from = args[1];
     if (!from) {
         console.error('❌ 缺少 <from-aid> 参数');
@@ -1621,6 +1809,9 @@ Options:
     const { isValidAid } = await import('../aun/aid/index.js');
     if (!isValidAid(from)) {
         console.error(`❌ 无效 AID 格式: ${from}`);
+        if (sub === 'send') {
+            console.error('提示：宿主终端可用 `ec msg send \'<正文>\' --self <本端AID> --thread <话题id> --check-every 5m`');
+        }
         process.exit(1);
     }
     if (process.env.EVOLCORE_SESSION_ID && sub !== 'send') {
@@ -1649,7 +1840,7 @@ Options:
     if (sub === 'history') {
         const target = args[2] && !args[2].startsWith('--') ? args[2] : undefined;
         const historyValueFlags = new Set([
-            '--session', '--limit', '--before', '--after', '--direction', '--channel', '--channel-name', '--format', '--channel-key', '--peer-id',
+            '--session', '--limit', '--before', '--after', '--direction', '--channel', '--channel-name', '--format', '--channel-key', '--peer-id', '--thread', '--self',
         ]);
         const seenHistoryFlags = new Set();
         for (let index = target ? 3 : 2; index < args.length; index++) {
@@ -1679,14 +1870,14 @@ Options:
         const limit = limitRaw === undefined ? undefined : Number(limitRaw);
         const beforeRaw = getArgValue(args, '--before');
         const afterRaw = getArgValue(args, '--after');
-        const before = beforeRaw === undefined ? undefined : parseMsgHistoryTime(beforeRaw);
-        const after = afterRaw === undefined ? undefined : parseMsgHistoryTime(afterRaw);
+        const before = beforeRaw === undefined ? undefined : parseTimeArg(beforeRaw);
+        const after = afterRaw === undefined ? undefined : parseTimeArg(afterRaw);
         if (beforeRaw !== undefined && before === undefined) {
-            console.error(`❌ --before 必须是 epoch 毫秒或有效时间: ${beforeRaw}`);
+            console.error(`❌ --before 不是有效时间: ${beforeRaw}（支持 ${TIME_ARG_FORMATS}）`);
             process.exit(1);
         }
         if (afterRaw !== undefined && after === undefined) {
-            console.error(`❌ --after 必须是 epoch 毫秒或有效时间: ${afterRaw}`);
+            console.error(`❌ --after 不是有效时间: ${afterRaw}（支持 ${TIME_ARG_FORMATS}）`);
             process.exit(1);
         }
         const channelKey = getArgValue(args, '--channel-key');
@@ -1725,6 +1916,18 @@ Options:
                 process.exit(1);
             }
         }
+        // `--thread` 接受 `ec thread list` 打印的 `<peer>/<id>`；前缀必须就是本次查询的对端
+        let historyThreadId;
+        const historyThreadRaw = getArgValue(args, '--thread');
+        if (historyThreadRaw !== undefined) {
+            const { normalizeThreadOptionValue } = await import('../core/thread/topic-id.js');
+            const normalized = normalizeThreadOptionValue(historyThreadRaw, peer => peer === target?.replace(/^@/, ''));
+            if (!normalized.ok) {
+                console.error(`❌ ${normalized.error}`);
+                process.exit(1);
+            }
+            historyThreadId = normalized.threadId;
+        }
         const result = msgHistory({
             from,
             ...(usesSelector
@@ -1735,7 +1938,7 @@ Options:
             before,
             after,
             direction: (getArgValue(args, '--direction') ?? 'all'),
-            threadId: getArgValue(args, '--thread'),
+            threadId: historyThreadId,
         });
         if (!result.ok) {
             if (format === 'json')
@@ -1824,7 +2027,7 @@ Options:
         else if (payloadVal) {
             let parsed;
             try {
-                parsed = JSON.parse(payloadVal);
+                parsed = parseJsonObjectArgument(payloadVal);
             }
             catch (e) {
                 console.error(`❌ --payload 解析失败: ${e.message}`);
@@ -1845,27 +2048,50 @@ Options:
             ? false
             : args.includes('--encrypt') ? true : undefined;
         const thread = getArgValue(args, '--thread');
-        // P1b.6.5: 话题存在性校验 — --thread 指定的话题必须在本端索引里存在
+        // P1b.6.5: 话题存在性校验 — 引用必须能解析成本端已存在的话题
         let threadEntry;
+        // 复查 Trigger 里记录的"目标话题"必须是规范 id：话题原样，主话题用
+        // `main:<a>:<b>`（`--thread` 可能写的是裸对端 AID 或 `<peer>/<id>` 历史写法）。
+        let threadTopicId = thread ?? '';
         if (thread) {
             const { ThreadService, normalizeThreadPeer } = await import('../core/thread/index.js');
-            threadEntry = ThreadService.findThreadById(from, thread);
-            if (!threadEntry || normalizeThreadPeer(threadEntry.peer) !== normalizeThreadPeer(to)) {
-                if (formatJson) {
-                    console.log(JSON.stringify({ ok: false, code: 'TOPIC_NOT_FOUND', error: `话题不存在: ${thread}` }));
-                }
-                else {
-                    console.error(`❌ 话题不存在: ${thread}`);
-                }
+            const { resolveThreadRef, isMainSessionThreadId } = await import('../core/thread/topic-id.js');
+            const resolved = resolveThreadRef(thread, from);
+            const fail = (message) => {
+                if (formatJson)
+                    console.log(JSON.stringify({ ok: false, code: 'TOPIC_NOT_FOUND', error: message }));
+                else
+                    console.error(`❌ ${message}`);
                 process.exit(1);
+            };
+            if (resolved.kind === 'invalid' || resolved.kind === 'current')
+                fail(resolved.kind === 'invalid' ? resolved.error : '无效的话题引用');
+            else if (resolved.kind === 'main') {
+                if (normalizeThreadPeer(resolved.peer) !== normalizeThreadPeer(to))
+                    fail(`主话题 ${thread} 的对端不是 ${to}`);
+                const main = await ThreadService.findMainSessionEntry(from, resolved.peer);
+                if (!main)
+                    fail(`与 ${resolved.peer} 无主话题会话`);
+                threadEntry = main;
+                threadTopicId = resolved.topicId;
+            }
+            else {
+                threadEntry = ThreadService.findThreadById(from, resolved.threadId);
+                const peer = resolved.peer ?? threadEntry?.peer;
+                if (!threadEntry || !peer || normalizeThreadPeer(threadEntry.peer) !== normalizeThreadPeer(to)) {
+                    fail(`话题不存在: ${thread}`);
+                }
+                threadTopicId = resolved.threadId;
             }
         }
-        // T8: 跨话题发送必须显式指定复查周期（发送前校验，避免消息已发出才报错）
+        // T8: 跨话题发送必须显式指定复查周期（发送前校验，避免消息已发出才报错）。
+        // 仅托管会话（有 runtime.sessionId）才会创建复查 Trigger，宿主终端直发不受此限制。
         const checkEveryRaw = getArgValue(args, '--check-every');
         const hasCheckEvery = args.includes('--check-every') || checkEveryRaw !== undefined;
         const triggerPromptExtra = getArgValue(args, '--trigger-prompt');
         let checkEveryDurationMs;
-        if (thread) {
+        const runtime = await readBestTaskRuntimeContext();
+        if (thread && runtime?.sessionId) {
             const parsedCheck = parseCheckEveryArgs(checkEveryRaw, hasCheckEvery);
             if ('error' in parsedCheck) {
                 if (formatJson)
@@ -1876,16 +2102,35 @@ Options:
             }
             checkEveryDurationMs = parsedCheck.durationMs;
         }
-        // --return 参数已移除：跨会话 send 不再需要指定返回策略（内部默认 none）。
         // SDK 尚未提供字节进度回调，只展示上传开始和成功完成。
+        const returnPolicyRaw = getArgValue(args, '--return');
+        if (returnPolicyRaw !== undefined && returnPolicyRaw !== 'none' && returnPolicyRaw !== 'required') {
+            console.error('invalid --return; expected none|required');
+            process.exit(1);
+        }
+        const timeoutRaw = getArgValue(args, '--timeout');
+        if (timeoutRaw !== undefined && returnPolicyRaw !== 'required') {
+            console.error('--timeout requires --return required');
+            process.exit(1);
+        }
+        let timeoutMs;
+        if (timeoutRaw !== undefined) {
+            const parsedTimeout = parseDuration(timeoutRaw);
+            if (parsedTimeout === null || parsedTimeout <= 0) {
+                console.error(`invalid --timeout: ${timeoutRaw}`);
+                process.exit(1);
+            }
+            timeoutMs = parsedTimeout;
+        }
         const onUploadProgress = formatJson ? undefined : (info) => {
             if (info.phase === 'upload')
                 process.stderr.write('  ⏫ uploading...\n');
             else if (info.phase === 'done')
                 process.stderr.write('  ✓ upload complete\n');
         };
-        const runtime = await readBestTaskRuntimeContext();
-        const result = await msgSend({ from, to, body, encrypt, thread, handoffContext: getArgValue(args, '--handoff-context'), onUploadProgress, ...commonOpts });
+        // `--thread` 的原文只用于解析；发出的必须是规范 id（历史写法 `<peer>/<id>`
+        // 若原样上线，对端会把它当成一个不存在的话题 id）。
+        const result = await msgSend({ from, to, body, encrypt, thread: thread ? threadTopicId : undefined, returnPolicy: returnPolicyRaw, timeoutMs, handoffContext: getArgValue(args, '--handoff-context'), onUploadProgress, ...commonOpts });
         if (!result.ok) {
             if (formatJson) {
                 console.log(JSON.stringify(result));
@@ -1901,7 +2146,7 @@ Options:
         if (thread && threadEntry && result.message_id && runtime?.sessionId) {
             const effects = await applyCrossThreadSendEffects({
                 selfAid: from,
-                targetThreadId: thread,
+                targetThreadId: threadTopicId,
                 targetSessionId: threadEntry.sessionId,
                 targetChannelId: to,
                 feedbackChatType: 'private',
@@ -1920,7 +2165,10 @@ Options:
         // E4: 把复查 Trigger ID 回填到返回值，兑现 spec §3.4 的 `{ message_id, trigger_id }` 契约。
         if (createdTriggerId)
             result.trigger_id = createdTriggerId;
-        if (formatJson) {
+        if (result.request_id && !formatJson) {
+            console.log(`request_id=${result.request_id} state=${result.request_state ?? '-'} message_id=${result.message_id ?? '-'}`);
+        }
+        else if (formatJson) {
             console.log(JSON.stringify(result));
         }
         else {
@@ -2178,10 +2426,11 @@ Options:
   --encrypt             强制端到端加密（未指定时使用 daemon 默认值；仅 send）
   --no-encrypt          强制明文发送（优先于 --encrypt；仅 send）
   --thread <id>         指定话题 ID（仅 send；话题必须存在于本端索引）
-  --check-every <时长>   跨话题发送（带 --thread）时**必填**，创建周期复查 Trigger（如 5m/30m/2h）
+  --check-every <时长>   跨话题发送（带 --thread）时**必填**，创建跨话题复查（如 5m/30m/2h）
+                        到期向**目标话题**投递【跨话题复查】通知，不新建会话
                         无值时默认 5m；Trigger 名：check-<目标threadId>-from-<来源threadId>-<唯一后缀>
-                        取消/调整用返回的 trigger_id（trig_…），show/update/cancel 只认 id
-  --trigger-prompt <text> 自定义复查 Trigger prompt 中的用户段（仅 --check-every）
+                        结束/调整用返回的 trigger_id（trig_…），show/update/delete 只认 id
+  --trigger-prompt <text> 追加到复查通知正文里的补充说明（仅 --check-every）
   --mention <...>       发送时 @ 某个成员。单引号包住、逗号分隔多个 aid
                         （如 --mention 'alice.agentid.pub,bob.agentid.pub'），可多次传入
   --mention-all         发送时 @ 所有人
@@ -2514,7 +2763,7 @@ g- 是名称的一部分，会完整保留；默认命名格式为 g-10000 至 g
         else if (payloadVal) {
             let parsed;
             try {
-                parsed = JSON.parse(payloadVal);
+                parsed = parseJsonObjectArgument(payloadVal);
             }
             catch (e) {
                 console.error(`❌ --payload 解析失败: ${e.message}`);
@@ -2550,12 +2799,35 @@ g- 是名称的一部分，会完整保留；默认命名格式为 g-10000 至 g
         const groupTriggerPromptExtra = getSendArgValue('--trigger-prompt');
         let groupCheckEveryMs;
         let groupThreadEntry;
+        // 与私聊路径同口径：复查 Trigger 记录规范 id，不记录调用方写的引用原文。
+        let groupTopicId = thread ?? '';
         if (thread) {
-            // 话题必须存在于本端索引（与私聊路径一致，不自动创建）。
+            // 引用必须解析成本端已存在的话题（与私聊路径一致，不自动创建）。
             const { ThreadService } = await import('../core/thread/index.js');
-            groupThreadEntry = ThreadService.findThreadById(from, thread);
-            if (!groupThreadEntry || normalizeGroupAid(groupThreadEntry.peer, from.slice(from.indexOf('.') + 1)) !== groupId) {
-                failManagedGroup(formatJson, 'TOPIC_NOT_FOUND', `话题不存在: ${thread}`);
+            const { resolveThreadRef } = await import('../core/thread/topic-id.js');
+            const resolved = resolveThreadRef(thread, from);
+            if (resolved.kind === 'invalid' || resolved.kind === 'current') {
+                failManagedGroup(formatJson, 'TOPIC_NOT_FOUND', resolved.kind === 'invalid' ? resolved.error : '无效的话题引用');
+            }
+            else if (resolved.kind === 'main') {
+                if (normalizeGroupAid(resolved.peer, from.slice(from.indexOf('.') + 1)) !== groupId) {
+                    failManagedGroup(formatJson, 'TOPIC_NOT_FOUND', `主话题 ${thread} 的对端不是 ${groupId}`);
+                }
+                groupThreadEntry = ThreadService.findMainSessionEntry(from, resolved.peer);
+                if (!groupThreadEntry)
+                    failManagedGroup(formatJson, 'TOPIC_NOT_FOUND', `与 ${resolved.peer} 无主话题会话`);
+                groupTopicId = resolved.topicId;
+            }
+            else {
+                const entry = ThreadService.findThreadById(from, resolved.threadId);
+                const peer = resolved.peer ?? entry?.peer;
+                if (!entry || !peer
+                    || normalizeGroupAid(entry.peer, from.slice(from.indexOf('.') + 1)) !== groupId
+                    || normalizeGroupAid(peer, from.slice(from.indexOf('.') + 1)) !== groupId) {
+                    failManagedGroup(formatJson, 'TOPIC_NOT_FOUND', `话题不存在: ${thread}`);
+                }
+                groupThreadEntry = entry;
+                groupTopicId = resolved.threadId;
             }
             const parsedCheck = parseCheckEveryArgs(groupCheckEveryRaw, groupHasCheckEvery);
             if ('error' in parsedCheck) {
@@ -2569,7 +2841,7 @@ g- 是名称的一部分，会完整保留；默认命名格式为 g-10000 至 g
             body,
             mentions: mentions.length ? mentions : undefined,
             encrypt: encryptGroup,
-            thread,
+            thread: thread ? groupTopicId : undefined,
             ...commonOpts,
         });
         // T2.6: 群聊跨话题发送成功后，同样写入本端 inbox（与私聊路径一致）
@@ -2579,7 +2851,7 @@ g- 是名称的一部分，会完整保留；默认命名格式为 g-10000 至 g
             if (messageId) {
                 const effects = await applyCrossThreadSendEffects({
                     selfAid: from,
-                    targetThreadId: thread,
+                    targetThreadId: groupTopicId,
                     targetSessionId: groupThreadEntry.sessionId,
                     targetChannelId: groupId,
                     feedbackChatType: 'group',
@@ -3123,13 +3395,27 @@ async function runManagedSend(argv, formatJson) {
     if (!result)
         failManagedGroup(formatJson, 'AUN_DAEMON_UNAVAILABLE', 'Unable to connect to the EvolCore daemon');
     if (!result.ok)
-        failManagedGroup(formatJson, result.code ?? 'AUN_SEND_FAILED', result.error ?? 'Send failed');
+        failManagedGroup(formatJson, result.code ?? 'AUN_SEND_FAILED', `${result.error ?? 'Send failed'}${result.request_id ? ` request_id=${result.request_id}` : ''}`, {
+            ...(typeof result.detail_code === 'string' ? { detail_code: result.detail_code } : {}),
+            ...(typeof result.retryable === 'boolean' ? { retryable: result.retryable } : {}),
+            ...(typeof result.sent === 'boolean' ? { sent: result.sent } : {}),
+        });
     if (formatJson)
         console.log(JSON.stringify(result));
     else if (result.handoff_id)
         console.log(`✓ handoff ${result.handoff_id} ${result.status === 'delivered' ? '已投递' : '已排队'} ${result.message_id ?? ''}`.trimEnd());
+    else if (result.request_id)
+        console.log(`sent message_id=${result.message_id ?? '-'} request_id=${result.request_id} state=${result.request_state ?? '-'}`);
     else
         console.log(`✓ 已发送 message_id=${result.message_id ?? '-'} seq=${result.seq ?? result.message?.seq ?? '-'}`);
+    // 复查 Trigger 结果必须可见：消息已发出所以不改退出码（避免调用方重发），
+    // 但没建成要明说，别让调用方以为"N 分钟后会自动复查"。
+    if (!formatJson) {
+        if (result.trigger_id)
+            console.log(`✓ 复查 Trigger ${result.trigger_id}`);
+        else if (result.trigger_error)
+            process.stderr.write(`⚠ 复查 Trigger 未创建: ${result.trigger_error}（消息已发出，需要复查请手动 ec trigger create）\n`);
+    }
 }
 export function resolveManagedSendArgv(argv) {
     if (!['msg', 'group'].includes(argv[0]) || argv[1] !== 'send' || !validSendAid(argv[2]))
@@ -3143,7 +3429,7 @@ export function resolveManagedSendArgv(argv) {
     const booleans = new Set();
     const text = [];
     const mentions = [];
-    const valueFlags = new Set(['--format', '--file', '--payload', '--text-from-file', '--link', '--title', '--description', '--as', '--content-type', '--text', '--transcript', '--thread', '--check-every', '--trigger-prompt', '--return', '--handoff-context', '--mention']);
+    const valueFlags = new Set(['--format', '--file', '--payload', '--text-from-file', '--link', '--title', '--description', '--as', '--content-type', '--text', '--transcript', '--thread', '--check-every', '--trigger-prompt', '--return', '--timeout', '--handoff-context', '--mention', '--self']);
     const booleanFlags = new Set(['--encrypt', '--no-encrypt', '--mention-all']);
     for (let index = 4; index < argv.length; index++) {
         const flag = argv[index];
@@ -3182,9 +3468,28 @@ export function resolveManagedSendArgv(argv) {
     const returnPolicy = values.get('--return');
     if (returnPolicy !== undefined && !['none', 'required'].includes(returnPolicy))
         throw new Error('Invalid return policy');
+    if (scope === 'group' && returnPolicy === 'required')
+        throw new Error('--return required is supported for private msg sends only');
+    const timeoutRaw = values.get('--timeout');
+    if (timeoutRaw !== undefined && returnPolicy !== 'required')
+        throw new Error('--timeout requires --return required');
+    let timeoutMs;
+    if (timeoutRaw !== undefined) {
+        const parsedTimeout = parseDuration(timeoutRaw);
+        if (parsedTimeout === null || parsedTimeout <= 0)
+            throw new Error('Invalid --timeout duration');
+        if (returnPolicy === 'required' && parsedTimeout > 3_600_000)
+            throw new Error('required request timeout cannot exceed 3600s for volatile AUN messages');
+        timeoutMs = parsedTimeout;
+    }
     const handoffContext = values.get('--handoff-context');
     if (handoffContext !== undefined && (scope !== 'msg' || !handoffContext.trim() || handoffContext.length > 65536))
         throw new Error('Invalid private handoff context');
+    // `--self` 在托管发送里只作冗余声明：本端必须就是当前会话的本端。
+    const declaredSelf = values.get('--self')?.replace(/^@/, '');
+    if (declaredSelf !== undefined && declaredSelf !== aid) {
+        throw new Error(`--self ${declaredSelf} 与当前会话本端 ${aid} 不一致`);
+    }
     const thread = values.get('--thread');
     const checkEvery = values.get('--check-every');
     const triggerPromptExtra = values.get('--trigger-prompt');
@@ -3217,9 +3522,7 @@ export function resolveManagedSendArgv(argv) {
         file = { filePath: values.get('--file'), as, contentType: values.get('--content-type'), text: values.get('--text'), transcript: values.get('--transcript') };
     }
     else if (values.has('--payload')) {
-        payload = JSON.parse(values.get('--payload'));
-        if (!payload || typeof payload !== 'object' || Array.isArray(payload))
-            throw new Error('--payload must be a JSON object');
+        payload = parseJsonObjectArgument(values.get('--payload'));
     }
     else if (values.has('--link')) {
         assertEcSingleLine(values.get('--title'), '--title');
@@ -3235,9 +3538,9 @@ export function resolveManagedSendArgv(argv) {
         throw new Error('Attachment options require --file');
     if (booleans.has('--mention-all'))
         mentions.push({ scope: 'all' });
-    return { aid, to, scope, payload, file, textFile: values.get('--text-from-file'),
+    return { aid, to, scope, payload, rawPayload: values.has('--payload'), file, textFile: values.get('--text-from-file'),
         encrypt: booleans.has('--no-encrypt') ? false : booleans.has('--encrypt') ? true : undefined,
-        thread, checkEvery, checkEveryMs: checkEveryMs ?? undefined, triggerPromptExtra, returnPolicy: returnPolicy, handoffContext,
+        thread, checkEvery, checkEveryMs: checkEveryMs ?? undefined, triggerPromptExtra, returnPolicy: returnPolicy, timeoutMs, handoffContext,
         mentions: mentions.length ? mentions : undefined };
 }
 /**
@@ -3259,7 +3562,8 @@ const VALUE_FLAGS = new Set([
     '--as', '--content-type', '--mention', '--visibility', '--join-mode',
     '--group-id', '--name', '--message', '--answer', '--page', '--size',
     '--member-type',
-    '--aun-path', '--thread', '--handoff-context',
+    '--aun-path', '--thread', '--handoff-context', '--self',
+    '--return', '--timeout',
     // 跨话题发送的复查参数：漏登记会让 collectPositional 把它们当正文（正文污染）
     '--check-every', '--trigger-prompt',
 ]);
@@ -3290,17 +3594,6 @@ function collectPositional(args, startIdx, extraValueFlags) {
     }
     return out;
 }
-function parseMsgHistoryTime(value) {
-    const trimmed = value.trim();
-    if (!trimmed)
-        return undefined;
-    if (/^-?\d+$/.test(trimmed)) {
-        const timestamp = Number(trimmed);
-        return Number.isSafeInteger(timestamp) ? timestamp : undefined;
-    }
-    const timestamp = Date.parse(trimmed);
-    return Number.isFinite(timestamp) ? timestamp : undefined;
-}
 /** Resolve a configured channel instance without exposing Agent session paths. */
 function resolveHistoryChannelName(agentAid, channel, requested) {
     if (channel === 'aun' && requested === undefined)