@downcity/plugins 1.0.4

package/src/chat/runtime/ChatQueueWorker.ts

@@ -0,0 +1,485 @@
+/**
+ * ChatQueueWorker：chat plugin runtime 侧队列执行器。
+ *
+ * 关键点（中文）
+ * - 消费 chat plugin runtime 持有的队列模块
+ * - 只负责把 lane 中的新输入持续提交给 `session.prompt()`
+ * - turn 并入策略、history 落盘、assistant 收敛统一交给 Session
+ */
+
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
+import type { ChatQueueItem } from "@/chat/types/ChatQueue.js";
+import type { AgentSessionEvent } from "@downcity/agent/internal/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionTurnResult } from "@downcity/agent/internal/types/sdk/AgentSessionTurn.js";
+import {
+  getSharedChatQueueStore,
+} from "./ChatQueue.js";
+import { getChatSender } from "./ChatSendRegistry.js";
+import {
+  hasPersistedAssistantSteps,
+  pickLastSuccessfulChatSendText,
+} from "@downcity/agent/internal/executor/messages/UserVisibleText.js";
+import {
+  buildChannelErrorText,
+  collectInitialBurstItems,
+  normalizeChatQueueWorkerConfig,
+} from "./ChatQueueWorkerSupport.js";
+import type { ChatQueueStorePort } from "./ChatQueueStore.js";
+import {
+  dispatchAssistantTextDirect,
+  dispatchTextToChannel,
+} from "./ChatQueueReplyDispatch.js";
+
+const TYPING_ACTION_INTERVAL_MS = 4_000;
+
+type LaneState = {
+  key: string;
+  running: boolean;
+  turnObservers: Map<string, TurnObservation>;
+  unsubscribeSessionEvents?: () => void;
+};
+
+type TurnObservation = {
+  turnId: string;
+  sessionId: string;
+  messageId?: string;
+  assistantStepDispatched: boolean;
+  typing: { stop: () => void };
+};
+
+export class ChatQueueWorker {
+  private readonly logger: Logger;
+  private readonly context: AgentContext;
+  private readonly config: ChatQueueWorkerConfig;
+  private readonly queueStore: ChatQueueStorePort;
+
+  private readonly lanes: Map<string, LaneState> = new Map();
+  private readonly runnable: string[] = [];
+  private readonly runnableSet: Set<string> = new Set();
+  private runningTotal: number = 0;
+  private unsubscribe?: () => void;
+  private stopped = false;
+
+  constructor(params: {
+    logger: Logger;
+    context: AgentContext;
+    queueStore?: ChatQueueStorePort;
+    config?: Partial<ChatQueueWorkerConfig>;
+  }) {
+    this.logger = params.logger;
+    this.context = params.context;
+    this.config = normalizeChatQueueWorkerConfig(params.config);
+    this.queueStore = params.queueStore || getSharedChatQueueStore();
+  }
+
+  /**
+   * 启动 worker。
+   */
+  start(): void {
+    if (this.unsubscribe) return;
+    this.stopped = false;
+    this.unsubscribe = this.queueStore.onEnqueue((laneKey) => {
+      this.markRunnable(laneKey);
+      void this.requestTurnCancelIfSupported(laneKey);
+      void this.kick();
+    });
+
+    // 初始化已有 lanes
+    for (const laneKey of this.queueStore.listLanes()) {
+      this.markRunnable(laneKey);
+    }
+    void this.kick();
+  }
+
+  /**
+   * 停止 worker（不清队列）。
+   */
+  stop(): void {
+    this.stopped = true;
+    if (this.unsubscribe) this.unsubscribe();
+    this.unsubscribe = undefined;
+  }
+
+  private getOrCreateLane(key: string): LaneState {
+    const existing = this.lanes.get(key);
+    if (existing) return existing;
+    const lane: LaneState = {
+      key,
+      running: false,
+      turnObservers: new Map(),
+    };
+    this.lanes.set(key, lane);
+    return lane;
+  }
+
+  private markRunnable(key: string): void {
+    if (this.runnableSet.has(key)) return;
+    this.runnableSet.add(key);
+    this.runnable.push(key);
+  }
+
+  private pickNextRunnableLane(): LaneState | null {
+    while (this.runnable.length > 0) {
+      const key = this.runnable.shift()!;
+      this.runnableSet.delete(key);
+      const lane = this.getOrCreateLane(key);
+      if (lane.running) continue;
+      if (this.queueStore.getLaneSize(key) === 0) continue;
+      return lane;
+    }
+    return null;
+  }
+
+  private async kick(): Promise<void> {
+    if (this.stopped) return;
+    while (this.runningTotal < this.config.maxConcurrency) {
+      const lane = this.pickNextRunnableLane();
+      if (!lane) return;
+
+      lane.running = true;
+      this.runningTotal += 1;
+      void this.runLaneOnce(lane)
+        .catch((err) => {
+          this.logger.error(`ChatQueueWorker lane failed: ${String(err)}`);
+        })
+        .finally(() => {
+          lane.running = false;
+          this.runningTotal -= 1;
+          if (!this.stopped) {
+            if (this.queueStore.getLaneSize(lane.key) > 0) {
+              this.markRunnable(lane.key);
+            }
+            void this.kick();
+          }
+        });
+    }
+  }
+
+  private async runLaneOnce(lane: LaneState): Promise<void> {
+    const first = this.queueStore.shift(lane.key);
+    if (!first) return;
+    await this.processOne(lane.key, first);
+  }
+
+  /**
+   * 若底层 runtime 支持取消当前 turn，则在新消息入队时立刻触发。
+   *
+   * 关键点（中文）
+   * - 只对支持显式取消的 runtime 生效（主要是 ACP）。
+   * - 失败不影响正常排队；worker 仍会走串行兜底。
+   */
+  private async requestTurnCancelIfSupported(sessionId: string): Promise<void> {
+    const sessionKey = String(sessionId || "").trim();
+    if (!sessionKey) return;
+    try {
+      // ACP executor removed; cancel is no longer supported through session executor port.
+    } catch {
+      // ignore
+
+      return;
+      // ignore
+    }
+  }
+
+  private handleControl(item: ChatQueueItem): boolean {
+    const control = item.control;
+    if (!control) return false;
+    if (control.type === "clear") {
+      this.requireContext(item.sessionId).clearExecutor();
+      this.queueStore.clear(item.sessionId);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * 在单次执行期间维持“正在输入”心跳。
+   *
+   * 关键点（中文）
+   * - 通过 chat plugin runtime 的 dispatcher 发送动作（不经过 main bindings）
+   * - 先发送一次，再按固定间隔续发
+   * - 发送失败不影响主执行流程（best-effort）
+   */
+  private startTypingHeartbeat(item: ChatQueueItem): { stop: () => void } {
+    const chatId = String(item.targetId || "").trim();
+    if (!chatId) return { stop: () => {} };
+
+    const dispatcher = getChatSender(item.channel);
+    const sendAction = dispatcher?.sendAction;
+    if (typeof sendAction !== "function") {
+      return { stop: () => {} };
+    }
+
+    const sendOnce = async () => {
+      try {
+        await sendAction({
+          chatId,
+          action: "typing",
+          ...(typeof item.threadId === "number"
+            ? { messageThreadId: item.threadId }
+            : {}),
+          ...(typeof item.targetType === "string" && item.targetType
+            ? { chatType: item.targetType }
+            : {}),
+          ...(typeof item.messageId === "string" && item.messageId
+            ? { messageId: item.messageId }
+            : {}),
+        });
+      } catch {
+        // ignore
+      }
+    };
+
+    void sendOnce();
+    const timer = setInterval(() => {
+      void sendOnce();
+    }, TYPING_ACTION_INTERVAL_MS);
+    if (typeof timer.unref === "function") timer.unref();
+
+    return {
+      stop: () => clearInterval(timer),
+    };
+  }
+
+  /**
+   * 发送 step 文本到 chat。
+   *
+   * 关键点（中文）
+   * - step 必须在当前回调阶段真正送达，不能依赖 run 结束后的 final 兜底。
+   * - 先尝试 direct 路径，保留 frontmatter / reaction 等语义。
+   * - 若 direct 未送达，则立刻回退到普通 channel 文本发送。
+   */
+  private async dispatchAssistantStepMessage(params: {
+    sessionId: string;
+    text: string;
+    messageId?: string;
+  }): Promise<boolean> {
+    const stepText = String(params.text || "").trim();
+    if (!stepText) return false;
+
+    const dispatchedDirectly = await dispatchAssistantTextDirect({
+      logger: this.logger,
+      context: this.context,
+      sessionId: params.sessionId,
+      assistantText: stepText,
+      phase: "step",
+    });
+    if (dispatchedDirectly) {
+      return true;
+    }
+
+    return await dispatchTextToChannel({
+      logger: this.logger,
+      context: this.context,
+      sessionId: params.sessionId,
+      text: stepText,
+      messageId: params.messageId,
+      phase: "step",
+    });
+  }
+
+  private async processOne(laneKey: string, first: ChatQueueItem): Promise<void> {
+    const lane = this.getOrCreateLane(laneKey);
+    if (first.kind === "control") {
+      this.handleControl(first);
+      return;
+    }
+
+    if (first.kind === "audit") {
+      return;
+    }
+
+    const serviceContext = this.requireContext(first.sessionId);
+    this.ensureLaneSessionSubscription(lane, first.sessionId);
+
+    let clearRequested = false;
+    const initialBurstItems = await collectInitialBurstItems({
+      laneKey,
+      first,
+      config: this.config,
+      queueStore: this.queueStore,
+    });
+    for (const item of initialBurstItems) {
+      if (item.kind === "control") {
+        if (item.control?.type === "clear") clearRequested = true;
+        continue;
+      }
+      if (item.kind === "exec") {
+        await this.submitExecItem({
+          lane,
+          item,
+          serviceContext,
+        });
+      }
+    }
+
+    if (clearRequested) {
+      serviceContext.clearExecutor();
+      this.queueStore.clear(first.sessionId);
+    }
+  }
+
+  private ensureLaneSessionSubscription(
+    lane: LaneState,
+    sessionId: string,
+  ): void {
+    if (lane.unsubscribeSessionEvents) return;
+    const session = this.requireContext(sessionId);
+    lane.unsubscribeSessionEvents = session.subscribe((event) => {
+      void this.handleLaneSessionEvent(lane, event);
+    });
+  }
+
+  private async handleLaneSessionEvent(
+    lane: LaneState,
+    event: AgentSessionEvent,
+  ): Promise<void> {
+    if (!("turnId" in event)) return;
+    const observation = lane.turnObservers.get(event.turnId);
+    if (!observation) return;
+    if (event.type !== "assistant-step") return;
+    if (event.visibility === "internal") return;
+    const stepText = String(event.text || "").trim();
+    if (!stepText) return;
+    const dispatched = await this.dispatchAssistantStepMessage({
+      sessionId: observation.sessionId,
+      text: stepText,
+      messageId: observation.messageId,
+    });
+    if (dispatched) {
+      observation.assistantStepDispatched = true;
+    }
+  }
+
+  private async submitExecItem(params: {
+    lane: LaneState;
+    item: ChatQueueItem;
+    serviceContext: ReturnType<ChatQueueWorker["requireContext"]>;
+  }): Promise<void> {
+    const item = params.item;
+    try {
+      const turn = await params.serviceContext.prompt({
+        query: item.text,
+      });
+      if (params.lane.turnObservers.has(turn.id)) {
+        return;
+      }
+      const observation: TurnObservation = {
+        turnId: turn.id,
+        sessionId: item.sessionId,
+        messageId: item.messageId,
+        assistantStepDispatched: false,
+        typing: this.startTypingHeartbeat(item),
+      };
+      params.lane.turnObservers.set(turn.id, observation);
+      void turn.finished
+        .then(async (result) => {
+          await this.handleObservedTurnFinish(observation, result);
+        })
+        .finally(() => {
+          observation.typing.stop();
+          params.lane.turnObservers.delete(turn.id);
+          if (
+            params.lane.turnObservers.size === 0 &&
+            this.queueStore.getLaneSize(params.lane.key) === 0 &&
+            params.lane.unsubscribeSessionEvents
+          ) {
+            params.lane.unsubscribeSessionEvents();
+            params.lane.unsubscribeSessionEvents = undefined;
+          }
+        });
+    } catch (error) {
+      const channelErrorText = buildChannelErrorText(error);
+      this.logger.error("ChatQueueWorker prompt submit failed", {
+        sessionId: item.sessionId,
+        error: String(error),
+      });
+      await dispatchTextToChannel({
+        logger: this.logger,
+        context: this.context,
+        sessionId: item.sessionId,
+        text: channelErrorText,
+        messageId: item.messageId,
+        phase: "error",
+      });
+    }
+  }
+
+  private async handleObservedTurnFinish(
+    observation: TurnObservation,
+    result: AgentSessionTurnResult,
+  ): Promise<void> {
+    const stopReason = String(
+      result.assistantMessage?.metadata?.extra?.stopReason || "",
+    ).trim();
+    if (stopReason === "cancelled") {
+      return;
+    }
+
+    if (!result.success) {
+      const resultErrorText =
+        pickLastSuccessfulChatSendText(result.assistantMessage) ||
+        result.error ||
+        "Execution failed";
+      const channelErrorText = buildChannelErrorText(resultErrorText);
+      this.logger.error("ChatQueueWorker turn finished with failure", {
+        sessionId: observation.sessionId,
+        error: result.error || resultErrorText,
+      });
+      await dispatchTextToChannel({
+        logger: this.logger,
+        context: this.context,
+        sessionId: observation.sessionId,
+        text: channelErrorText,
+        messageId: observation.messageId,
+        phase: "error",
+      });
+      return;
+    }
+
+    if (
+      observation.assistantStepDispatched ||
+      hasPersistedAssistantSteps(result.assistantMessage)
+    ) {
+      return;
+    }
+
+    const finalAssistantText =
+      pickLastSuccessfulChatSendText(result.assistantMessage) || result.text;
+    if (!finalAssistantText) {
+      return;
+    }
+
+    const dispatchedDirectly = await dispatchAssistantTextDirect({
+      logger: this.logger,
+      context: this.context,
+      sessionId: observation.sessionId,
+      assistantText: finalAssistantText,
+      phase: "final",
+    });
+    if (dispatchedDirectly) {
+      return;
+    }
+
+    await dispatchTextToChannel({
+      logger: this.logger,
+      context: this.context,
+      sessionId: observation.sessionId,
+      text: finalAssistantText,
+      messageId: observation.messageId,
+      phase: "final",
+    });
+  }
+
+  /**
+   * 读取 session 端口。
+   *
+   * 关键点（中文）
+   * - 在使用点显式校验，避免隐藏依赖来源。
+   */
+  private requireContext(sessionId: string) {
+    return this.context.session.get(sessionId);
+  }
+}

package/src/chat/runtime/ChatQueueWorkerSupport.ts

@@ -0,0 +1,137 @@
+/**
+ * ChatQueueWorkerSupport：chat queue worker 的通用辅助模块。
+ *
+ * 关键点（中文）
+ * - 收敛 burst merge、错误文本构造、worker 配置归一化等辅助逻辑。
+ * - 这些逻辑与 lane 调度主流程正交，拆出后让 ChatQueueWorker 更聚焦。
+ */
+
+import type { ChatQueueWorkerConfig } from "@/chat/types/ChatQueueWorker.js";
+import type { ChatQueueItem } from "@/chat/types/ChatQueue.js";
+import type { ChatQueueStorePort } from "./ChatQueueStore.js";
+
+const CHANNEL_ERROR_TEXT_MAX_LENGTH = 480;
+const DEFAULT_MERGE_DEBOUNCE_MS = 600;
+const DEFAULT_MERGE_MAX_WAIT_MS = 2_000;
+const BURST_MERGE_POLL_INTERVAL_MS = 20;
+
+/**
+ * 归一化 worker 配置。
+ */
+export function normalizeChatQueueWorkerConfig(
+  input?: Partial<ChatQueueWorkerConfig>,
+): ChatQueueWorkerConfig {
+  const maxConcurrency =
+    typeof input?.maxConcurrency === "number" && Number.isFinite(input.maxConcurrency)
+      ? Math.max(1, Math.min(32, Math.floor(input.maxConcurrency)))
+      : 2;
+
+  const mergeDebounceMs =
+    typeof input?.mergeDebounceMs === "number" &&
+    Number.isFinite(input.mergeDebounceMs)
+      ? Math.max(0, Math.min(60_000, Math.floor(input.mergeDebounceMs)))
+      : DEFAULT_MERGE_DEBOUNCE_MS;
+
+  const mergeMaxWaitMs =
+    typeof input?.mergeMaxWaitMs === "number" &&
+    Number.isFinite(input.mergeMaxWaitMs)
+      ? Math.max(0, Math.min(120_000, Math.floor(input.mergeMaxWaitMs)))
+      : DEFAULT_MERGE_MAX_WAIT_MS;
+
+  return { maxConcurrency, mergeDebounceMs, mergeMaxWaitMs };
+}
+
+/**
+ * 判断是否启用“启动前消息合并”。
+ */
+export function isBurstMergeEnabled(config: ChatQueueWorkerConfig): boolean {
+  return config.mergeDebounceMs > 0 && config.mergeMaxWaitMs > 0;
+}
+
+/**
+ * 判断是否为上游模型服务临时不可用。
+ */
+export function isTemporaryModelServiceUnavailable(error: unknown): boolean {
+  const msg = String(error ?? "");
+  return (
+    /Service temporarily unavailable/i.test(msg) ||
+    /AI_RetryError/i.test(msg) ||
+    /AI_APICallError/i.test(msg) ||
+    /maxRetriesExceeded/i.test(msg) ||
+    /\b503\b/.test(msg)
+  );
+}
+
+/**
+ * 构造回发到 channel 的失败文本。
+ */
+export function buildChannelErrorText(error: unknown): string {
+  if (isTemporaryModelServiceUnavailable(error)) {
+    return "⚠️ 模型服务暂时不可用（503），系统已自动重试但仍失败，请稍后再试。";
+  }
+
+  const normalized = String(error ?? "").replace(/\s+/g, " ").trim();
+  if (/AI_NoOutputGeneratedError|No output generated/i.test(normalized)) {
+    return "❌ 模型本轮没有生成可发送内容。系统已记录底层 stream 错误，请稍后重试。";
+  }
+
+  if (!normalized) {
+    return "❌ 执行失败，请稍后重试。";
+  }
+
+  const clipped =
+    normalized.length > CHANNEL_ERROR_TEXT_MAX_LENGTH
+      ? `${normalized.slice(0, CHANNEL_ERROR_TEXT_MAX_LENGTH)}…`
+      : normalized;
+  return `❌ 执行失败：${clipped}`;
+}
+
+/**
+ * 等待一小段时间，让同 lane 的连续消息尽量在一次 run 前合并。
+ */
+export async function collectInitialBurstItems(params: {
+  laneKey: string;
+  first: ChatQueueItem;
+  config: ChatQueueWorkerConfig;
+  queueStore: ChatQueueStorePort;
+}): Promise<ChatQueueItem[]> {
+  if (params.first.kind !== "exec") return [params.first];
+  if (!isBurstMergeEnabled(params.config)) return [params.first];
+
+  const startedAt = Date.now();
+  let lastInboundAt = startedAt;
+  let knownLaneSize = params.queueStore.getLaneSize(params.laneKey);
+
+  while (true) {
+    const now = Date.now();
+    const idleMs = now - lastInboundAt;
+    const elapsedMs = now - startedAt;
+    if (idleMs >= params.config.mergeDebounceMs) break;
+    if (elapsedMs >= params.config.mergeMaxWaitMs) break;
+
+    const remainingDebounceMs = params.config.mergeDebounceMs - idleMs;
+    const remainingMaxWaitMs = params.config.mergeMaxWaitMs - elapsedMs;
+    const sleepMs = Math.max(
+      1,
+      Math.min(
+        BURST_MERGE_POLL_INTERVAL_MS,
+        remainingDebounceMs,
+        remainingMaxWaitMs,
+      ),
+    );
+
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, sleepMs);
+      if (typeof timer.unref === "function") timer.unref();
+    });
+
+    const laneSize = params.queueStore.getLaneSize(params.laneKey);
+    if (laneSize > knownLaneSize) {
+      knownLaneSize = laneSize;
+      lastInboundAt = Date.now();
+    }
+  }
+
+  const drained = params.queueStore.drain(params.laneKey);
+  return drained.length > 0 ? [params.first, ...drained] : [params.first];
+}