@zhin.js/service-activity-feedback 3.0.14 → 3.0.16

package/src/executor.ts

@@ -1,5 +1,4 @@
-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 { 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） */
@@ -7,7 +6,7 @@ export interface ActivityFeedbackEndpointAccess {
   resolve(
     platform: string,
     endpointKey: string,
-  ): { endpoint: EndpointWithActivityFeedback; adapter: Adapter } | undefined;
+  ): { endpoint: EndpointWithActivityFeedback; outbound: ActivityFeedbackSendPort } | undefined;
 }
 
 /** Slice-2: no Adapter inject — executor start/stop no-op when resolve returns undefined. */
@@ -42,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:endpointKey 缓存 { endpoint, adapter }：activity manager 挂在
+ * 按 platform:endpointKey 缓存 { endpoint, outbound }：activity manager 挂在
  * endpoint.$activityFeedback 上，start/stop 必须解析到同一个对象，否则
  * stop 时拿不到 manager，typing 指示器永远无法停止。
  */
@@ -50,19 +49,27 @@ 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, endpointKey) {
-      const key = `${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: endpointKey,
         control: {
-          ...(recall ? {
+          ...(recall && supports('recall') ? {
             recall: async (message: Parameters<typeof recall>[0]['message']) => {
               try {
                 await recall({ adapter: platform, endpointKey, message });
@@ -74,7 +81,23 @@ export function createOutboundEndpointAccess(
               }
             },
           } : {}),
-          ...(addReaction ? {
+          ...(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,
@@ -98,44 +121,53 @@ export function createOutboundEndpointAccess(
               }
             },
           } : {}),
-          ...(removeReaction ? {
+          ...(removeReaction && supports('reaction') ? {
             removeReaction: async (
               message: Parameters<typeof removeReaction>[0]['message'],
               reactionId: string,
             ) => {
-              void Promise.resolve(
-                removeReaction({ adapter: platform, endpointKey, message, reactionId }),
-              ).catch((error) => {
+              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),
+                );
+              }
             },
           } : {}),
         },
       } 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,
               endpointKey,
               conversation: {
-                kind: (options.type as 'private' | 'group' | 'channel' | undefined) || 'private',
-                id: options.id,
+                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}):`,
@@ -144,11 +176,8 @@ export function createOutboundEndpointAccess(
             return null;
           }
         },
-        endpoints: {
-          get: (id: string) => (id === endpointKey ? endpoint : undefined),
-        },
       };
-      const resolved = { endpoint, adapter: adapter as unknown as Adapter };
+      const resolved = { endpoint, outbound: sendPort };
       cache.set(key, resolved);
       return resolved;
     },
@@ -208,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> {
@@ -218,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;
   }
 
@@ -251,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 {
@@ -270,21 +299,35 @@ export class ActivityFeedbackExecutor {
   ): Promise<void> {
     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.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> {
+  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/orchestrator.ts

@@ -12,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,
@@ -49,6 +60,7 @@ export class ActivityFeedbackOrchestrator {
       const config = applySubagentActivityPrefixToConfig(resolution.config, payload);
       this.log.debug(`[ActivityFeedback] start ${phase} (${reason}) session=${ctx.sessionId}`);
       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);
     }
@@ -57,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}`);
@@ -67,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, withSubagentActivityPrefix(text, payload));
+      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

@@ -35,6 +35,7 @@ export class ActivityFeedbackPolicy {
       this.service.defaults,
       this.service.platforms?.[platform],
       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;
+}