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

package/src/executor.ts

@@ -1,26 +1,12 @@
-import type { Adapter } from 'zhin.js';
-import { enableActivityFeedbackForBot, isGenericActivityFeedbackManager, type ActivityFeedbackManager, type ActivityFeedbackPhase, type EndpointWithActivityFeedback, type PlatformActivityFeedbackManager, type ResolvedActivityFeedbackPhaseConfig, type ActivityFeedbackEventContext } from '@zhin.js/agent';
-import type { OutboundHost } from '@zhin.js/plugin-runtime';
+import { enableActivityFeedbackForBot, isGenericActivityFeedbackManager, type ActivityFeedbackManager, type ActivityFeedbackPhase, type ActivityFeedbackSendPort, type EndpointWithActivityFeedback, type PlatformActivityFeedbackManager, type ResolvedActivityFeedbackPhaseConfig, type ActivityFeedbackEventContext } from '@zhin.js/agent';
+import type { OutboundHost } from 'zhin.js';
 
 /** IM 侧 endpoint 访问 seam（便于测试注入 fake） */
 export interface ActivityFeedbackEndpointAccess {
   resolve(
     platform: string,
-    endpointId: string,
-  ): { endpoint: EndpointWithActivityFeedback; adapter: Adapter } | undefined;
-}
-
-export function createRootEndpointAccess(root: {
-  injectAdapter(platform: string): Adapter | undefined;
-}): ActivityFeedbackEndpointAccess {
-  return {
-    resolve(platform, endpointId) {
-      const adapter = root.injectAdapter(platform);
-      const endpoint = adapter?.endpoints?.get(endpointId) as EndpointWithActivityFeedback | undefined;
-      if (!endpoint || !adapter) return undefined;
-      return { endpoint, adapter };
-    },
-  };
+    endpointKey: string,
+  ): { endpoint: EndpointWithActivityFeedback; outbound: ActivityFeedbackSendPort } | undefined;
 }
 
 /** Slice-2: no Adapter inject — executor start/stop no-op when resolve returns undefined. */
@@ -55,7 +41,7 @@ function stringifySendContent(content: unknown): string {
  * Plugin Runtime: resolve endpoints via OutboundHost → ImRuntime.sendEndpointMessage.
  * Typing/reaction text goes through the unified outbound chain (no legacy Adapter.inject).
  *
- * 按 platform:endpointId 缓存 { endpoint, adapter }：activity manager 挂在
+ * 按 platform:endpointKey 缓存 { endpoint, outbound }：activity manager 挂在
  * endpoint.$activityFeedback 上，start/stop 必须解析到同一个对象，否则
  * stop 时拿不到 manager，typing 指示器永远无法停止。
  */
@@ -63,76 +49,125 @@ export function createOutboundEndpointAccess(
   outbound: OutboundHost,
   logger?: { debug: (msg: string, ...args: unknown[]) => void },
 ): ActivityFeedbackEndpointAccess {
-  const cache = new Map<string, { endpoint: EndpointWithActivityFeedback; adapter: Adapter }>();
+  const cache = new Map<string, {
+    endpoint: EndpointWithActivityFeedback;
+    outbound: ActivityFeedbackSendPort;
+  }>();
   return {
-    resolve(platform, endpointId) {
-      const key = `${platform}:${endpointId}`;
+    resolve(platform, endpointKey) {
+      const key = JSON.stringify([platform, endpointKey]);
       const cached = cache.get(key);
       if (cached) return cached;
+      const declared = outbound.capabilities?.({ adapter: platform, endpointKey })?.operations;
+      const supports = (operation: 'recall' | 'edit' | 'reaction' | 'typing') =>
+        declared?.includes(operation) === true;
+      const recall = outbound.recall;
+      const edit = outbound.edit;
+      const addReaction = outbound.addReaction;
+      const removeReaction = outbound.removeReaction;
+      const typing = outbound.typing;
       const endpoint = {
-        $id: endpointId,
-        // Prefer real OutboundHost.recall when available (icqq RECALL_MSG).
-        $recallMessage: async (messageId: string) => {
-          if (outbound.recall) {
-            try {
-              await outbound.recall({ adapter: platform, endpointId, messageId });
-              return;
-            } catch (error) {
-              logger?.debug(
-                `[ActivityFeedback] outbound recall failed (${key}):`,
-                error instanceof Error ? error.message : String(error),
-              );
-              return;
-            }
-          }
-          logger?.debug(
-            `[ActivityFeedback] recall not supported via OutboundHost (${key}, messageId=${messageId})`,
-          );
+        $id: endpointKey,
+        control: {
+          ...(recall && supports('recall') ? {
+            recall: async (message: Parameters<typeof recall>[0]['message']) => {
+              try {
+                await recall({ adapter: platform, endpointKey, message });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound recall failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+              }
+            },
+          } : {}),
+          ...(edit && supports('edit') ? {
+            edit: async (
+              message: Parameters<typeof edit>[0]['message'],
+              content: unknown,
+            ) => {
+              try {
+                return await edit({ adapter: platform, endpointKey, message, content });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound edit failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+                return null;
+              }
+            },
+          } : {}),
+          ...(addReaction && supports('reaction') ? {
+            addReaction: async (
+              message: Parameters<typeof addReaction>[0]['message'],
+              emoji: string,
+              hint?: { sceneType?: 'private' | 'group' | 'channel'; channelId?: string },
+            ) => {
+              try {
+                return await addReaction({
+                  adapter: platform,
+                  endpointKey,
+                  message,
+                  emoji,
+                  sceneType: hint?.sceneType,
+                  channelId: hint?.channelId,
+                });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound addReaction failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+                return null;
+              }
+            },
+          } : {}),
+          ...(removeReaction && supports('reaction') ? {
+            removeReaction: async (
+              message: Parameters<typeof removeReaction>[0]['message'],
+              reactionId: string,
+            ) => {
+              try {
+                await removeReaction({ adapter: platform, endpointKey, message, reactionId });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound removeReaction failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+              }
+            },
+          } : {}),
+          ...(typing && supports('typing') ? {
+            typing: async (
+              conversation: Parameters<typeof typing>[0]['conversation'],
+              active?: boolean,
+            ) => {
+              try {
+                await typing({ adapter: platform, endpointKey, conversation, active });
+              } catch (error) {
+                logger?.debug(
+                  `[ActivityFeedback] outbound typing failed (${key}):`,
+                  error instanceof Error ? error.message : String(error),
+                );
+              }
+            },
+          } : {}),
         },
-        $addReaction: outbound.addReaction
-          ? async (
-            messageId: string,
-            emoji: string,
-            hint?: { sceneType?: 'private' | 'group' | 'channel'; channelId?: string },
-          ) => outbound.addReaction!({
-            adapter: platform,
-            endpointId,
-            messageId,
-            emoji,
-            sceneType: hint?.sceneType,
-            channelId: hint?.channelId,
-          })
-          : undefined,
-        $removeReaction: outbound.removeReaction
-          ? async (messageId: string, reactionId: string) => {
-            await outbound.removeReaction!({
-              adapter: platform,
-              endpointId,
-              messageId,
-              reactionId,
-            });
-          }
-          : undefined,
       } as EndpointWithActivityFeedback;
-      const adapter = {
-        sendMessage: async (options: {
-          type?: string;
-          id?: string;
-          content?: unknown;
-        }) => {
-          const text = stringifySendContent(options.content);
-          if (!text || !options.id) return null;
+      const sendPort: ActivityFeedbackSendPort = {
+        send: async ({ conversation, content }) => {
+          const text = stringifySendContent(content);
+          if (!text || !conversation.id) return null;
           try {
             const messageId = await outbound.send({
               adapter: platform,
-              endpointId,
-              channelType: options.type || 'private',
-              channelId: options.id,
+              endpointKey,
+              conversation: {
+                kind: conversation.kind,
+                id: conversation.id,
+              },
               content: text,
             });
-            // Prefer real id; fall back to a sentinel so MessageTypingIndicator
-            // keeps the phase active until stop (recall is a no-op here).
-            return messageId || `outbound:${Date.now()}`;
+            return messageId || null;
           } catch (error) {
             logger?.debug(
               `[ActivityFeedback] outbound send failed (${key}):`,
@@ -141,11 +176,8 @@ export function createOutboundEndpointAccess(
             return null;
           }
         },
-        endpoints: {
-          get: (id: string) => (id === endpointId ? endpoint : undefined),
-        },
       };
-      const resolved = { endpoint, adapter: adapter as unknown as Adapter };
+      const resolved = { endpoint, outbound: sendPort };
       cache.set(key, resolved);
       return resolved;
     },
@@ -205,7 +237,7 @@ class GenericPhaseDriver implements PhaseDriver {
   constructor(
     private readonly endpoint: EndpointWithActivityFeedback,
     private readonly platform: string,
-    private readonly adapter: Adapter,
+    private readonly outbound: ActivityFeedbackSendPort,
   ) {}
 
   private async ensureManager(): Promise<ActivityFeedbackManager> {
@@ -215,7 +247,7 @@ class GenericPhaseDriver implements PhaseDriver {
       this.manager = existing;
       return existing;
     }
-    this.manager = enableActivityFeedbackForBot(this.endpoint, this.platform, this.adapter);
+    this.manager = enableActivityFeedbackForBot(this.endpoint, this.platform, this.outbound);
     return this.manager;
   }
 
@@ -248,13 +280,13 @@ class GenericPhaseDriver implements PhaseDriver {
 function createPhaseDriver(
   endpoint: EndpointWithActivityFeedback,
   platform: string,
-  adapter: Adapter,
+  outbound: ActivityFeedbackSendPort,
 ): PhaseDriver {
   const manager = endpoint.$activityFeedback;
   if (manager && !isGenericActivityFeedbackManager(manager)) {
     return new PlatformPhaseDriver(manager);
   }
-  return new GenericPhaseDriver(endpoint, platform, adapter);
+  return new GenericPhaseDriver(endpoint, platform, outbound);
 }
 
 export class ActivityFeedbackExecutor {
@@ -265,23 +297,37 @@ export class ActivityFeedbackExecutor {
     phase: ActivityFeedbackPhase,
     phaseConfig: ResolvedActivityFeedbackPhaseConfig,
   ): Promise<void> {
-    const resolved = this.access.resolve(ctx.platform, ctx.endpointId);
+    const resolved = this.access.resolve(ctx.platform, ctx.endpointKey);
     if (!resolved) return;
-    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.adapter);
+    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.outbound);
     await driver.start(ctx, phase, phaseConfig);
   }
 
   async stop(ctx: ActivityFeedbackEventContext, phase: ActivityFeedbackPhase): Promise<void> {
-    const resolved = this.access.resolve(ctx.platform, ctx.endpointId);
+    const resolved = this.access.resolve(ctx.platform, ctx.endpointKey);
     if (!resolved?.endpoint.$activityFeedback) return;
-    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.adapter);
+    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.outbound);
     await driver.stop(ctx, phase);
   }
 
-  async updateThinkingText(ctx: ActivityFeedbackEventContext, text: string): Promise<void> {
-    const resolved = this.access.resolve(ctx.platform, ctx.endpointId);
+  async updateText(
+    ctx: ActivityFeedbackEventContext,
+    phase: ActivityFeedbackPhase,
+    text: string,
+  ): Promise<void> {
+    const resolved = this.access.resolve(ctx.platform, ctx.endpointKey);
     if (!resolved) return;
-    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.adapter);
-    await driver.updateThinkingText(ctx, text);
+    const driver = createPhaseDriver(resolved.endpoint, ctx.platform, resolved.outbound);
+    const manager = resolved.endpoint.$activityFeedback;
+    if (!manager || !isGenericActivityFeedbackManager(manager)) {
+      if (phase === 'thinking') await driver.updateThinkingText(ctx, text);
+      return;
+    }
+    const indicator = manager.getActiveIndicator(phase, ctx.options);
+    if (indicator?.update) await indicator.update(text);
+  }
+
+  async updateThinkingText(ctx: ActivityFeedbackEventContext, text: string): Promise<void> {
+    await this.updateText(ctx, 'thinking', text);
   }
 }

package/src/index.ts

@@ -4,13 +4,10 @@
  * Pure module exports. Plugin Runtime entry is `plugin.ts`.
  */
 export {
-  bindActivityFeedbackToAIEvents,
   bindActivityFeedbackToAIEventBus,
   createActivityFeedbackAIEventHandlers,
   createActivityFeedbackOrchestrator,
-  createActivityFeedbackOrchestratorFromPlugin,
   createActivityFeedbackOrchestratorForRuntime,
-  mountActivityFeedbackService,
 } from './ai-event-binder.js';
 export { ActivityFeedbackOrchestrator } from './orchestrator.js';
 export { ActivityFeedbackPolicy } from './policy.js';
@@ -23,5 +20,4 @@ export type { ActivityFeedbackEndpointAccess } from './executor.js';
 export {
   createNoopEndpointAccess,
   createOutboundEndpointAccess,
-  createRootEndpointAccess,
 } from './executor.js';

package/src/orchestrator.ts

@@ -1,6 +1,8 @@
 import {
   toActivityFeedbackEventContext,
   isActivityFeedbackEnabled,
+  applySubagentActivityPrefixToConfig,
+  withSubagentActivityPrefix,
   type AIEventPayload,
   type ActivityFeedbackPhase,
 } from '@zhin.js/agent';
@@ -10,6 +12,17 @@ import { ActivityFeedbackPolicy } from './policy.js';
 type Logger = { debug: (msg: string, ...args: unknown[]) => void; error: (msg: string, ...args: unknown[]) => void };
 
 export class ActivityFeedbackOrchestrator {
+  private readonly active = new Map<string, {
+    ctx: NonNullable<ReturnType<typeof toActivityFeedbackEventContext>>;
+    phase: ActivityFeedbackPhase;
+  }>();
+  private readonly transient = new Map<string, {
+    timer: ReturnType<typeof setTimeout>;
+    ctx: NonNullable<ReturnType<typeof toActivityFeedbackEventContext>>;
+    phase: ActivityFeedbackPhase;
+  }>();
+  private readonly pendingCleanup = new Set<Promise<void>>();
+
   constructor(
     private readonly policy: ActivityFeedbackPolicy,
     private readonly executor: ActivityFeedbackExecutor,
@@ -18,16 +31,36 @@ export class ActivityFeedbackOrchestrator {
 
   async startPhase(payload: AIEventPayload, phase: ActivityFeedbackPhase, reason: string): Promise<void> {
     const gatePhase = phase as import('@zhin.js/agent').ActivityFeedbackGatePhase;
-    if (!isActivityFeedbackEnabled(payload, gatePhase)) return;
+    if (!isActivityFeedbackEnabled(payload, gatePhase)) {
+      this.log.debug(
+        `[ActivityFeedback] skip ${phase} (${reason}): gate closed`
+        + ` (eligible=${String(payload.hookContext?.activityFeedbackEligible)})`,
+      );
+      return;
+    }
     const ctx = toActivityFeedbackEventContext(payload);
-    if (!ctx) return;
+    if (!ctx) {
+      this.log.debug(
+        `[ActivityFeedback] skip ${phase} (${reason}): unresolvable context`
+        + ` (platform=${String(payload.platform)} endpoint=${String(payload.endpointKey)})`,
+      );
+      return;
+    }
 
     try {
-      const resolution = this.policy.resolvePhase(ctx.platform, ctx.endpointId, phase, ctx.sceneType);
-      if (resolution.kind !== 'active') return;
+      const resolution = this.policy.resolvePhase(ctx.platform, ctx.endpointKey, phase, ctx.sceneType);
+      if (resolution.kind !== 'active') {
+        this.log.debug(
+          `[ActivityFeedback] skip ${phase} (${reason}): policy=${resolution.kind}`
+          + ` (${ctx.platform}:${ctx.endpointKey} ${ctx.sceneType})`,
+        );
+        return;
+      }
 
+      const config = applySubagentActivityPrefixToConfig(resolution.config, payload);
       this.log.debug(`[ActivityFeedback] start ${phase} (${reason}) session=${ctx.sessionId}`);
-      await this.executor.start(ctx, phase, resolution.config);
+      await this.executor.start(ctx, phase, config);
+      this.active.set(this.phaseKey(ctx, phase), { ctx, phase });
     } catch (error) {
       this.log.error(`[ActivityFeedback] start ${phase} failed (${reason}):`, error);
     }
@@ -36,6 +69,9 @@ export class ActivityFeedbackOrchestrator {
   async stopPhase(payload: AIEventPayload, phase: ActivityFeedbackPhase, reason: string): Promise<void> {
     const ctx = toActivityFeedbackEventContext(payload);
     if (!ctx) return;
+    const key = this.phaseKey(ctx, phase);
+    this.clearTransient(key);
+    this.active.delete(key);
 
     try {
       this.log.debug(`[ActivityFeedback] stop ${phase} (${reason}) session=${ctx.sessionId}`);
@@ -46,13 +82,76 @@ export class ActivityFeedbackOrchestrator {
   }
 
   async updateThinkingText(payload: AIEventPayload, text: string): Promise<void> {
+    await this.updatePhaseText(payload, 'thinking', text);
+  }
+
+  async updatePhaseText(
+    payload: AIEventPayload,
+    phase: ActivityFeedbackPhase,
+    text: string,
+  ): Promise<void> {
     const ctx = toActivityFeedbackEventContext(payload);
     if (!ctx || !text) return;
 
     try {
-      await this.executor.updateThinkingText(ctx, text);
+      await this.executor.updateText(ctx, phase, withSubagentActivityPrefix(text, payload));
     } catch (error) {
-      this.log.error('[ActivityFeedback] thinking update failed:', error);
+      this.log.error(`[ActivityFeedback] ${phase} update failed:`, error);
     }
   }
+
+  async showTransientPhase(
+    payload: AIEventPayload,
+    phase: ActivityFeedbackPhase,
+    reason: string,
+  ): Promise<void> {
+    await this.startPhase(payload, phase, reason);
+    const ctx = toActivityFeedbackEventContext(payload);
+    if (!ctx) return;
+    const resolution = this.policy.resolvePhase(ctx.platform, ctx.endpointKey, phase, ctx.sceneType);
+    if (resolution.kind !== 'active') return;
+    const delay = resolution.config.removeDelay ?? 3_000;
+    const key = this.phaseKey(ctx, phase);
+    this.clearTransient(key);
+    const timer = setTimeout(() => {
+      this.transient.delete(key);
+      this.active.delete(key);
+      const cleanup = this.executor.stop(ctx, phase)
+        .catch((error) => {
+          this.log.error(`[ActivityFeedback] transient ${phase} cleanup failed:`, error);
+        })
+        .finally(() => {
+          this.pendingCleanup.delete(cleanup);
+        });
+      this.pendingCleanup.add(cleanup);
+    }, Math.max(0, delay));
+    timer.unref?.();
+    this.transient.set(key, { timer, ctx, phase });
+  }
+
+  async dispose(): Promise<void> {
+    const pending = [...this.active.values()];
+    const timers = [...this.transient.values()];
+    this.active.clear();
+    this.transient.clear();
+    for (const item of timers) clearTimeout(item.timer);
+    await Promise.allSettled([
+      ...pending.map((item) => this.executor.stop(item.ctx, item.phase)),
+      ...this.pendingCleanup,
+    ]);
+  }
+
+  private phaseKey(
+    ctx: NonNullable<ReturnType<typeof toActivityFeedbackEventContext>>,
+    phase: ActivityFeedbackPhase,
+  ): string {
+    return JSON.stringify([ctx.platform, ctx.endpointKey, ctx.sessionId, phase, ctx.messageId]);
+  }
+
+  private clearTransient(key: string): void {
+    const current = this.transient.get(key);
+    if (!current) return;
+    clearTimeout(current.timer);
+    this.transient.delete(key);
+  }
 }

package/src/policy.ts

@@ -23,7 +23,7 @@ export class ActivityFeedbackPolicy {
 
   resolvePhase(
     platform: string,
-    endpointId: string,
+    endpointKey: string,
     phase: ActivityFeedbackPhase,
     sceneType: ActivitySceneType,
   ): PhaseResolution {
@@ -34,7 +34,8 @@ export class ActivityFeedbackPolicy {
     const policy = mergeActivityFeedbackLayers(
       this.service.defaults,
       this.service.platforms?.[platform],
-      this.service.endpoints?.[`${platform}:${endpointId}`],
+      this.service.endpoints?.[`${platform}:${endpointKey}`],
+      schedulePhaseLayer(this.service, phase),
     );
 
     if (policy?.enabled === false) {
@@ -49,3 +50,18 @@ export class ActivityFeedbackPolicy {
     return { kind: 'active', config };
   }
 }
+
+function schedulePhaseLayer(
+  service: ActivityFeedbackServiceConfig,
+  phase: ActivityFeedbackPhase,
+): import('@zhin.js/agent').ActivityFeedbackConfig | undefined {
+  const scheduleKey = phase === 'schedule_start'
+    ? 'start'
+    : phase === 'schedule_finish'
+      ? 'finish'
+      : phase === 'schedule_error'
+        ? 'error'
+        : undefined;
+  const scenes = scheduleKey ? service.schedule?.phases?.[scheduleKey] : undefined;
+  return scenes ? { phases: { [phase]: scenes } } : undefined;
+}

package/plugin.ts

@@ -1,51 +0,0 @@
-import { definePlugin, outboundHostToken } from '@zhin.js/plugin-runtime';
-import { getLogger } from '@zhin.js/logger';
-import {
-  loadActivityFeedbackServiceConfig,
-  type ActivityFeedbackServiceConfig,
-} from './src/config.js';
-import {
-  bindActivityFeedbackToAIEventBus,
-  createActivityFeedbackOrchestratorForRuntime,
-} from './src/ai-event-binder.js';
-import {
-  createNoopEndpointAccess,
-  createOutboundEndpointAccess,
-} from './src/executor.js';
-
-const logger = getLogger('activity-feedback');
-
-/**
- * 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<ActivityFeedbackServiceConfig>({
-  name: 'activity-feedback',
-  metadata: {
-    displayName: 'Activity Feedback',
-  },
-  setup(context) {
-    const serviceConfig = loadActivityFeedbackServiceConfig(context.config.get());
-    if (serviceConfig.enabled === false) {
-      return;
-    }
-
-    const access = context.resources.has(outboundHostToken)
-      ? createOutboundEndpointAccess(context.resources.use(outboundHostToken), logger)
-      : createNoopEndpointAccess();
-
-    const orchestrator = createActivityFeedbackOrchestratorForRuntime(
-      serviceConfig,
-      logger,
-      access,
-    );
-    const dispose = bindActivityFeedbackToAIEventBus(orchestrator);
-    context.lifecycle.add(() => {
-      logger.debug('[ActivityFeedback] Disposing Runtime AI event binder');
-      dispose();
-    });
-  },
-});