minimal-agent 0.8.2 → 0.10.0

package/src/ui/hooks/askSlot.js

@@ -0,0 +1,82 @@
+/**
+ * ============================================================
+ *  src/ui/hooks/askSlot.ts —— TUI 的 AskUserQuestion 单槽状态机
+ * ------------------------------------------------------------
+ *  从 useChat 抽出的纯函数工厂（仿 LiveArea 的 buildLiveView 先例：
+ *  React hook 闭包没法单测，抽成纯函数才能给真实事故上回归锚）。
+ *
+ *  单槽的依据：工具 isConcurrencySafe:false + workflow 串行 →
+ *  同一时刻至多一个 pending 提问。
+ *
+ *  ⚠️ 归属校验（`current !== me` 早退）是本模块的核心防线：
+ *  同一轮里模型可以**先后**多次 AskUserQuestion，它们共享同一个 turn
+ *  AbortSignal——每次提问都在 signal 上挂一个 {once:true} 的 abort
+ *  监听器，已答完提问的监听器**不会消失**。中断时监听器按注册顺序全部
+ *  触发：若不校验「槽位是否还归我」，第 1 问的监听器会抢先把属于第 2 问
+ *  的槽清掉，第 2 问的监听器再看到空槽早退 → 第 2 问的 promise 永不落定
+ *  → 工具 await 挂死 → 整轮死锁只能杀进程（真实事故，
+ *  test/askSlot.test.ts「同轮两问」场景锁定）。
+ * ============================================================
+ */
+import { dlog } from '../../utils/debugLog.js';
+/**
+ * @param onPendingChange 槽位变化回调：questions = 有待答题目（宿主该弹界面），
+ *                        null = 槽已清（该收界面）。source 描述提问来源（子任务提问时
+ *                        kind:'subagent' + description），供 UI 显示「子任务：X」徽标。
+ *                        TUI 用它同时驱动 setPendingAsk + setPendingAskSource。
+ */
+export function createAskSlot(onPendingChange) {
+    let current = null;
+    const handler = (questions, signal, source, control) => new Promise((resolve, reject) => {
+        current?.cleanup();
+        current?.reject(new Error('被新的提问取代'));
+        const onAbort = () => {
+            if (current !== me)
+                return;
+            me.cleanup();
+            current = null;
+            onPendingChange(null);
+            reject(new DOMException('已被用户中断', 'AbortError'));
+        };
+        const me = {
+            resolve,
+            reject,
+            source,
+            control,
+            cleanup: () => signal?.removeEventListener('abort', onAbort),
+        };
+        current = me;
+        dlog('ui', 'ask handler INVOKED (等待用户答题)', {
+            n: questions.length,
+            headers: questions.map((q) => q.header),
+            source: source?.kind,
+        });
+        onPendingChange(questions, source);
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+    const answer = (answers) => {
+        const r = current;
+        current = null;
+        if (!r)
+            return; // abort 已清槽后用户又确认：空操作，无双落定
+        r.cleanup();
+        onPendingChange(null);
+        dlog('ui', 'ask ANSWERED (继续执行)', { selected: answers.map((a) => a.selected) });
+        r.resolve(answers);
+    };
+    const cancel = () => {
+        const r = current;
+        current = null;
+        if (!r)
+            return;
+        r.cleanup();
+        r.control?.cancelSource();
+        onPendingChange(null);
+        r.reject(new DOMException(r.source?.kind === 'subagent' ? 'subagent cancelled by owner' : 'ask cancelled by user', 'AbortError'));
+    };
+    return { handler, answer, cancel };
+}