@zhin.js/service-activity-feedback 1.0.2 → 1.1.0

package/plugin.js

@@ -0,0 +1,43 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createGenerationAdmissionGate, createToken, definePlugin, outboundHostToken, } from 'zhin.js';
+import { getLogger } from '@zhin.js/logger';
+import { loadActivityFeedbackServiceConfig, } from "./lib/config.js";
+import { bindActivityFeedbackToAIEventBus, createActivityFeedbackOrchestratorForRuntime, } from "./lib/ai-event-binder.js";
+import { createOutboundEndpointAccess, } from "./lib/executor.js";
+const logger = getLogger('activity-feedback');
+const activityFeedbackAdmissionToken = createToken('zhin.activity-feedback.generation-admission');
+/**
+ * Activity Feedback service — Plugin Runtime entry.
+ *
+ * Subscribes AI lifecycle events via `activityFeedbackAiBus`.
+ * When Root provides `outboundHostToken`, typing/status text uses
+ * ImRuntime.sendEndpointMessage; otherwise phases no-op.
+ */
+export default definePlugin({
+    name: 'activity-feedback',
+    metadata: {
+        displayName: 'Activity Feedback',
+    },
+    setup(context) {
+        const serviceConfig = loadActivityFeedbackServiceConfig(context.config.get());
+        if (serviceConfig.enabled === false) {
+            return;
+        }
+        const outbound = context.resources.has(outboundHostToken)
+            ? context.resources.use(outboundHostToken)
+            : undefined;
+        if (!outbound || typeof outbound.runWithView !== 'function') {
+            logger.debug('[ActivityFeedback] disabled: OutboundHost with generation-bound runWithView is required');
+            return;
+        }
+        const access = createOutboundEndpointAccess(outbound, logger);
+        const orchestrator = createActivityFeedbackOrchestratorForRuntime(serviceConfig, logger, access);
+        const admission = createGenerationAdmissionGate();
+        context.resources.provide(activityFeedbackAdmissionToken, admission);
+        const dispose = bindActivityFeedbackToAIEventBus(orchestrator, admission, outbound.runWithView.bind(outbound));
+        context.lifecycle.add(async () => {
+            logger.debug('[ActivityFeedback] Disposing Runtime AI event binder');
+            await dispose();
+        });
+    },
+});

package/schema.json

@@ -3,10 +3,126 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "enabled": { "type": "boolean", "default": true },
-    "defaults": { "type": "object", "additionalProperties": true },
-    "platforms": { "type": "object", "additionalProperties": true },
-    "endpoints": { "type": "object", "additionalProperties": true },
-    "schedule": { "type": "object", "additionalProperties": true }
+    "enabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Enable activity feedback for this plugin instance.",
+      "x-descriptionZh": "是否启用当前活动反馈插件实例。"
+    },
+    "defaults": {
+      "$ref": "#/$defs/activityFeedback",
+      "description": "Default policy for all platforms and Endpoints.",
+      "x-descriptionZh": "所有平台与 Endpoint 的默认策略。"
+    },
+    "platforms": {
+      "type": "object",
+      "x-keyPlaceholder": "<platform>",
+      "additionalProperties": { "$ref": "#/$defs/activityFeedback" },
+      "description": "Platform overrides keyed by platform name; values use the same shape as defaults.",
+      "x-descriptionZh": "按平台名覆盖；值的结构与 defaults 相同。"
+    },
+    "endpoints": {
+      "type": "object",
+      "x-keyPlaceholder": "<platform:endpointKey>",
+      "additionalProperties": { "$ref": "#/$defs/activityFeedback" },
+      "description": "Endpoint overrides keyed by platform:endpointKey; values use the same shape as defaults.",
+      "x-descriptionZh": "按 platform:endpointKey 覆盖；值的结构与 defaults 相同。"
+    },
+    "schedule": {
+      "$ref": "#/$defs/scheduleFeedback",
+      "description": "Schedule-only start, finish, and error feedback.",
+      "x-descriptionZh": "仅用于 Schedule 的开始、完成与失败反馈。"
+    }
+  },
+  "$defs": {
+    "activityFeedback": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable this policy layer.",
+          "x-descriptionZh": "是否启用当前策略层。"
+        },
+        "phases": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Feedback policy keyed by lifecycle phase.",
+          "x-descriptionZh": "按生命周期 phase 配置反馈策略。",
+          "properties": {
+            "queued": { "$ref": "#/$defs/scenePhases" },
+            "active": { "$ref": "#/$defs/scenePhases" },
+            "thinking": { "$ref": "#/$defs/scenePhases" },
+            "schedule_start": { "$ref": "#/$defs/scenePhases" },
+            "schedule_finish": { "$ref": "#/$defs/scenePhases" },
+            "schedule_error": { "$ref": "#/$defs/scenePhases" }
+          }
+        }
+      }
+    },
+    "scenePhases": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "private": { "$ref": "#/$defs/phaseConfig" },
+        "group": { "$ref": "#/$defs/phaseConfig" },
+        "channel": { "$ref": "#/$defs/phaseConfig" }
+      }
+    },
+    "phaseConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["reaction", "message", "typing", "none"],
+          "description": "How the phase is presented.",
+          "x-descriptionZh": "该 phase 的呈现方式。"
+        },
+        "emoji": {
+          "type": "string",
+          "description": "Reaction value for type=reaction.",
+          "x-descriptionZh": "type=reaction 时使用的回应值。"
+        },
+        "message": {
+          "type": "string",
+          "description": "Status text for type=message.",
+          "x-descriptionZh": "type=message 时使用的状态文本。"
+        },
+        "autoRemove": {
+          "type": "boolean",
+          "default": true,
+          "description": "Remove the feedback after the phase stops.",
+          "x-descriptionZh": "phase 停止后是否自动移除反馈。"
+        },
+        "removeDelay": {
+          "type": "number",
+          "description": "Delay before removal in milliseconds; negative values are normalized to zero at runtime.",
+          "x-descriptionZh": "自动移除前等待的毫秒数；负值会在运行时归一化为 0。"
+        },
+        "platformConfig": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Platform-specific options.",
+          "x-descriptionZh": "平台特定选项。"
+        }
+      }
+    },
+    "scheduleFeedback": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "phases": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "start": { "$ref": "#/$defs/scenePhases" },
+            "finish": { "$ref": "#/$defs/scenePhases" },
+            "error": { "$ref": "#/$defs/scenePhases" }
+          }
+        }
+      }
+    }
   }
 }

package/src/ai-event-binder.ts

@@ -1,16 +1,16 @@
-import type { Plugin } from 'zhin.js';
 import {
-  subscribeAIEvents,
   subscribeAIEventsOnTarget,
   activityFeedbackAiBus,
   isActivityFeedbackEnabled,
   type AIEventHandlers,
+  type AIEventPayload,
+  type AIEventTarget,
 } from '@zhin.js/agent';
 import { loadActivityFeedbackServiceConfig, type ActivityFeedbackServiceConfig } from './config.js';
+import type { GenerationAdmissionGate } from 'zhin.js';
 import {
   ActivityFeedbackExecutor,
   createNoopEndpointAccess,
-  createRootEndpointAccess,
   type ActivityFeedbackEndpointAccess,
 } from './executor.js';
 import { ActivityFeedbackOrchestrator } from './orchestrator.js';
@@ -32,7 +32,13 @@ export function createActivityFeedbackAIEventHandlers(
     onProcessingStart: async (payload) => {
       if (!isActivityFeedbackEnabled(payload, 'active')) return;
       await orchestrator.stopPhase(payload, 'queued', 'processing.start');
+      if (typeof payload.iterations === 'number' && payload.iterations > 1) {
+        await orchestrator.stopPhase(payload, 'thinking', 'processing.iteration');
+      }
       await orchestrator.startPhase(payload, 'active', 'processing.start');
+      if (typeof payload.iterations === 'number' && payload.iterations > 1 && payload.content?.trim()) {
+        await orchestrator.updatePhaseText(payload, 'active', payload.content.trim());
+      }
     },
 
     onTypingStart: async () => {},
@@ -50,9 +56,10 @@ export function createActivityFeedbackAIEventHandlers(
       await orchestrator.stopPhase(payload, 'active', 'processing.error');
     },
 
-    onTypingStop: (payload) => {
+    onTypingStop: async (payload) => {
       if (!isActivityFeedbackEnabled(payload, 'active')) return;
-      return orchestrator.stopPhase(payload, 'active', 'typing.stop');
+      await orchestrator.stopPhase(payload, 'thinking', 'typing.stop');
+      await orchestrator.stopPhase(payload, 'active', 'typing.stop');
     },
 
     onThinking: async (payload) => {
@@ -63,61 +70,166 @@ export function createActivityFeedbackAIEventHandlers(
       await orchestrator.updateThinkingText(payload, payload.thinking);
     },
 
+    onToolCall: async (payload) => {
+      if (!isActivityFeedbackEnabled(payload, 'active') || !payload.toolName?.trim()) return;
+      const text = `调用工具：${payload.toolName.trim()}…`;
+      await orchestrator.updatePhaseText(payload, 'thinking', text);
+      await orchestrator.updatePhaseText(payload, 'active', text);
+    },
+
+    onToolResult: async (payload) => {
+      if (!isActivityFeedbackEnabled(payload, 'active') || !payload.toolName?.trim()) return;
+      const outcome = payload.status === 'error' || payload.error ? '未完成' : '已完成';
+      const text = `工具 ${payload.toolName.trim()} ${outcome}，继续处理…`;
+      await orchestrator.updatePhaseText(payload, 'thinking', text);
+      await orchestrator.updatePhaseText(payload, 'active', text);
+    },
+
     onSubagentStart: async (payload) => {
       if (!isActivityFeedbackEnabled(payload, 'thinking')) return;
+      // The subagent has an isolated session key; remove its own active placeholder
+      // before switching to the richer thinking state.
       await orchestrator.stopPhase(payload, 'active', 'subagent.start');
       await orchestrator.startPhase(payload, 'thinking', 'subagent.start');
-      const label = payload.label
-        ? `🔍 子任务执行中: ${payload.label}...`
-        : '🔍 子 agent 处理中...';
-      await orchestrator.updateThinkingText(payload, label);
+      const tag = payload.agentId?.trim() || 'subagent';
+      const label = payload.label?.trim()
+        ? `子任务执行中: ${payload.label.trim()}...`
+        : '思考中...';
+      await orchestrator.updateThinkingText(payload, `[${tag}] ${label}`);
     },
 
     onSubagentFinish: async (payload) => {
-      if (!isActivityFeedbackEnabled(payload, 'active')) return;
-      await orchestrator.stopPhase(payload, 'thinking', 'subagent.finish');
-      await orchestrator.startPhase(payload, 'active', 'subagent.finish');
+      if (isActivityFeedbackEnabled(payload, 'thinking')) {
+        await orchestrator.stopPhase(payload, 'thinking', 'subagent.finish');
+      }
+      if (isActivityFeedbackEnabled(payload, 'active')) {
+        await orchestrator.stopPhase(payload, 'active', 'subagent.finish');
+      }
     },
 
     onScheduleStart: (payload) => orchestrator.startPhase(payload, 'schedule_start', 'schedule.start'),
-    onScheduleFinish: (payload) => orchestrator.stopPhase(payload, 'schedule_start', 'schedule.finish'),
+    onScheduleFinish: async (payload) => {
+      await orchestrator.stopPhase(payload, 'schedule_start', 'schedule.finish');
+      await orchestrator.showTransientPhase(payload, 'schedule_finish', 'schedule.finish');
+    },
     onScheduleError: async (payload) => {
       await orchestrator.stopPhase(payload, 'schedule_start', 'schedule.error');
-      await orchestrator.startPhase(payload, 'schedule_error', 'schedule.error');
+      await orchestrator.showTransientPhase(payload, 'schedule_error', 'schedule.error');
     },
   };
 }
 
-/** Legacy host Plugin path (ALS-aware subscribeAIEvents). */
-export function bindActivityFeedbackToAIEvents(
-  root: Plugin['root'],
-  orchestrator: ActivityFeedbackOrchestrator,
-): () => void {
-  return subscribeAIEvents(root, createActivityFeedbackAIEventHandlers(orchestrator));
-}
-
 /**
  * Plugin Runtime path: subscribe on module-level `activityFeedbackAiBus`
  * (fed by ZhinAgentEventEmitter.emit). No usePlugin / Adapter inject.
  */
 export function bindActivityFeedbackToAIEventBus(
   orchestrator: ActivityFeedbackOrchestrator,
-): () => void {
-  return subscribeAIEventsOnTarget(
+  admission: GenerationAdmissionGate,
+  runWithView: <T>(operation: () => Promise<T>) => Promise<T>,
+): () => Promise<void> {
+  let stopWatchingRetirement: (() => void) | undefined;
+  let cleanupNeedsGenerationView = false;
+  const watchRetirement = () => {
+    if (stopWatchingRetirement) return;
+    cleanupNeedsGenerationView = true;
+    stopWatchingRetirement = admission.onDeactivate(() => {
+      void close();
+    });
+  };
+  const serialized = createGenerationSerializedTarget(
     activityFeedbackAiBus,
+    admission,
+    runWithView,
+    watchRetirement,
+  );
+  const unsubscribe = subscribeAIEventsOnTarget(
+    serialized.target,
     createActivityFeedbackAIEventHandlers(orchestrator),
   );
+  let shutdown: Promise<void> | undefined;
+  function close(): Promise<void> {
+    if (shutdown) return shutdown;
+    const cleanup = async () => {
+      unsubscribe();
+      await serialized.close();
+      await orchestrator.dispose();
+    };
+    // Retirement is published before SnapshotStore changes its current pointer.
+    // Enter the IM view synchronously here so timers, native-typing keepalives,
+    // and final reaction/message cleanup all remain on this generation's Endpoint.
+    // A candidate rolled back before admitting any event has no generation-local
+    // feedback state, and its view is unavailable while Root is still idle.
+    shutdown = cleanupNeedsGenerationView ? runWithView(cleanup) : cleanup();
+    return shutdown;
+  }
+  return async () => {
+    stopWatchingRetirement?.();
+    await close();
+  };
 }
 
-export function mountActivityFeedbackService(
-  plugin: Plugin,
-  orchestrator: ActivityFeedbackOrchestrator,
-): void {
-  const dispose = bindActivityFeedbackToAIEvents(plugin.root, orchestrator);
-  plugin.onDispose(() => {
-    plugin.logger.debug('[ActivityFeedback] Disposing binder');
-    dispose();
-  });
+/** Generation-local ordering: one queue per IM session, no module-level runtime state. */
+function createGenerationSerializedTarget(
+  source: AIEventTarget,
+  admission: GenerationAdmissionGate,
+  runWithView: <T>(operation: () => Promise<T>) => Promise<T>,
+  onAdmitted: () => void,
+): {
+  target: AIEventTarget;
+  close(): Promise<void>;
+} {
+  const tails = new Map<string, Promise<void>>();
+  const wrappers = new Map<(payload: AIEventPayload) => void | Promise<void>,
+    (payload: AIEventPayload) => Promise<void>>();
+  let closed = false;
+  const target: AIEventTarget = {
+    on(event, listener) {
+      const wrapped = async (payload: AIEventPayload) => {
+        const release = admission.acquire();
+        if (!release) return;
+        onAdmitted();
+        try {
+          await runWithView(async () => {
+            const key = payload.sessionId || '__global__';
+            const previous = tails.get(key);
+            const run = async () => {
+              if (!closed) await listener(payload);
+            };
+            const current = previous
+              ? previous.catch(() => undefined).then(run)
+              : run();
+            tails.set(key, current);
+            try {
+              await current;
+            } finally {
+              if (tails.get(key) === current) tails.delete(key);
+            }
+          });
+        } finally {
+          release();
+        }
+      };
+      wrappers.set(listener, wrapped);
+      return source.on(event, wrapped);
+    },
+    off(event, listener) {
+      const wrapped = wrappers.get(listener);
+      if (!wrapped) return source.off(event, listener);
+      wrappers.delete(listener);
+      return source.off(event, wrapped);
+    },
+  };
+  return {
+    target,
+    async close() {
+      closed = true;
+      const pending = [...tails.values()];
+      await Promise.allSettled(pending);
+      tails.clear();
+      wrappers.clear();
+    },
+  };
 }
 
 export type ActivityFeedbackLogger = {
@@ -139,17 +251,6 @@ export function createActivityFeedbackOrchestrator(
   return new ActivityFeedbackOrchestrator(policy, executor, options.logger);
 }
 
-export function createActivityFeedbackOrchestratorFromPlugin(
-  plugin: Plugin,
-  serviceConfig: ActivityFeedbackServiceConfig,
-): ActivityFeedbackOrchestrator {
-  return createActivityFeedbackOrchestrator({
-    serviceConfig,
-    access: createRootEndpointAccess(plugin.root),
-    logger: plugin.logger,
-  });
-}
-
 /** Runtime: prefer OutboundHost-backed access; else noop until Host wires outbound. */
 export function createActivityFeedbackOrchestratorForRuntime(
   serviceConfig: ActivityFeedbackServiceConfig,

package/src/config.ts

@@ -1,6 +1,6 @@
 import type { ActivityFeedbackConfig } from '@zhin.js/agent';
 
-/** 顶层 `activityFeedback` 配置（zhin.config.yml，与 endpoints 解耦） */
+/** Plugin Runtime 实例配置（`plugins.<instanceKey>`，与 Adapter endpoint 配置解耦）。 */
 export interface ActivityFeedbackServiceConfig {
   enabled?: boolean;
   defaults?: ActivityFeedbackConfig;
@@ -66,7 +66,7 @@ export function loadActivityFeedbackServiceConfig(
 export function resolveActivityFeedbackForTarget(
   service: ActivityFeedbackServiceConfig,
   platform: string,
-  endpointId: string,
+  endpointKey: string,
 ): ActivityFeedbackConfig | undefined {
   if (service.enabled === false) {
     return { enabled: false };
@@ -74,6 +74,6 @@ export function resolveActivityFeedbackForTarget(
   return mergeActivityFeedbackLayers(
     service.defaults,
     service.platforms?.[platform],
-    service.endpoints?.[`${platform}:${endpointId}`],
+    service.endpoints?.[`${platform}:${endpointKey}`],
   );
 }