evolcore 0.0.2 → 0.0.3

package/dist/agents/claude-runner.js

@@ -719,7 +719,7 @@ export class AgentRunner {
         if (!permCtx?.adapter || !permCtx?.channelId) {
             return this.handleAskUserQuestionFallback(sessionId, input, questions, options);
         }
-        const adapterHasInteractionPath = !!permCtx.adapter.send;
+        const adapterHasInteractionPath = permCtx.adapter.capabilities?.interaction === true;
         if (!adapterHasInteractionPath || !permCtx.interactionRouter) {
             return this.handleAskUserQuestionFallback(sessionId, input, questions, options);
         }
@@ -756,6 +756,7 @@ export class AgentRunner {
                     },
                     channelId: permCtx.channelId,
                     sessionId,
+                    initiatorId: permCtx.userId,
                 };
             }
             else {
@@ -783,6 +784,7 @@ export class AgentRunner {
                     },
                     channelId: permCtx.channelId,
                     sessionId,
+                    initiatorId: permCtx.userId,
                 };
             }
             let cardSent = false;
@@ -797,7 +799,10 @@ export class AgentRunner {
                     replyContext: permCtx.replyContext,
                 });
                 const optionLines = q.options.map((o, idx) => `  ${idx + 1}. ${o.label}${o.description ? ` — ${o.description}` : ''}`).join('\n');
-                const fallbackText = `💬 ${q.header || q.question}\n${q.header ? q.question + '\n' : ''}${optionLines}`;
+                const answerHint = q.multiSelect
+                    ? '回复 /ask 1,2（多选用逗号分隔），或 /ask <自定义内容>'
+                    : '回复 /ask 1，或 /ask <自定义内容>';
+                const fallbackText = `💬 ${q.header || q.question}\n${q.header ? q.question + '\n' : ''}${optionLines}\n\n${answerHint}`;
                 const result = await sendInteractionPayload(permCtx.adapter, envelope, interaction, fallbackText, permCtx.replyContext);
                 cardSent = !!result;
             }
@@ -958,7 +963,9 @@ export class AgentRunner {
                             command: 'ask',
                             buttonArgMap: Object.fromEntries(q.options.map((_, i) => [`opt-${i}`, String(i + 1)])),
                             acceptFreeText: true,
-                            freeTextHint: '或回复 /ask <自定义内容>',
+                            freeTextHint: q.multiSelect
+                                ? '多选请回复 /ask 1,2；也可回复 /ask <自定义内容>'
+                                : '或回复 /ask <自定义内容>',
                         },
                     };
                     await sendPrompt(renderActionAsText(interaction));
@@ -990,12 +997,25 @@ export class AgentRunner {
                             finish({ kind: 'cancelled', reason: 'aborted' });
                         };
                         permCtx.interactionRouter.register(requestId, sessionId, (action) => {
-                            const num = parseInt(action.trim(), 10);
-                            if (num >= 1 && num <= q.options.length) {
-                                finish({ kind: 'answered', value: q.options[num - 1].label });
+                            const answer = action.trim();
+                            const selectionParts = answer.split(/[,，]/).map(part => part.trim());
+                            const selectedIndexes = selectionParts.map(part => Number(part));
+                            const hasValidNumericSelection = selectionParts.length > 0
+                                && selectionParts.every((part, index) => (/^\d+$/.test(part)
+                                    && Number.isInteger(selectedIndexes[index])
+                                    && selectedIndexes[index] >= 1
+                                    && selectedIndexes[index] <= q.options.length));
+                            if (q.multiSelect && hasValidNumericSelection) {
+                                finish({
+                                    kind: 'answered',
+                                    value: [...new Set(selectedIndexes)].map(num => q.options[num - 1].label),
+                                });
+                            }
+                            else if (!q.multiSelect && hasValidNumericSelection && selectedIndexes.length === 1) {
+                                finish({ kind: 'answered', value: q.options[selectedIndexes[0] - 1].label });
                             }
                             else {
-                                finish({ kind: 'answered', value: action.trim() });
+                                finish({ kind: 'answered', value: answer });
                             }
                         }, {
                             initiatorId: permCtx.userId,
@@ -1181,7 +1201,7 @@ export class AgentRunner {
         };
         // 尝试发送交互卡片
         let cardSent = false;
-        if (permCtx.adapter?.send) {
+        if (permCtx.adapter?.capabilities?.interaction === true) {
             // 发送计划内容：找 plans 目录中最新修改的 .md 文件
             if (sendPrompt) {
                 try {
@@ -1283,10 +1303,20 @@ export class AgentRunner {
      * SDK 原始事件 → 标准 AgentEvent 转换
      * 所有 SDK 特有的事件类型引用封装在此方法内
      */
-    async *transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel) {
+    async *transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, isResuming = false) {
         let lastSessionId;
+        let hasTurnActivity = false;
+        let ignoredPreTurnResult = false;
+        let waitingForBackgroundCompletion = false;
+        let liveBackgroundTasks = new Set();
+        const unsettledTasks = new Set();
+        const terminalTasks = new Set();
+        const ambientTasks = new Set();
+        const awaitedTaskNotifications = new Set();
+        const taskMetadata = new Map();
         // tool_use_id → tool_name 映射，用于从 SDKUserMessage 的 tool_result 块中还原工具名
         const toolUseNames = new Map();
+        const emittedToolResultIds = new Set();
         let turnCount = 0;
         const seenMessageIds = new Set();
         let lastModelCall;
@@ -1302,11 +1332,99 @@ export class AgentRunner {
                     yield { type: 'session_id', sessionId: event.session_id };
                 }
                 if (event.type === 'user' && event.uuid === inputId) {
+                    hasTurnActivity = true;
                     yield { type: 'input_accepted', inputId };
                 }
+                if (event.type === 'system' && event.subtype === 'task_started' && typeof event.task_id === 'string') {
+                    const taskKind = event.subagent_type || event.task_type === 'remote_agent'
+                        ? 'agent'
+                        : event.workflow_name || event.task_type === 'local_workflow'
+                            ? 'workflow'
+                            : 'background';
+                    taskMetadata.set(event.task_id, {
+                        taskKind,
+                        description: event.description,
+                        subagentType: event.subagent_type,
+                        taskType: event.task_type,
+                    });
+                    if (event.skip_transcript === true) {
+                        ambientTasks.add(event.task_id);
+                        unsettledTasks.delete(event.task_id);
+                        liveBackgroundTasks.delete(event.task_id);
+                    }
+                    else if (!terminalTasks.has(event.task_id)) {
+                        unsettledTasks.add(event.task_id);
+                        hasTurnActivity = true;
+                    }
+                    yield {
+                        type: 'task_started',
+                        taskId: event.task_id,
+                        taskKind,
+                        toolUseId: event.tool_use_id,
+                        description: event.description || event.task_id,
+                        subagentType: event.subagent_type,
+                        taskType: event.task_type,
+                        workflowName: event.workflow_name,
+                        prompt: event.prompt,
+                        skipTranscript: event.skip_transcript,
+                    };
+                    continue;
+                }
+                if (event.type === 'system' && event.subtype === 'background_tasks_changed') {
+                    const tasks = Array.isArray(event.tasks) ? event.tasks : [];
+                    liveBackgroundTasks = new Set(tasks
+                        .map((task) => task?.task_id)
+                        .filter((taskId) => (typeof taskId === 'string'
+                        && !terminalTasks.has(taskId)
+                        && !ambientTasks.has(taskId))));
+                    yield {
+                        type: 'background_tasks_changed',
+                        tasks: tasks.map((task) => ({
+                            taskId: task.task_id,
+                            taskKind: task.task_type === 'remote_agent'
+                                ? 'agent'
+                                : task.task_type === 'local_workflow'
+                                    ? 'workflow'
+                                    : taskMetadata.get(task.task_id)?.taskKind || 'background',
+                            taskType: task.task_type,
+                            description: task.description,
+                        })),
+                    };
+                    continue;
+                }
+                if (event.type === 'system' && event.subtype === 'task_notification' && typeof event.task_id === 'string') {
+                    const metadata = taskMetadata.get(event.task_id);
+                    const taskKind = metadata?.taskKind
+                        || (event.tool_use_id && toolUseNames.get(event.tool_use_id) === 'Agent' ? 'agent' : undefined)
+                        || (typeof event.summary === 'string' && /^Agent\b/.test(event.summary) ? 'agent' : 'background');
+                    terminalTasks.add(event.task_id);
+                    ambientTasks.delete(event.task_id);
+                    unsettledTasks.delete(event.task_id);
+                    liveBackgroundTasks.delete(event.task_id);
+                    awaitedTaskNotifications.delete(event.task_id);
+                    yield {
+                        type: 'task_notification',
+                        taskId: event.task_id,
+                        taskKind,
+                        toolUseId: event.tool_use_id,
+                        description: metadata?.description,
+                        subagentType: metadata?.subagentType,
+                        status: event.status || 'completed',
+                        outputFile: event.output_file,
+                        summary: event.summary,
+                        usage: event.usage ? {
+                            totalTokens: event.usage.total_tokens,
+                            toolUses: event.usage.tool_uses,
+                            durationMs: event.usage.duration_ms,
+                        } : undefined,
+                        skipTranscript: event.skip_transcript,
+                    };
+                    continue;
+                }
                 if (event.type === 'stream_event') {
                     const streamEvent = event.event;
                     if (streamEvent?.type === 'message_start' && streamEvent.message?.usage) {
+                        hasTurnActivity = true;
                         lastModelCall = {
                             uuid: event.uuid,
                             model: streamEvent.message.model,
@@ -1347,11 +1465,21 @@ export class AgentRunner {
                 }
                 // system: task_progress → task_progress
                 if (event.type === 'system' && event.subtype === 'task_progress') {
+                    const metadata = typeof event.task_id === 'string' ? taskMetadata.get(event.task_id) : undefined;
+                    if (!event.task_id || !ambientTasks.has(event.task_id))
+                        hasTurnActivity = true;
                     yield {
                         type: 'task_progress',
+                        taskId: event.task_id,
+                        taskKind: metadata?.taskKind || (event.subagent_type ? 'agent' : undefined),
+                        toolUseId: event.tool_use_id,
+                        description: event.description,
+                        subagentType: event.subagent_type || metadata?.subagentType,
                         summary: event.summary,
-                        toolUses: event.tool_uses,
-                        durationMs: event.duration_ms,
+                        lastToolName: event.last_tool_name,
+                        totalTokens: event.usage?.total_tokens,
+                        toolUses: event.usage?.tool_uses ?? event.tool_uses,
+                        durationMs: event.usage?.duration_ms ?? event.duration_ms,
                     };
                 }
                 // system: session_state_changed → state_changed
@@ -1360,6 +1488,7 @@ export class AgentRunner {
                 }
                 // assistant: 提取 tool_use 和文本（仅无 text_delta 时提取文本）
                 if (event.type === 'assistant' && event.message?.content) {
+                    hasTurnActivity = true;
                     lastAssistantUuid = event.uuid ?? lastAssistantUuid;
                     const msgId = event.message.id;
                     if (!msgId || !seenMessageIds.has(msgId)) {
@@ -1410,6 +1539,8 @@ export class AgentRunner {
                             const resultContent = typeof block.content === 'string'
                                 ? block.content
                                 : block.content != null ? JSON.stringify(block.content) : '';
+                            if (block.tool_use_id)
+                                emittedToolResultIds.add(block.tool_use_id);
                             yield {
                                 type: 'tool_result',
                                 name: toolName,
@@ -1423,15 +1554,22 @@ export class AgentRunner {
                 }
                 // result → complete（含 permission_denials 提取）
                 if (event.type === 'result') {
-                    // 先发出被拒绝的权限事件
+                    // Most SDK streams surface denials as user-message tool_result blocks.
+                    // The terminal summary is only a fallback for incomplete streams.
                     if (Array.isArray(event.permission_denials)) {
                         for (const denial of event.permission_denials) {
+                            const callId = typeof denial.tool_use_id === 'string' ? denial.tool_use_id : undefined;
+                            if (callId && emittedToolResultIds.has(callId))
+                                continue;
+                            if (callId)
+                                emittedToolResultIds.add(callId);
                             yield {
                                 type: 'tool_result',
                                 name: denial.tool_name || '',
                                 result: '',
                                 isError: true,
-                                error: `权限被拒绝: ${denial.tool_name}`,
+                                error: `权限被拒绝: ${denial.tool_name || 'unknown tool'}`,
+                                callId,
                             };
                         }
                     }
@@ -1502,7 +1640,7 @@ export class AgentRunner {
                         // 降级：无逐次数据，写一条累计行
                         modelCalls = [{ call_index: 0, model: callModel_, tokenUsage: u, contextUsage: contextUsageForCall(u), degraded: true }];
                     }
-                    yield {
+                    const completeEvent = {
                         type: 'complete',
                         result: cleanResult,
                         subtype: event.subtype,
@@ -1520,10 +1658,53 @@ export class AgentRunner {
                         modelCalls,
                         assistantUuid: lastAssistantUuid,
                     };
-                    // result 是 SDK 流的终结事件，不再等待后续（防止 interrupt 后流不关闭导致挂起）
+                    // Fatal results belong to the query transport itself and must terminate
+                    // even when the current input was not echoed back by the CLI.
+                    if (event.is_error) {
+                        yield { ...completeEvent, queryFinal: true };
+                        return;
+                    }
+                    if (isResuming && !hasTurnActivity && !ignoredPreTurnResult) {
+                        ignoredPreTurnResult = true;
+                        logger.info(`[AgentRunner] Ignoring pre-turn result while resuming session=${sessionId} input=${inputId}`);
+                        continue;
+                    }
+                    const hasLiveTasks = liveBackgroundTasks.size > 0 || unsettledTasks.size > 0;
+                    if (hasLiveTasks) {
+                        waitingForBackgroundCompletion = true;
+                        for (const taskId of liveBackgroundTasks)
+                            awaitedTaskNotifications.add(taskId);
+                        for (const taskId of unsettledTasks)
+                            awaitedTaskNotifications.add(taskId);
+                        yield { ...completeEvent, queryFinal: false };
+                        hasTurnActivity = false;
+                        ignoredPreTurnResult = false;
+                        continue;
+                    }
+                    // background_tasks_changed may report an empty set before the matching
+                    // task_notification. Do not close in that gap: the notification wakes the
+                    // parent agent for the final synthesis turn.
+                    if (waitingForBackgroundCompletion && awaitedTaskNotifications.size > 0) {
+                        yield { ...completeEvent, queryFinal: false };
+                        hasTurnActivity = false;
+                        ignoredPreTurnResult = false;
+                        continue;
+                    }
+                    yield { ...completeEvent, queryFinal: true };
                     return;
                 }
             }
+            if (waitingForBackgroundCompletion) {
+                yield {
+                    type: 'complete',
+                    isError: true,
+                    subtype: 'protocol_incomplete',
+                    terminalReason: 'background_tasks_incomplete',
+                    protocolIncompleteReason: 'background_tasks_incomplete',
+                    errors: ['Claude SDK stream ended before background tasks produced a final parent result'],
+                    queryFinal: true,
+                };
+            }
         }
         catch (err) {
             // 子进程崩溃（如 exited with code 1）时，把缓冲的 stderr 打出来还原真实原因。
@@ -2107,7 +2288,6 @@ export class AgentRunner {
             logger.info('[AgentRunner] Creating query with images:', images.length, 'first image size:', images[0]?.data?.length ?? 0);
             logger.debug('[AgentRunner] Skipping resume for image message to avoid history conflict');
             msgStream.push(prompt, images, inputId);
-            msgStream.end();
             sdkStream = createQuery(msgStream);
         }
         else {
@@ -2124,7 +2304,7 @@ export class AgentRunner {
             this.interruptFns.set(sessionId, () => sdkStream.interrupt());
         }
         // 返回标准 AgentEvent 流（重试由 MessageProcessor 层负责）
-        const transformed = this.transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel);
+        const transformed = this.transformStream(sdkStream, sessionId, inputId, callModel, callEffort, sdkModel, !!agentSessionId);
         const self = this;
         return (async function* () {
             try {

package/dist/agents/codex-runner.js

@@ -704,11 +704,13 @@ export class CodexRunner {
         controller.signal.addEventListener('abort', () => queue.end(), { once: true });
         const state = {
             threadId,
+            model: callModel,
             streamedAgentMessageIds: new Set(),
             agentMessageDeltaText: new Map(),
             completedItemIds: new Set(),
             emittedEditCallIds: new Set(),
             completedTurnIds: new Set(),
+            openToolCalls: new Map(),
         };
         const unsubscribe = appServer.onNotification(notification => {
             // 仅从 turn/started 锁定权威 turnId — resume 时会有上一轮 turn 的残留通知
@@ -2083,7 +2085,10 @@ export class CodexRunner {
                 break;
             }
             case 'item/started': {
-                yield* this.mapAppServerItemStarted(params.item, state);
+                for (const event of this.mapAppServerItemStarted(params.item, state)) {
+                    this.trackAppServerToolLifecycle(event, state);
+                    yield event;
+                }
                 break;
             }
             case 'item/agentMessage/delta': {
@@ -2099,11 +2104,17 @@ export class CodexRunner {
                 const item = params.item;
                 if (item?.id)
                     state.completedItemIds.add(item.id);
-                yield* this.mapAppServerItemCompleted(item, state);
+                for (const event of this.mapAppServerItemCompleted(item, state)) {
+                    this.trackAppServerToolLifecycle(event, state);
+                    yield event;
+                }
                 break;
             }
             case 'item/fileChange/patchUpdated': {
-                yield* this.mapAppServerFileChangePatchUpdated(params, state);
+                for (const event of this.mapAppServerFileChangePatchUpdated(params, state)) {
+                    this.trackAppServerToolLifecycle(event, state);
+                    yield event;
+                }
                 break;
             }
             case 'turn/plan/updated': {
@@ -2131,6 +2142,7 @@ export class CodexRunner {
                 if (turnId)
                     state.completedTurnIds.add(turnId);
                 this.activeTurns.delete(sessionId);
+                yield* this.reconcileOpenAppServerToolCalls(state, turnId);
                 if (turn.status === 'failed' && turn.error?.message) {
                     if (isRetryableError(new Error(turn.error.message))) {
                         throw new Error(turn.error.message);
@@ -2154,6 +2166,36 @@ export class CodexRunner {
             }
         }
     }
+    trackAppServerToolLifecycle(event, state) {
+        if (event.type !== 'tool_use' && event.type !== 'tool_result')
+            return;
+        if (!event.callId)
+            return;
+        if (event.type === 'tool_use') {
+            state.openToolCalls.set(event.callId, event.name);
+        }
+        else if (event.type === 'tool_result') {
+            state.openToolCalls.delete(event.callId);
+        }
+    }
+    *reconcileOpenAppServerToolCalls(state, turnId) {
+        if (state.openToolCalls.size === 0)
+            return;
+        const callIds = [...state.openToolCalls.keys()];
+        logger.warn(`[CodexRunner] Turn completed with ${callIds.length} open tool call(s): ` +
+            `thread=${state.threadId} turn=${turnId || state.turnId || 'unknown'} calls=${callIds.join(',')}`);
+        for (const [callId, name] of state.openToolCalls) {
+            yield {
+                type: 'tool_result',
+                name,
+                result: '',
+                isError: true,
+                error: 'Codex app-server ended the turn without an item/completed notification',
+                callId,
+            };
+        }
+        state.openToolCalls.clear();
+    }
     *mapAppServerItemStarted(item, state) {
         if (!item)
             return;
@@ -2458,6 +2500,7 @@ export class CodexRunner {
             costUsd: this.pickNumber(turn.costUsd, turn.totalCostUsd, turn.total_cost_usd),
             sessionTitle: typeof turn.sessionTitle === 'string' ? turn.sessionTitle : typeof turn.session_title === 'string' ? turn.session_title : undefined,
             numTurns: this.pickNumber(turn.numTurns, turn.num_turns),
+            model: state.model,
             tokenUsage,
             contextUsage,
         };

package/dist/aun/outbox.js

@@ -158,3 +158,11 @@ export function hasPending(aid) {
         return false;
     }
 }
+/**
+ * 当前 outbox 中待发送条目数。用于诊断发送管线堵塞：depth 持续增长说明
+ * message.send 出队速度跟不上入队速度（网关慢 / 链路抖动 / 卡片洪泛），
+ * 是命令「回复慢/无回复」的先行指标。
+ */
+export function pendingCount(aid) {
+    return load(aid).length;
+}

package/dist/channels/aun.js

@@ -195,25 +195,37 @@ export class AUNChannel {
      */
     async callAndTrace(method, params, opts) {
         this.trace('OUT', method, params);
+        // RPC 往返计时：区分「网关慢」与「本地队列堵塞」。message.send/group.send 的
+        // duration 若普遍逼近 SDK 的 rpc 超时（默认 10s），说明发送管线已饱和或链路抖动，
+        // 是 /evolhelp 等命令「回复慢/无回复」的直接可观测信号。
+        const rpcStart = Date.now();
+        // SLOW_RPC_WARN_MS 需明显低于 SDK 默认 10s 超时，以便在真正超时前提前告警。
+        const SLOW_RPC_WARN_MS = 3000;
         try {
             const result = await this.client.call(method, params);
+            const durationMs = Date.now() - rpcStart;
             if (!opts?.silentOk) {
                 const r = result;
                 const snap = r && typeof r === 'object'
-                    ? { message_id: r.message_id, ok: r.ok, thought_id: r.thought_id }
-                    : undefined;
-                this.trace('OUT', `${method}.ok`, snap ?? {});
+                    ? { message_id: r.message_id, ok: r.ok, thought_id: r.thought_id, duration_ms: durationMs }
+                    : { duration_ms: durationMs };
+                this.trace('OUT', `${method}.ok`, snap);
+            }
+            if (durationMs >= SLOW_RPC_WARN_MS) {
+                logger.warn(`${this.logPrefix()} rpc ${method} SLOW: duration=${durationMs}ms (发送管线可能饱和或链路抖动)`);
             }
             return result;
         }
         catch (e) {
+            const durationMs = Date.now() - rpcStart;
             this.trace('OUT', `${method}.error`, {
                 error: e?.message ?? String(e),
                 code: e?.code,
                 name: e?.name,
+                duration_ms: durationMs,
             });
             if (!opts?.silentError) {
-                logger.warn(`${this.logPrefix()} rpc ${method} failed: ${e?.name ?? ''}(${e?.code ?? ''}) ${e?.message ?? e}`);
+                logger.warn(`${this.logPrefix()} rpc ${method} failed after ${durationMs}ms: ${e?.name ?? ''}(${e?.code ?? ''}) ${e?.message ?? e}`);
             }
             throw e;
         }
@@ -2752,6 +2764,11 @@ EvolCore AI Agent 网关，支持多项目会话管理和多 AI 后端切换。
             context,
         });
         logger.debug(`${this.logPrefix()} Outbox enqueued: id=${entry.id} channel=${channelId} text=${finalText.slice(0, 40)}`);
+        // 积压深度告警：outbox 待发条目累积说明发送速度跟不上，回复将出现明显延迟。
+        const backlog = outbox.pendingCount(this.config.aid);
+        if (backlog >= 5) {
+            logger.warn(`${this.logPrefix()} Outbox backlog=${backlog} channel=${channelId} (发送管线堵塞，回复将延迟)`);
+        }
         if (!this.connected || !this.client) {
             logger.warn(`${this.logPrefix()} Not connected, message queued in outbox (id=${entry.id}). Triggering reconnect.`);
             if (!this.reconnectTimer && !this.client) {

package/dist/channels/contact-bind-code.js

@@ -0,0 +1,134 @@
+import { randomInt } from 'crypto';
+import { isValidAid } from '../aun/aid/validation.js';
+import { bindContactAlias } from '../config/contact-book.js';
+export const CONTACT_BIND_CODE_TTL_MS = 10 * 60 * 1000;
+export const CONTACT_BIND_MAX_FAILED_ATTEMPTS = 5;
+/** In-memory, one-time channel identity proof used before writing a Contact alias. */
+export class ContactBindCodeRegistry {
+    options;
+    pending = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    register(req) {
+        const selfAid = String(req.selfAid || '').trim();
+        const channelName = String(req.channelName || '').trim();
+        const primaryId = String(req.primaryId || '').trim();
+        const now = req.now ?? Date.now();
+        const code = req.code ? String(req.code).trim() : generateBindCode();
+        if (!isValidAid(selfAid))
+            return { ok: false, error: `invalid selfAid: ${req.selfAid}` };
+        if (!channelName)
+            return { ok: false, error: 'missing channelName' };
+        if (!isValidAid(primaryId))
+            return { ok: false, error: `invalid primaryId: ${req.primaryId}` };
+        if (!/^\d{6}$/.test(code))
+            return { ok: false, error: 'binding code must be 6 digits' };
+        const key = pendingBindKey(selfAid, channelName);
+        const replaced = this.pending.has(key);
+        const item = {
+            selfAid,
+            channelName,
+            primaryId,
+            code,
+            createdAt: now,
+            expiresAt: now + CONTACT_BIND_CODE_TTL_MS,
+            failedAttempts: 0,
+            maxFailedAttempts: CONTACT_BIND_MAX_FAILED_ATTEMPTS,
+        };
+        this.pending.set(key, item);
+        return { ok: true, code, expiresAt: item.expiresAt, replaced };
+    }
+    handle(ctx) {
+        if (ctx.channelType !== this.options.channelType)
+            return { handled: false };
+        const selfAid = String(ctx.selfAid || '').trim();
+        const channelName = String(ctx.channelName || '').trim();
+        if (!selfAid || !channelName)
+            return { handled: false };
+        const key = pendingBindKey(selfAid, channelName);
+        const item = this.pending.get(key);
+        if (!item)
+            return { handled: false };
+        const now = ctx.now ?? Date.now();
+        if (now >= item.expiresAt) {
+            this.pending.delete(key);
+            return {
+                handled: true,
+                status: 'expired',
+                remainingAttempts: 0,
+                reply: `${this.options.displayName}身份绑定码已超时，本次绑定失败。请重新执行 ${this.options.initCommand} 并再次绑定。`,
+            };
+        }
+        if (ctx.chatType !== 'private')
+            return { handled: false };
+        const input = String(ctx.content ?? '').trim();
+        if (!/^\d{6}$/.test(input)) {
+            return {
+                handled: true,
+                status: 'format',
+                reply: '请直接发送 6 位数字绑定码。',
+                remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
+            };
+        }
+        if (input !== item.code) {
+            item.failedAttempts += 1;
+            const remaining = Math.max(0, item.maxFailedAttempts - item.failedAttempts);
+            if (remaining === 0) {
+                this.pending.delete(key);
+                return {
+                    handled: true,
+                    status: 'failed',
+                    remainingAttempts: 0,
+                    reply: `绑定码无效，本次${this.options.displayName}身份绑定失败。请重新执行 ${this.options.initCommand} 并再次绑定。`,
+                };
+            }
+            return {
+                handled: true,
+                status: 'wrong-code',
+                remainingAttempts: remaining,
+                reply: '绑定码错误，请重新发送 6 位数字绑定码。',
+            };
+        }
+        const actorId = String(ctx.actorId || '').trim();
+        if (!actorId) {
+            return {
+                handled: true,
+                status: 'missing-actor',
+                remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
+                reply: `无法识别当前${this.options.displayName}发送者身份，未建立绑定。请重新发送绑定码或重新执行绑定流程。`,
+            };
+        }
+        try {
+            bindContactAlias(item.selfAid, item.primaryId, this.options.channelType, actorId, item.channelName);
+            this.pending.delete(key);
+            return {
+                handled: true,
+                status: 'bound',
+                reply: `${this.options.displayName}身份绑定成功：${item.channelName}:${encodeURIComponent(actorId)} -> ${item.primaryId}`,
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                handled: true,
+                status: 'write-failed',
+                remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
+                reply: `${this.options.displayName}身份绑定写入失败：${message}`,
+            };
+        }
+    }
+    get(selfAid, channelName) {
+        const item = this.pending.get(pendingBindKey(selfAid, channelName));
+        return item ? { ...item } : null;
+    }
+    clear() {
+        this.pending.clear();
+    }
+}
+function generateBindCode() {
+    return String(randomInt(0, 1_000_000)).padStart(6, '0');
+}
+function pendingBindKey(selfAid, channelName) {
+    return `${String(selfAid || '').trim()}\u0000${String(channelName || '').trim()}`;
+}