@downcity/agent 1.1.25 → 1.1.32

package/src/plugin/builtins/chat/runtime/ChatQueueStore.ts

@@ -0,0 +1,185 @@
+/**
+ * ChatQueueStore：chat service 队列存储。
+ *
+ * 关键点（中文）
+ * - 这是 chat queue 的实例级状态容器。
+ * - 允许 `ChatService` 持有自己的 queue store，而不是完全依赖模块级全局状态。
+ * - 旧的 `ChatQueue.ts` 会保留共享门面，逐步迁移到显式实例注入。
+ */
+
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type {
+  ChatQueueEnqueueParams,
+  ChatQueueEnqueueResult,
+  ChatQueueItem,
+} from "@/plugin/builtins/chat/types/ChatQueue.js";
+
+/**
+ * 入队监听器。
+ */
+export type ChatQueueEnqueueListener = (laneKey: string) => void;
+
+/**
+ * ChatService queue store 的最小能力接口。
+ */
+export interface ChatQueueStorePort {
+  /**
+   * 订阅入队事件。
+   */
+  onEnqueue(listener: ChatQueueEnqueueListener): () => void;
+  /**
+   * 入队。
+   */
+  enqueue(params: ChatQueueEnqueueParams): ChatQueueEnqueueResult;
+  /**
+   * 弹出一条队列项。
+   */
+  shift(laneKey: string): ChatQueueItem | null;
+  /**
+   * drain 指定 lane。
+   */
+  drain(laneKey: string, maxItems?: number): ChatQueueItem[];
+  /**
+   * 列出当前 lane keys。
+   */
+  listLanes(): string[];
+  /**
+   * 查询某个 lane 的长度。
+   */
+  getLaneSize(laneKey: string): number;
+  /**
+   * 清空某个 lane。
+   */
+  clear(laneKey: string): void;
+}
+
+/**
+ * 共享 queue store。
+ *
+ * 关键点（中文）
+ * - 迁移阶段仍保留一份共享实例，避免一次性改动所有旧入口。
+ * - 新代码应优先通过 `AgentContext.agent` 解析显式 queue store。
+ */
+/**
+ * Chat queue 实例级存储。
+ */
+export class ChatQueueStore implements ChatQueueStorePort {
+  private readonly lanes: Map<string, ChatQueueItem[]> = new Map();
+  private readonly listeners: Set<ChatQueueEnqueueListener> = new Set();
+  private nextSeq = 1;
+
+  private generateItemId(): string {
+    const seq = this.nextSeq;
+    this.nextSeq += 1;
+    return `q:${Date.now().toString(36)}:${seq.toString(36)}`;
+  }
+
+  private getLane(key: string): ChatQueueItem[] {
+    const lane = this.lanes.get(key);
+    if (lane) return lane;
+    const created: ChatQueueItem[] = [];
+    this.lanes.set(key, created);
+    return created;
+  }
+
+  private normalizeLaneKey(raw: string): string {
+    const key = String(raw || "").trim();
+    if (!key) throw new Error("ChatQueueStore requires a non-empty lane key");
+    return key;
+  }
+
+  onEnqueue(listener: ChatQueueEnqueueListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  enqueue(params: ChatQueueEnqueueParams): ChatQueueEnqueueResult {
+    const laneKey = this.normalizeLaneKey(params.sessionId);
+    const lane = this.getLane(laneKey);
+    const item: ChatQueueItem = {
+      ...params,
+      id: this.generateItemId(),
+      enqueuedAt: Date.now(),
+      kind: params.kind ?? "exec",
+    };
+    lane.push(item);
+    for (const listener of this.listeners) {
+      try {
+        listener(laneKey);
+      } catch {
+        // ignore listener failure
+      }
+    }
+    return {
+      lanePosition: lane.length,
+      itemId: item.id,
+    };
+  }
+
+  shift(laneKey: string): ChatQueueItem | null {
+    const key = this.normalizeLaneKey(laneKey);
+    const lane = this.lanes.get(key);
+    if (!lane || lane.length === 0) return null;
+    const item = lane.shift() || null;
+    if (lane.length === 0) this.lanes.delete(key);
+    return item;
+  }
+
+  drain(laneKey: string, maxItems?: number): ChatQueueItem[] {
+    const key = this.normalizeLaneKey(laneKey);
+    const lane = this.lanes.get(key);
+    if (!lane || lane.length === 0) return [];
+
+    if (typeof maxItems === "number" && maxItems > 0 && maxItems < lane.length) {
+      return lane.splice(0, Math.floor(maxItems));
+    }
+
+    this.lanes.delete(key);
+    return lane.splice(0, lane.length);
+  }
+
+  listLanes(): string[] {
+    return Array.from(this.lanes.keys());
+  }
+
+  getLaneSize(laneKey: string): number {
+    const key = String(laneKey || "").trim();
+    if (!key) return 0;
+    const lane = this.lanes.get(key);
+    return lane ? lane.length : 0;
+  }
+
+  clear(laneKey: string): void {
+    const key = String(laneKey || "").trim();
+    if (!key) return;
+    this.lanes.delete(key);
+  }
+}
+
+const sharedChatQueueStore = new ChatQueueStore();
+
+/**
+ * 读取共享 chat queue store。
+ */
+export function getSharedChatQueueStore(): ChatQueueStore {
+  return sharedChatQueueStore;
+}
+
+/**
+ * 从运行时解析 chat queue store。
+ *
+ * 关键点（中文）
+ * - 新路径优先读取 `runtime.agent.runtimePlugins.chat.queueStore`。
+ * - 迁移阶段若拿不到，则回退到共享 queue store，保证旧入口可继续工作。
+ */
+export function resolveChatQueueStore(runtime?: AgentContext): ChatQueueStorePort {
+  const chatService = runtime?.agent?.runtimePlugins?.get?.("chat") as
+    | { queueStore?: ChatQueueStorePort }
+    | undefined;
+  if (chatService?.queueStore) {
+    return chatService.queueStore;
+  }
+  return sharedChatQueueStore;
+}

package/src/plugin/builtins/chat/runtime/ChatQueueWorker.ts

@@ -0,0 +1,485 @@
+/**
+ * ChatQueueWorker：chat service 侧队列执行器。
+ *
+ * 关键点（中文）
+ * - 消费 services / chat 的队列模块
+ * - 只负责把 lane 中的新输入持续提交给 `session.prompt()`
+ * - turn 并入策略、history 落盘、assistant 收敛统一交给 Session
+ */
+
+import type { Logger } from "@/utils/logger/Logger.js";
+import type { AgentContext } from "@/core/AgentContextTypes.js";
+import type { ChatQueueWorkerConfig } from "@/plugin/builtins/chat/types/ChatQueueWorker.js";
+import type { ChatQueueItem } from "@/plugin/builtins/chat/types/ChatQueue.js";
+import type { AgentSessionEvent } from "@/types/sdk/AgentSessionEvent.js";
+import type { AgentSessionTurnResult } from "@/types/sdk/AgentSessionTurn.js";
+import {
+  getSharedChatQueueStore,
+} from "./ChatQueue.js";
+import { getChatSender } from "./ChatSendRegistry.js";
+import {
+  hasPersistedAssistantSteps,
+  pickLastSuccessfulChatSendText,
+} from "./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;
+  }
+
+  /**
+   * 在单次执行期间维持“正在输入”心跳。
+   *
+   * 关键点（中文）
+   * - 通过 services / chat 的 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);
+  }
+}