evolcore 0.0.28 → 0.0.29

package/dist/core/message/pending-hints.js

@@ -1,190 +1,356 @@
-// 观察者插话：待用提示（pending-hints）存储。
-//
-// owner 经 observer.inject 给「agent↔对端」会话预埋的提示，落盘为 append-only jsonl，
-// 在下一条对端消息到达、渲染该轮 prompt 时一次性消费、注入渲染层。
-// 详见 docs/observer-insert-design.md 第一部分（§1.3 文件生命周期 / §1.4 thread 作用域）。
-//
-// 文件：agents/<selfAID>/sessions/<channelSessionKey>/pending-hints.jsonl（与 messages.jsonl 同级）
-// 每行一个事件：
-//   { action:'add',    id, text, threadId, ownerAid, ts }
-//   { action:'remove', targetId?, threadId, ts }   // 无 targetId = 撤该 thread 全部
-//
-// 生命周期 = 一个消费周期（按 (对端,thread) 维度）：
-//   - add/remove 追加行（append-only，处理「加了又撤」的竞态：按时间序回放抵消）
-//   - consume（对端消息到达触发）：回放算「该 thread」有效集 → 返回 → 清掉该 thread 的事件。
-//     · 若文件里其它 thread 仍有未消费提示 → 重写文件只留它们（不误删别的 thread）。
-//     · 否则（无其它 thread 残留）→ 删整个文件。
-//   - 因为 consume 一次性用掉该 thread 的全部有效提示，消费后该 thread 有效集必然归零，
-//     未来状态不依赖消费前历史，故消费即清安全，无需 consume 事件行。
-//   - 任何让「整文件」有效集归零的操作都删文件：consume 后无残留即删；remove 把提示全撤光也删。
+// Observer insert hint storage and protocol parsing.
+// Durable events remain pending until a successful claim is committed. Claims
+// are process-local so a crash leaves the durable hint available for retry.
 import fs from 'fs';
 import path from 'path';
-import { chatDirPath, appendJsonl, readAllJsonlLines } from '../session/session-fs-store.js';
+import crypto from 'crypto';
+import { chatDirPath, appendJsonl, readAllJsonlLines, scanChatDirs } from '../session/session-fs-store.js';
 import { logger } from '../../utils/logger.js';
 const PENDING_HINTS_FILE = 'pending-hints.jsonl';
-function hintsPath(sessionsDir, channelType, channelId, selfAID) {
-    return path.join(chatDirPath(sessionsDir, channelType, channelId, selfAID), PENDING_HINTS_FILE);
+export const OBSERVER_HINT_FAILURE_MESSAGES = {
+    SESSION_NOT_FOUND: '目标 Agent session 不存在',
+    INTERRUPT_FAILED: 'Agent 当前任务中断失败',
+    INTERRUPT_TIMEOUT: '等待 Agent 当前任务中断超时',
+    QUEUE_FAILED: 'Agent 任务队列不可用',
+    QUEUE_PERSIST_FAILED: '提示入队失败',
+    RENDER_FAILED: '提示内容组装失败',
+    RUNNER_START_FAILED: 'Agent runner 启动失败',
+    RUNNER_START_SUPERSEDED: '提示启动时已被新的任务取代',
+    HINT_UNAVAILABLE: '提示已不可用',
+};
+const targetLocks = new Map();
+const claimedHints = new Map();
+let claimSequence = 0;
+function hintsPath(sessionsDir, channelType, channelId, selfAID, channelKey) {
+    return path.join(chatDirPath(sessionsDir, channelType, channelId, selfAID, channelKey), PENDING_HINTS_FILE);
 }
-/** 归一 threadId：undefined/null → ''（主线程）。 */
 function normThread(threadId) {
     return threadId || '';
 }
-/**
- * 追加一条 add 事件。返回是否写盘成功（供 ack 判定）。
- * 写盘成功后才回 ack(accepted)——accepted 真正代表"已持久保存"。
- */
-export function appendHintAdd(sessionsDir, channelType, channelId, selfAID, hint) {
+function normChatType(chatType) {
+    return chatType === 'group' ? 'group' : 'private';
+}
+function eventChatType(event) {
+    return normChatType(event.chatType);
+}
+function eventMode(event) {
+    return event.mode === 'interrupt' ? 'interrupt' : 'next';
+}
+function targetKey(sessionsDir, channelType, channelId, selfAID, chatType, threadId, channelKey) {
+    return [sessionsDir, channelType, channelId, selfAID, channelKey || '', chatType, normThread(threadId)].join('\u0000');
+}
+/** Serialize all operations for one target conversation/thread. */
+export async function withHintTargetLock(sessionsDir, channelType, channelId, selfAID, chatType, threadId, fn, channelKey) {
+    const key = targetKey(sessionsDir, channelType, channelId, selfAID, chatType, threadId, channelKey);
+    const previous = targetLocks.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise(resolve => { release = resolve; });
+    targetLocks.set(key, current);
+    await previous.catch(() => undefined);
     try {
-        const fp = hintsPath(sessionsDir, channelType, channelId, selfAID);
-        fs.mkdirSync(path.dirname(fp), { recursive: true });
-        const ev = {
-            action: 'add', id: hint.id, text: hint.text,
-            threadId: normThread(hint.threadId), ownerAid: hint.ownerAid, ts: hint.ts,
-        };
-        appendJsonl(fp, ev);
-        return true;
+        return await fn();
     }
-    catch (e) {
-        logger.warn(`[PendingHints] appendHintAdd failed: ${e instanceof Error ? e.message : String(e)}`);
-        return false;
+    finally {
+        release();
+        if (targetLocks.get(key) === current)
+            targetLocks.delete(key);
     }
 }
-/**
- * 追加一条 remove 事件。若该操作使 (对端,thread) 有效集归零，则删除整个文件。
- * 返回是否写盘成功（供 ack 判定）。
- */
-export function appendHintRemove(sessionsDir, channelType, channelId, selfAID, rm) {
+function readEvents(fp) {
     try {
-        const fp = hintsPath(sessionsDir, channelType, channelId, selfAID);
-        if (!fs.existsSync(fp))
-            return true; // 无文件 = 无可撤，幂等成功
-        fs.mkdirSync(path.dirname(fp), { recursive: true });
-        const ev = {
-            action: 'remove', threadId: normThread(rm.threadId), ts: rm.ts,
-            ...(rm.targetId ? { targetId: rm.targetId } : {}),
-        };
-        appendJsonl(fp, ev);
-        // 撤销后：若全部 thread 的有效集都归零，删文件（不堆死文件）。
-        if (!hasAnyEffective(fp))
-            deleteFile(fp);
-        return true;
+        return fs.existsSync(fp) ? readAllJsonlLines(fp) : [];
     }
-    catch (e) {
-        logger.warn(`[PendingHints] appendHintRemove failed: ${e instanceof Error ? e.message : String(e)}`);
-        return false;
+    catch (error) {
+        logger.warn(`[PendingHints] read failed: ${error instanceof Error ? error.message : String(error)}`);
+        throw error;
     }
 }
-/** 回放整个文件，返回是否还存在任意 thread 的有效提示。 */
-function hasAnyEffective(fp) {
-    const events = readAllJsonlLines(fp);
-    // 按 thread 分组回放
-    const byThread = new Map();
+function replayEffective(events) {
+    const active = new Map();
     for (const ev of events) {
-        const t = normThread(ev.threadId);
-        (byThread.get(t) ?? byThread.set(t, []).get(t)).push(ev);
+        if (ev.action === 'add') {
+            active.set(ev.id, {
+                id: ev.id,
+                text: ev.text,
+                ownerAid: ev.ownerAid,
+                ts: ev.ts,
+                mode: eventMode(ev),
+                chatType: eventChatType(ev),
+                threadId: normThread(ev.threadId),
+            });
+        }
+        else if (ev.action === 'promote') {
+            const current = active.get(ev.targetId);
+            if (current)
+                active.set(ev.targetId, {
+                    ...current,
+                    mode: 'interrupt',
+                    ...(ev.requestId ? { promoteRequestId: ev.requestId } : {}),
+                });
+        }
+        else if (ev.targetId) {
+            active.delete(ev.targetId);
+        }
+        else {
+            active.clear();
+        }
     }
-    for (const [, evs] of byThread) {
-        if (replayEffective(evs).length > 0)
+    return [...active.values()].sort((a, b) => a.ts - b.ts);
+}
+function effectiveFor(events, chatType, threadId) {
+    return replayEffective(events.filter(ev => eventChatType(ev) === chatType && normThread(ev.threadId) === threadId));
+}
+function hasAnyEffective(events) {
+    const keys = new Set(events.map(ev => `${eventChatType(ev)}\u0000${normThread(ev.threadId)}`));
+    for (const key of keys) {
+        const [chatType, threadId] = key.split('\u0000');
+        if (effectiveFor(events, chatType, threadId).length > 0)
             return true;
     }
     return false;
 }
-/** 对单个 thread 的事件序列回放，算出有效提示集（已 add、未被 remove，按 ts 升序）。 */
-function replayEffective(events) {
-    const sorted = events.slice().sort((a, b) => a.ts - b.ts);
-    const active = new Map(); // id → hint，保插入序
-    for (const ev of sorted) {
-        if (ev.action === 'add') {
-            active.set(ev.id, { id: ev.id, text: ev.text, ownerAid: ev.ownerAid, ts: ev.ts });
+function deleteFile(fp) {
+    try {
+        if (fs.existsSync(fp))
+            fs.unlinkSync(fp);
+    }
+    catch (error) {
+        logger.warn(`[PendingHints] delete failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function claimKey(claim) {
+    return targetKey(claim.sessionsDir, claim.channelType, claim.channelId, claim.selfAID, claim.chatType, claim.threadId, claim.channelKey);
+}
+export function pendingInterruptHints(sessionsDir, selfAID) {
+    const pending = [];
+    for (const chat of scanChatDirs(sessionsDir)) {
+        if (chat.selfAID !== selfAID || chat.channelType !== 'aun' || !chat.channelKey)
+            continue;
+        let events;
+        try {
+            events = readEvents(path.join(chat.dirPath, PENDING_HINTS_FILE));
         }
-        else {
-            if (ev.targetId)
-                active.delete(ev.targetId);
-            else
-                active.clear(); // 无 targetId = 撤该 thread 全部
+        catch {
+            continue;
+        }
+        const keys = new Set(events.filter(event => event.action === 'add')
+            .map(event => `${eventChatType(event)}\u0000${normThread(event.threadId)}`));
+        for (const key of keys) {
+            const [chatType, threadId] = key.split('\u0000');
+            for (const hint of effectiveFor(events, chatType, threadId)) {
+                if (hint.mode !== 'interrupt')
+                    continue;
+                pending.push({ channelKey: chat.channelKey, channelId: chat.channelId, chatType,
+                    threadId: threadId || undefined, hintId: hint.id, requestId: hint.promoteRequestId });
+            }
         }
     }
-    return [...active.values()].sort((a, b) => a.ts - b.ts);
+    return pending;
 }
-/**
- * 消费 (对端, thread) 的有效提示：回放算「该 thread」有效集 → 返回 → 清掉该 thread。
- *
- * thread 隔离：只消费传入 threadId（归一后）的提示。若文件里其它 thread 仍有未消费提示，
- * 重写文件保留它们；只有当整文件再无任何有效提示时才删除文件。
- * 返回空数组表示该 thread 无有效提示（调用方据此决定是否注入）。
- */
-export function consumeHints(sessionsDir, channelType, channelId, selfAID, threadId) {
-    const fp = hintsPath(sessionsDir, channelType, channelId, selfAID);
-    if (!fs.existsSync(fp))
-        return [];
-    let all;
+function idExistsElsewhere(fp, id) {
+    const parent = path.dirname(fp);
+    const sessionsRoot = path.dirname(parent);
+    let entries;
     try {
-        all = readAllJsonlLines(fp);
+        entries = fs.readdirSync(sessionsRoot, { withFileTypes: true });
     }
-    catch (e) {
-        logger.warn(`[PendingHints] consume read failed: ${e instanceof Error ? e.message : String(e)}`);
-        return [];
+    catch {
+        return false;
     }
-    const wantThread = normThread(threadId);
-    const sameThread = all.filter(ev => normThread(ev.threadId) === wantThread);
-    const effective = replayEffective(sameThread);
-    // 其它 thread 仍有未消费提示？若有，重写文件只留它们；否则删整个文件。
-    const otherThreadEvents = all.filter(ev => normThread(ev.threadId) !== wantThread);
-    if (otherThreadEvents.length > 0 && hasEffectiveInEvents(otherThreadEvents)) {
-        rewriteFile(fp, otherThreadEvents);
+    return entries.some(entry => entry.isDirectory() && path.join(sessionsRoot, entry.name) !== parent
+        && readEvents(path.join(sessionsRoot, entry.name, PENDING_HINTS_FILE))
+            .some(event => event.action === 'add' && event.id === id));
+}
+function isClaimed(claim, id) {
+    return claimedHints.get(claimKey(claim))?.has(id) ?? false;
+}
+export function appendHintAddDetailed(sessionsDir, channelType, channelId, selfAID, hint, channelKey) {
+    try {
+        const chatType = normChatType(hint.chatType);
+        const threadId = normThread(hint.threadId);
+        const fp = hintsPath(sessionsDir, channelType, channelId, selfAID, channelKey);
+        const events = readEvents(fp);
+        const original = events.find((event) => event.action === 'add' && event.id === hint.id);
+        if (original) {
+            const same = original.text === hint.text && original.ownerAid === hint.ownerAid
+                && eventChatType(original) === chatType && normThread(original.threadId) === threadId
+                && eventMode(original) === (hint.mode ?? 'next');
+            if (!same)
+                return { ok: false, id: hint.id, code: 'CONFLICT' };
+            const terminal = events.filter(event => event.action !== 'add'
+                && event.action !== 'promote' && event.targetId === hint.id
+                && eventChatType(event) === chatType && normThread(event.threadId) === threadId).at(-1);
+            return { ok: true, id: hint.id, duplicate: true,
+                state: terminal?.action === 'consumed' ? 'consumed' : terminal ? 'removed' : 'pending' };
+        }
+        if (idExistsElsewhere(fp, hint.id))
+            return { ok: false, id: hint.id, code: 'CONFLICT' };
+        fs.mkdirSync(path.dirname(fp), { recursive: true });
+        appendJsonl(fp, {
+            action: 'add',
+            id: hint.id,
+            text: hint.text,
+            mode: hint.mode === 'interrupt' ? 'interrupt' : 'next',
+            chatType,
+            threadId,
+            ownerAid: hint.ownerAid,
+            ts: hint.ts,
+        });
+        return { ok: true, id: hint.id, state: 'pending' };
     }
-    else {
-        deleteFile(fp);
+    catch (error) {
+        logger.warn(`[PendingHints] append add failed: ${error instanceof Error ? error.message : String(error)}`);
+        return { ok: false };
     }
-    return effective;
 }
-/** events（可能跨多 thread）中是否存在任意有效提示。 */
-function hasEffectiveInEvents(events) {
-    const byThread = new Map();
-    for (const ev of events) {
-        const t = normThread(ev.threadId);
-        (byThread.get(t) ?? byThread.set(t, []).get(t)).push(ev);
+export function appendHintAdd(sessionsDir, channelType, channelId, selfAID, hint) {
+    try {
+        const fp = hintsPath(sessionsDir, channelType, channelId, selfAID);
+        fs.mkdirSync(path.dirname(fp), { recursive: true });
+        appendJsonl(fp, {
+            action: 'add', id: hint.id, text: hint.text,
+            ...(hint.mode ? { mode: hint.mode } : {}),
+            ...(hint.chatType ? { chatType: hint.chatType } : {}),
+            threadId: normThread(hint.threadId), ownerAid: hint.ownerAid, ts: hint.ts,
+        });
+        return true;
     }
-    for (const [, evs] of byThread) {
-        if (replayEffective(evs).length > 0)
-            return true;
+    catch (error) {
+        logger.warn(`[PendingHints] append add failed: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
     }
-    return false;
 }
-function rewriteFile(fp, events) {
+export function appendHintRemoveDetailed(sessionsDir, channelType, channelId, selfAID, rm, channelKey) {
     try {
-        const body = events.map(e => JSON.stringify(e)).join('\n') + '\n';
-        fs.writeFileSync(fp, body);
+        const chatType = normChatType(rm.chatType);
+        const threadId = normThread(rm.threadId);
+        const fp = hintsPath(sessionsDir, channelType, channelId, selfAID, channelKey);
+        if (!fs.existsSync(fp))
+            return { ok: true, removedIds: [], removedHints: [] };
+        const all = readEvents(fp);
+        const effective = effectiveFor(all, chatType, threadId);
+        const targets = rm.targetId ? effective.filter(item => item.id === rm.targetId) : effective;
+        const claim = { sessionsDir, channelType, channelId, channelKey, selfAID, chatType, threadId };
+        if (targets.some(item => isClaimed(claim, item.id)))
+            return { ok: false, id: rm.targetId, code: 'IN_PROGRESS' };
+        if (targets.length === 0) {
+            const consumed = rm.targetId && all.some(event => event.action === 'consumed'
+                && event.targetId === rm.targetId && eventChatType(event) === chatType && normThread(event.threadId) === threadId);
+            return consumed ? { ok: false, id: rm.targetId, code: 'ALREADY_CONSUMED' }
+                : { ok: true, removedIds: [], removedHints: [] };
+        }
+        fs.appendFileSync(fp, targets.map(item => JSON.stringify({
+            action: 'remove', targetId: item.id, chatType, threadId, ts: rm.ts,
+        })).join('\n') + '\n');
+        return { ok: true, removedIds: targets.map(item => item.id), removedHints: targets };
     }
-    catch (e) {
-        logger.warn(`[PendingHints] rewriteFile failed: ${e instanceof Error ? e.message : String(e)}`);
+    catch (error) {
+        logger.warn(`[PendingHints] append remove failed: ${error instanceof Error ? error.message : String(error)}`);
+        return { ok: false };
     }
 }
-function deleteFile(fp) {
+export function appendHintRemove(sessionsDir, channelType, channelId, selfAID, rm) {
+    const result = appendHintRemoveDetailed(sessionsDir, channelType, channelId, selfAID, rm);
+    if (result.ok) {
+        const fp = hintsPath(sessionsDir, channelType, channelId, selfAID);
+        if (fs.existsSync(fp) && !hasAnyEffective(readEvents(fp)))
+            deleteFile(fp);
+    }
+    return result.ok;
+}
+export function appendHintPromoteDetailed(sessionsDir, channelType, channelId, selfAID, promote, channelKey) {
     try {
-        if (fs.existsSync(fp))
-            fs.unlinkSync(fp);
+        const chatType = normChatType(promote.chatType);
+        const threadId = normThread(promote.threadId);
+        const fp = hintsPath(sessionsDir, channelType, channelId, selfAID, channelKey);
+        const all = readEvents(fp);
+        const existing = effectiveFor(all, chatType, threadId).find(item => item.id === promote.targetId);
+        if (!existing)
+            return { ok: false, id: promote.targetId, code: all.some(event => event.action === 'consumed'
+                    && event.targetId === promote.targetId && eventChatType(event) === chatType && normThread(event.threadId) === threadId)
+                    ? 'ALREADY_CONSUMED' : 'NOT_FOUND' };
+        if ((existing.mode ?? 'next') === 'interrupt') {
+            appendJsonl(fp, {
+                action: 'promote', targetId: promote.targetId, chatType, threadId,
+                ...(promote.requestId ? { requestId: promote.requestId } : {}), ts: promote.ts,
+            });
+            return { ok: true, id: promote.targetId, duplicate: true, state: 'pending' };
+        }
+        appendJsonl(fp, {
+            action: 'promote', targetId: promote.targetId, chatType, threadId,
+            ...(promote.requestId ? { requestId: promote.requestId } : {}), ts: promote.ts,
+        });
+        return { ok: true, id: promote.targetId, state: 'pending' };
     }
-    catch (e) {
-        logger.warn(`[PendingHints] deleteFile failed: ${e instanceof Error ? e.message : String(e)}`);
+    catch (error) {
+        logger.warn(`[PendingHints] append promote failed: ${error instanceof Error ? error.message : String(error)}`);
+        return { ok: false };
     }
 }
-/** 仅供 watch / 调试：读出当前 (对端,thread) 有效提示，不消费、不删文件。 */
-export function peekHints(sessionsDir, channelType, channelId, selfAID, threadId) {
+/** Backward-compatible eager consumption API. New flows should use claim/commit. */
+export function consumeHints(sessionsDir, channelType, channelId, selfAID, threadId, chatType) {
     const fp = hintsPath(sessionsDir, channelType, channelId, selfAID);
     if (!fs.existsSync(fp))
         return [];
+    const all = readEvents(fp);
+    const normalizedChat = normChatType(chatType);
+    const normalizedThread = normThread(threadId);
+    const effective = effectiveFor(all, normalizedChat, normalizedThread);
+    const rest = all.filter(ev => eventChatType(ev) !== normalizedChat || normThread(ev.threadId) !== normalizedThread);
+    if (hasAnyEffective(rest)) {
+        const body = rest.map(event => JSON.stringify(event)).join('\n');
+        fs.writeFileSync(fp, `${body}${body ? '\n' : ''}`);
+    }
+    else
+        deleteFile(fp);
+    return effective;
+}
+export function peekHints(sessionsDir, channelType, channelId, selfAID, threadId, chatType, mode, channelKey) {
+    const effective = effectiveFor(readEvents(hintsPath(sessionsDir, channelType, channelId, selfAID, channelKey)), normChatType(chatType), normThread(threadId));
+    return mode ? effective.filter(item => (item.mode ?? 'next') === mode) : effective;
+}
+export function claimHints(sessionsDir, channelType, channelId, selfAID, threadId, chatType, mode = 'next', targetId, channelKey) {
+    const claim = {
+        token: '', hints: [], sessionsDir, channelType, channelId, selfAID, channelKey,
+        chatType: normChatType(chatType), threadId: normThread(threadId),
+    };
+    const effective = peekHints(sessionsDir, channelType, channelId, selfAID, threadId, chatType, mode, channelKey)
+        .filter(item => (!targetId || item.id === targetId) && !isClaimed(claim, item.id));
+    if (effective.length === 0)
+        return claim;
+    claim.token = `claim-${++claimSequence}`;
+    const ids = claimedHints.get(claimKey(claim)) ?? new Set();
+    effective.forEach(item => ids.add(item.id));
+    claimedHints.set(claimKey(claim), ids);
+    claim.hints = effective;
+    return claim;
+}
+export function releaseHintClaim(claim) {
+    if (!claim.token)
+        return;
+    const ids = claimedHints.get(claimKey(claim));
+    claim.hints.forEach(item => ids?.delete(item.id));
+    if (ids?.size === 0)
+        claimedHints.delete(claimKey(claim));
+}
+export function commitHintClaim(claim, ts = Date.now()) {
+    if (!claim.token || claim.hints.length === 0)
+        return true;
+    const fp = hintsPath(claim.sessionsDir, claim.channelType, claim.channelId, claim.selfAID, claim.channelKey);
     try {
-        const all = readAllJsonlLines(fp);
-        const wantThread = normThread(threadId);
-        return replayEffective(all.filter(ev => normThread(ev.threadId) === wantThread));
+        if (!fs.existsSync(fp))
+            return false;
+        fs.appendFileSync(fp, claim.hints.map(hint => JSON.stringify({
+            action: 'consumed', targetId: hint.id, chatType: claim.chatType, threadId: claim.threadId, ts,
+        })).join('\n') + '\n');
+        releaseHintClaim(claim);
+        return true;
     }
-    catch {
-        return [];
+    catch (error) {
+        logger.warn(`[PendingHints] commit failed: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
     }
 }
-// ── 渲染接线纯函数（无 IO，便于单测） ──────────────────────────
-/** 把有效提示转成 owner-hint SubMessage（排在对端真实 item 之前，走 inject 渲染模式）。 */
 export function hintsToSubMessages(hints) {
     return hints.map(h => ({
         kind: 'owner-hint',
@@ -194,39 +360,41 @@ export function hintsToSubMessages(hints) {
         timestamp: h.ts,
     }));
 }
-/**
- * 渲染失败兜底：把已消费的 owner-hint（提示已从 pending 删除、不可恢复）以纯文本前缀
- * 拼到对端原文之前，避免提示被静默丢弃。仅在 renderMessageBody 抛错或产出空时使用。
- */
 export function composeHintFallback(hintItems, content) {
     if (!hintItems || hintItems.length === 0)
         return content;
     const lines = hintItems.map(h => `‹owner 提示·已验证›（仅你可见，对端无感）\n${h.content}`);
     return [...lines, content].join('\n\n');
 }
-/**
- * 解析 observer.inject payload：鉴权（from∈owners）+ 校验（add 需 channel_id+text；remove 需 channel_id）
- * + 归一字段。纯函数，无副作用——落盘 / ack / watch 由调用方按结果执行。
- * @param ts 用于 add 缺省 id（`inj-<ts>`）；由调用方传入便于测试确定性。
- */
 export function parseInjectRequest(payload, fromAid, owners, ts) {
-    const p = (payload && typeof payload === 'object') ? payload : {};
+    const p = payload && typeof payload === 'object' ? payload : {};
     const injectId = typeof p.id === 'string' ? p.id : undefined;
-    const action = p.action === 'remove' ? 'remove' : 'add';
-    if (!owners.includes(fromAid)) {
-        return { kind: 'reject', code: 'NOT_OWNER', message: '仅 owner 可插话', action, injectId };
-    }
-    const target = (p.target && typeof p.target === 'object') ? p.target : undefined;
-    const channelId = target && typeof target.channel_id === 'string' ? target.channel_id : undefined;
-    const text = typeof p.text === 'string' ? p.text : '';
-    if (!channelId || (action === 'add' && !text.trim())) {
-        return { kind: 'reject', code: 'INVALID_TARGET', message: 'target.channel_id 必填；add 还需 text', action, injectId };
-    }
-    const chatType = target?.chat_type === 'group' ? 'group' : 'private';
+    const action = p.action === 'remove' || p.action === 'promote' ? p.action : 'add';
+    const target = p.target && typeof p.target === 'object' ? p.target : undefined;
+    const channelId = typeof target?.channel_id === 'string' ? target.channel_id : undefined;
+    const chatType = normChatType(target?.chat_type);
     const threadId = typeof target?.thread_id === 'string' ? target.thread_id : undefined;
     const targetId = typeof p.target_id === 'string' ? p.target_id : undefined;
-    if (action === 'remove') {
-        return { kind: 'remove', injectId, channelId, chatType, threadId, targetId };
+    const rejectContext = {
+        ...(channelId ? { channelId } : {}), chatType, ...(threadId ? { threadId } : {}),
+        ...(targetId ? { targetId } : {}),
+    };
+    if (!owners.includes(fromAid))
+        return { kind: 'reject', code: 'NOT_OWNER', message: '仅 owner 可插话', action, injectId, ...rejectContext };
+    if ((p.action !== undefined && p.action !== 'add' && p.action !== 'remove' && p.action !== 'promote')
+        || !channelId?.trim() || (target?.chat_type !== undefined && target.chat_type !== 'private' && target.chat_type !== 'group')
+        || (target?.thread_id !== undefined && typeof target.thread_id !== 'string')
+        || (action === 'add' && (typeof p.text !== 'string' || !p.text.trim() || (p.mode !== undefined && p.mode !== 'next' && p.mode !== 'interrupt')))
+        || (action === 'promote' && !targetId?.trim())) {
+        return { kind: 'reject', code: 'INVALID_TARGET', message: 'target.channel_id 必填；add 需 text，promote 需 target_id', action, injectId, ...rejectContext };
     }
-    return { kind: 'add', injectId, id: injectId || `inj-${ts}`, text, channelId, chatType, threadId, ownerAid: fromAid };
+    if (action === 'remove')
+        return { kind: 'remove', injectId, channelId, chatType, threadId, targetId };
+    if (action === 'promote')
+        return { kind: 'promote', injectId, channelId, chatType, threadId, targetId: targetId };
+    return {
+        kind: 'add', injectId, id: injectId || `inj-${ts}-${crypto.randomUUID()}`, text: p.text,
+        ...(p.mode === 'interrupt' ? { mode: 'interrupt' } : {}),
+        channelId, chatType, threadId, ownerAid: fromAid,
+    };
 }