@soimy/dingtalk 3.5.3 → 3.6.0

package/src/reply-strategy-types.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared type definitions for reply strategy implementations.
+ *
+ * Extracted into a leaf module so that the factory (reply-strategy.ts) and
+ * concrete strategies (reply-strategy-card.ts, reply-strategy-markdown.ts)
+ * can share these interfaces without circular imports.
+ */
+
+import type { GetReplyOptions } from "openclaw/plugin-sdk/reply-runtime";
+import type { DingTalkConfig, Logger, QuotedRef } from "./types";
+
+// ---- Internal helper type ----
+
+export type InternalReplyStrategyConfig = DingTalkConfig & {
+  /** @deprecated Internal compatibility only. Removed from public config surface. */
+  cardStreamReasoning?: boolean;
+};
+
+// ---- Public interfaces ----
+
+export interface DeliverPayload {
+  text?: string;
+  mediaUrls: string[];
+  /**
+   * Shared reply-runtime voice hint. Strategies forward this unchanged into the
+   * channel media delivery helper; inbound-handler is responsible for bridging
+   * legacy aliases (for example `asVoice`) into this single field.
+   */
+  audioAsVoice?: boolean;
+  kind: "block" | "final" | "tool";
+  isReasoning?: boolean;
+}
+
+export interface ReplyOptions {
+  disableBlockStreaming: boolean;
+  onPartialReply?: (payload: { text?: string }) => void | Promise<void>;
+  onReasoningStream?: (payload: { text?: string }) => void | Promise<void>;
+  onAssistantMessageStart?: () => void | Promise<void>;
+  onAgentRunStart?: GetReplyOptions["onAgentRunStart"];
+  onModelSelected?: GetReplyOptions["onModelSelected"];
+}
+
+export interface ReplyStrategy {
+  /** Options forwarded to the runtime dispatcher. */
+  getReplyOptions(): ReplyOptions;
+
+  /** Called by the deliver callback for each payload chunk. */
+  deliver(payload: DeliverPayload): Promise<void>;
+
+  /** Called after dispatch completes successfully. */
+  finalize(): Promise<void>;
+
+  /** Called when dispatch throws an error. */
+  abort(error: Error): Promise<void>;
+
+  /** Last known final text (for external consumers such as logging). */
+  getFinalText(): string | undefined;
+}
+
+/** Shared context passed to every strategy implementation. */
+export interface TaskMeta {
+  model?: string;
+  effort?: string;
+  usage?: number;
+  elapsedMs?: number;
+  agent?: string;
+  runIds?: Set<string>;
+}
+
+export interface ReplyStrategyContext {
+  config: InternalReplyStrategyConfig;
+  to: string;
+  sessionWebhook: string;
+  senderId: string;
+  isDirect: boolean;
+  accountId: string;
+  storePath: string;
+  disableBlockStreaming?: boolean;
+  sessionKey?: string;
+  sessionAgentId?: string;
+  groupId?: string;
+  log?: Logger;
+  replyQuotedRef?: QuotedRef;
+  /**
+   * Channel-level media delivery hook. The `audioAsVoice` option is the same
+   * shared voice semantic carried on DeliverPayload, not a second independent
+   * config knob.
+   */
+  deliverMedia: (urls: string[], options?: { audioAsVoice?: boolean }) => Promise<void>;
+  isStopRequested?: () => boolean;
+  inboundText?: string;
+  taskMeta?: TaskMeta;
+}

package/src/reply-strategy-with-reaction.ts

@@ -24,7 +24,7 @@
  * concurrently. The `sessionFilter` parameter is required for this reason.
  */
 
-import type { DeliverPayload, ReplyOptions, ReplyStrategy } from "./reply-strategy";
+import type { DeliverPayload, ReplyOptions, ReplyStrategy } from "./reply-strategy-types";
 import type { DingTalkConfig, Logger } from "./types";
 
 const TOOL_REACTION_SILENCE_MS = 55_000;

package/src/reply-strategy.ts

@@ -1,82 +1,24 @@
 /**
- * Reply strategy interface for DingTalk message delivery.
+ * Reply strategy factory for DingTalk message delivery.
  *
- * Abstracts the "how to deliver a reply" concern away from
- * handleDingTalkMessage, so card and markdown modes each manage
- * their own state and lifecycle independently.
+ * Delegates the "how to deliver a reply" concern to card or markdown
+ * strategy implementations. Type definitions live in reply-strategy-types.ts.
  */
 
-import type { AICardInstance, DingTalkConfig, Logger, QuotedRef } from "./types";
+import type { AICardInstance } from "./types";
+import type { ReplyStrategy, ReplyStrategyContext } from "./reply-strategy-types";
 import { createCardReplyStrategy } from "./reply-strategy-card";
 import { createMarkdownReplyStrategy } from "./reply-strategy-markdown";
 
-// ---- Public types ------------------------------------------------
-
-type InternalReplyStrategyConfig = DingTalkConfig & {
-  /** @deprecated Internal compatibility only. Removed from public config surface. */
-  cardStreamReasoning?: boolean;
-};
-
-export interface DeliverPayload {
-  text?: string;
-  mediaUrls: string[];
-  /**
-   * Shared reply-runtime voice hint. Strategies forward this unchanged into the
-   * channel media delivery helper; inbound-handler is responsible for bridging
-   * legacy aliases (for example `asVoice`) into this single field.
-   */
-  audioAsVoice?: boolean;
-  kind: "block" | "final" | "tool";
-  isReasoning?: boolean;
-}
-
-export interface ReplyOptions {
-  disableBlockStreaming: boolean;
-  onPartialReply?: (payload: { text?: string }) => void | Promise<void>;
-  onReasoningStream?: (payload: { text?: string }) => void | Promise<void>;
-  onAssistantMessageStart?: () => void | Promise<void>;
-}
-
-export interface ReplyStrategy {
-  /** Options forwarded to the runtime dispatcher. */
-  getReplyOptions(): ReplyOptions;
-
-  /** Called by the deliver callback for each payload chunk. */
-  deliver(payload: DeliverPayload): Promise<void>;
-
-  /** Called after dispatch completes successfully. */
-  finalize(): Promise<void>;
-
-  /** Called when dispatch throws an error. */
-  abort(error: Error): Promise<void>;
-
-  /** Last known final text (for external consumers such as logging). */
-  getFinalText(): string | undefined;
-}
-
-/** Shared context passed to every strategy implementation. */
-export interface ReplyStrategyContext {
-  config: InternalReplyStrategyConfig;
-  to: string;
-  sessionWebhook: string;
-  senderId: string;
-  isDirect: boolean;
-  accountId: string;
-  storePath: string;
-  disableBlockStreaming?: boolean;
-  sessionKey?: string;
-  sessionAgentId?: string;
-  groupId?: string;
-  log?: Logger;
-  replyQuotedRef?: QuotedRef;
-  /**
-   * Channel-level media delivery hook. The `audioAsVoice` option is the same
-   * shared voice semantic carried on DeliverPayload, not a second independent
-   * config knob.
-   */
-  deliverMedia: (urls: string[], options?: { audioAsVoice?: boolean }) => Promise<void>;
-  isStopRequested?: () => boolean;
-}
+// Re-export all types so existing consumers that import from "./reply-strategy"
+// continue to work without changes beyond the ones we explicitly migrate.
+export type {
+  DeliverPayload,
+  ReplyOptions,
+  ReplyStrategy,
+  ReplyStrategyContext,
+  TaskMeta,
+} from "./reply-strategy-types";
 
 // ---- Factory -----------------------------------------------------
 

package/src/run-usage-store.ts

@@ -0,0 +1,59 @@
+export interface UsageAccumulation {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  total?: number;
+}
+
+const usageStore = new Map<string, UsageAccumulation>();
+
+export function recordRunStart(runId: string): void {
+  if (!usageStore.has(runId)) {
+    usageStore.set(runId, {});
+  }
+}
+
+export function accumulateUsage(runId: string, usage: UsageAccumulation): void {
+  const existing = usageStore.get(runId);
+  if (!existing) { return; }
+
+  for (const field of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
+    const value = usage[field];
+    if (typeof value === "number") {
+      existing[field] = (existing[field] ?? 0) + value;
+    }
+  }
+}
+
+export function getUsageByRunId(runId: string): UsageAccumulation | undefined {
+  return usageStore.get(runId);
+}
+
+export function getAggregatedUsage(runIds: Set<string> | undefined): UsageAccumulation {
+  const result: UsageAccumulation = {};
+  if (!runIds) { return result; }
+  for (const runId of runIds) {
+    const usage = usageStore.get(runId);
+    if (!usage) { continue; }
+    for (const field of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
+      if (typeof usage[field] === "number") {
+        result[field] = (result[field] ?? 0) + usage[field];
+      }
+    }
+  }
+  return result;
+}
+
+export function clearRun(runId: string | undefined): void {
+  if (runId) { usageStore.delete(runId); }
+}
+
+export function clearRuns(runIds: Set<string> | undefined): void {
+  if (!runIds) { return; }
+  for (const runId of runIds) { usageStore.delete(runId); }
+}
+
+export function clearAllForTest(): void {
+  usageStore.clear();
+}

package/src/send-service.ts

@@ -1,13 +1,20 @@
 import * as path from "node:path";
 import axios from "./http-client";
 import { getAccessToken } from "./auth";
+import { resolveCardRunByConversation, resolveCardRunByOwner } from "./card/card-run-registry";
+
 import {
   isCardInTerminalState,
   sendProactiveCardText,
 } from "./card-service";
 import { resolveRobotCode, stripTargetPrefix } from "./config";
 import { getLogger } from "./logger-context";
-import { getVoiceDurationMs, uploadMedia as uploadMediaUtil } from "./media-utils";
+import {
+  getVoiceDurationMs,
+  prepareMediaInput,
+  resolveOutboundMediaType,
+  uploadMedia as uploadMediaUtil,
+} from "./media-utils";
 import { convertMarkdownTablesToPlainText, detectMarkdownAndExtractTitle } from "./message-utils";
 import {
   DEFAULT_MESSAGE_CONTEXT_TTL_DAYS,
@@ -176,6 +183,29 @@ function buildPersistedOutboundText(text: string, options: SendMessageOptions):
 }
 
 const DINGTALK_TEXT_CHUNK_LIMIT = 3800;
+const CARD_MEDIA_CONTROLLER_ATTACH_WAIT_MS = 150;
+const CARD_MEDIA_CONTROLLER_ATTACH_POLL_MS = 25;
+
+async function waitForCardControllerAttachment(
+  activeRun: ReturnType<typeof resolveCardRunByConversation>,
+): Promise<NonNullable<ReturnType<typeof resolveCardRunByConversation>>["controller"] | null> {
+  if (!activeRun) {
+    return null;
+  }
+  if (activeRun.controller?.appendImageBlock) {
+    return activeRun.controller;
+  }
+
+  const deadline = Date.now() + CARD_MEDIA_CONTROLLER_ATTACH_WAIT_MS;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, CARD_MEDIA_CONTROLLER_ATTACH_POLL_MS));
+    if (activeRun.controller?.appendImageBlock) {
+      return activeRun.controller;
+    }
+  }
+
+  return activeRun.controller?.appendImageBlock ? activeRun.controller : null;
+}
 
 function splitMarkdownChunks(text: string, limit = DINGTALK_TEXT_CHUNK_LIMIT): string[] {
   if (!text || text.length <= limit) {
@@ -453,7 +483,7 @@ export async function sendProactiveMedia(
   mediaPath: string,
   mediaType: "image" | "voice" | "video" | "file",
   options: SendMessageOptions & { accountId?: string } = {},
-): Promise<{ ok: boolean; error?: string; data?: any; messageId?: string }> {
+): Promise<{ ok: boolean; error?: string; data?: any; messageId?: string; mediaId?: string }> {
   const log = options.log || getLogger();
 
   try {
@@ -541,7 +571,7 @@ export async function sendProactiveMedia(
         kind: "proactive-media",
       },
     });
-    return { ok: true, data: result.data, messageId };
+    return { ok: true, data: result.data, messageId, mediaId };
   } catch (err: any) {
     log?.error?.(`[DingTalk] Failed to send proactive media: ${err.message}`);
     const normalizedTarget = resolveOriginalPeerId(stripTargetPrefix(target).targetId);
@@ -605,6 +635,88 @@ export async function sendProactiveMedia(
   }
 }
 
+export async function sendMedia(
+  config: DingTalkConfig,
+  target: string,
+  mediaInput: string,
+  options: SendMessageOptions & {
+    mediaType?: "image" | "voice" | "video" | "file";
+    audioAsVoice?: boolean;
+    expectedCardOwnerId?: string;
+  } = {},
+): Promise<{ ok: boolean; error?: string; data?: any; messageId?: string; mediaId?: string }> {
+  const log = options.log || getLogger();
+  let preparedMedia: Awaited<ReturnType<typeof prepareMediaInput>> | undefined;
+
+  try {
+    preparedMedia = await prepareMediaInput(mediaInput, log, config.mediaUrlAllowlist);
+    const mediaPath = preparedMedia.cleanup
+      ? preparedMedia.path
+      : path.resolve(process.cwd(), preparedMedia.path);
+    const mediaType = resolveOutboundMediaType({
+      mediaType: options.mediaType,
+      mediaPath,
+      asVoice: options.audioAsVoice === true,
+    });
+
+    if (config.messageType === "card" && mediaType === "image") {
+      const accountId = options.accountId ?? "default";
+
+      // Three-tier lookup strategy to handle sessionKey=- from runtime:
+      // 1. If conversationId is available: try owner-filtered then conversation-only
+      // 2. If conversationId is undefined but owner is provided: try owner-only lookup
+      // 3. Otherwise: no active card found
+      let activeRun = null;
+
+      if (options.conversationId) {
+        // conversationId explicitly provided (parsed from sessionKey)
+        activeRun = options.expectedCardOwnerId
+          ? resolveCardRunByConversation(accountId, options.conversationId, {
+              ownerUserId: options.expectedCardOwnerId,
+            }) ?? resolveCardRunByConversation(accountId, options.conversationId, undefined)
+          : resolveCardRunByConversation(accountId, options.conversationId, undefined);
+      } else if (options.expectedCardOwnerId) {
+        // Fallback: when sessionKey=- causes conversationId to be undefined,
+        // try owner-only matching as last resort
+        activeRun = resolveCardRunByOwner(accountId, options.expectedCardOwnerId);
+        if (activeRun) {
+          log?.debug?.(
+            `[DingTalk] Matched active card by owner-only lookup (conversationId unavailable) ` +
+            `accountId=${accountId} ownerUserId=${options.expectedCardOwnerId} outTrackId=${activeRun.outTrackId}`,
+          );
+        }
+      }
+
+      const uploadResult = await uploadMedia(config, mediaPath, "image", log, {
+        mediaLocalRoots: options.mediaLocalRoots,
+      });
+      if (!uploadResult?.mediaId) {
+        return { ok: false, error: "Failed to upload media" };
+      }
+
+      const activeController = await waitForCardControllerAttachment(activeRun);
+      if (activeController?.appendImageBlock) {
+        await activeController.appendImageBlock(uploadResult.mediaId);
+        return { ok: true, mediaId: uploadResult.mediaId };
+      }
+
+      if (activeRun) {
+        log?.debug?.(
+          `[DingTalk] Active card matched but controller was not attached in time; fallback to proactive media send`,
+        );
+      } else {
+        log?.debug?.(
+          `[DingTalk] No active card found for media embedding; fallback to proactive media send`,
+        );
+      }
+    }
+
+    return await sendProactiveMedia(config, target, mediaPath, mediaType, options);
+  } finally {
+    await preparedMedia?.cleanup?.();
+  }
+}
+
 export async function sendBySession(
   config: DingTalkConfig,
   sessionWebhook: string,

package/src/session-state.ts

@@ -0,0 +1,62 @@
+interface SessionState {
+  model?: string;
+  effort?: string;
+  taskStartTime: number;
+}
+
+const sessionStore = new Map<string, SessionState>();
+
+function sessionKey(accountId: string, conversationId: string): string {
+  return `${accountId}:${conversationId}`;
+}
+
+export function initSessionState(accountId: string, conversationId: string): SessionState {
+  const key = sessionKey(accountId, conversationId);
+  const existing = sessionStore.get(key);
+  if (existing) {
+    existing.taskStartTime = Date.now();
+    return existing;
+  }
+  const state: SessionState = {
+    taskStartTime: Date.now(),
+  };
+  sessionStore.set(key, state);
+  return state;
+}
+
+export function getSessionState(accountId: string, conversationId: string): SessionState | undefined {
+  return sessionStore.get(sessionKey(accountId, conversationId));
+}
+
+export function updateSessionState(
+  accountId: string,
+  conversationId: string,
+  patch: Partial<Pick<SessionState, "model" | "effort">>,
+): void {
+  const state = sessionStore.get(sessionKey(accountId, conversationId));
+  if (!state) {
+    return;
+  }
+  if (patch.model !== undefined) {
+    state.model = patch.model;
+  }
+  if (patch.effort !== undefined) {
+    state.effort = patch.effort;
+  }
+}
+
+export function getTaskTimeSeconds(accountId: string, conversationId: string): number | undefined {
+  const state = sessionStore.get(sessionKey(accountId, conversationId));
+  if (!state) {
+    return undefined;
+  }
+  return Math.round((Date.now() - state.taskStartTime) / 1000);
+}
+
+export function clearSessionState(accountId: string, conversationId: string): void {
+  sessionStore.delete(sessionKey(accountId, conversationId));
+}
+
+export function clearAllSessionStatesForTest(): void {
+  sessionStore.clear();
+}

package/src/targeting/agent-name-matcher.ts

@@ -146,3 +146,31 @@ export function resolveAtAgents(
     hasInvalidAgentNames,
   };
 }
+
+/**
+ * Get agent display name for statusLine in card template.
+ *
+ * Priority:
+ * 1. subAgentOptions.matchedName - user-friendly name from @mention (e.g., "代码专家")
+ * 2. agents.list lookup - name field from agent config
+ * 3. agentId fallback - technical identifier
+ */
+export function getAgentDisplayName(params: {
+  subAgentOptions?: { matchedName?: string };
+  agentId: string;
+  agentsList?: Array<{ id: string; name?: string }>;
+}): string {
+  // Priority 1: sub-agent matchedName (user-friendly)
+  if (params.subAgentOptions?.matchedName) {
+    return params.subAgentOptions.matchedName;
+  }
+  // Priority 2: lookup from agents.list
+  if (params.agentsList) {
+    const agent = params.agentsList.find((a) => a.id === params.agentId);
+    if (agent?.name) {
+      return agent.name;
+    }
+  }
+  // Priority 3: fallback to agentId
+  return params.agentId;
+}