@soimy/dingtalk 3.5.2 → 3.6.0

package/src/reply-strategy-markdown.ts

@@ -6,7 +6,7 @@
  * Reasoning display is intentionally unsupported on DingTalk markdown.
  */
 
-import type { DeliverPayload, ReplyOptions, ReplyStrategy, ReplyStrategyContext } from "./reply-strategy";
+import type { DeliverPayload, ReplyOptions, ReplyStrategy, ReplyStrategyContext } from "./reply-strategy-types";
 import { sendMessage } from "./send-service";
 
 const EMPTY_FINAL_FALLBACK_TEXT = "✅ Done";
@@ -119,7 +119,7 @@ export function createMarkdownReplyStrategy(
 
     async deliver(payload: DeliverPayload): Promise<void> {
       if (payload.mediaUrls.length > 0) {
-        await ctx.deliverMedia(payload.mediaUrls);
+        await ctx.deliverMedia(payload.mediaUrls, { audioAsVoice: payload.audioAsVoice });
         sentVisibleContent = true;
       }
 

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,66 +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 ------------------------------------------------
-
-export interface DeliverPayload {
-  text?: string;
-  mediaUrls: string[];
-  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: DingTalkConfig;
-  to: string;
-  sessionWebhook: string;
-  senderId: string;
-  isDirect: boolean;
-  accountId: string;
-  storePath: string;
-  disableBlockStreaming?: boolean;
-  sessionKey?: string;
-  sessionAgentId?: string;
-  groupId?: string;
-  log?: Logger;
-  replyQuotedRef?: QuotedRef;
-  deliverMedia: (urls: string[]) => 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) {
@@ -212,6 +242,14 @@ function extractErrorCodeFromResponseData(data: unknown): string | null {
   }
 
   const payload = data as Record<string, unknown>;
+  const errcode = payload.errcode;
+  if (typeof errcode === "number" && Number.isFinite(errcode)) {
+    return String(errcode);
+  }
+  if (typeof errcode === "string" && errcode.trim()) {
+    return errcode.trim();
+  }
+
   const code = payload.code;
   if (typeof code === "string" && code.trim()) {
     return code.trim();
@@ -225,6 +263,62 @@ function extractErrorCodeFromResponseData(data: unknown): string | null {
   return null;
 }
 
+function summarizeSessionWebhookResponse(data: unknown): string {
+  if (!data || typeof data !== "object") {
+    return `type=${typeof data}`;
+  }
+  const payload = data as Record<string, unknown>;
+  const code = extractErrorCodeFromResponseData(payload) || "(none)";
+  const message = firstTrimmedString(
+    payload.message,
+    payload.errmsg,
+    payload.msg,
+    payload.errorMessage,
+  ) || "(none)";
+  const success =
+    typeof payload.success === "boolean"
+      ? String(payload.success)
+      : typeof payload.result === "boolean"
+        ? String(payload.result)
+        : "(none)";
+  const delivery = extractOutboundDeliveryMetadata(payload);
+  return (
+    `success=${success} code=${code} message=${message} ` +
+    `messageId=${delivery.messageId || "(none)"} ` +
+    `processQueryKey=${delivery.processQueryKey || "(none)"} ` +
+    `outTrackId=${delivery.outTrackId || "(none)"}`
+  );
+}
+
+function ensureSessionWebhookBusinessSuccess(
+  data: unknown,
+  context: { msgtype: string },
+): void {
+  if (!data || typeof data !== "object") {
+    return;
+  }
+  const payload = data as Record<string, unknown>;
+  const code = extractErrorCodeFromResponseData(payload);
+  const message = firstTrimmedString(
+    payload.message,
+    payload.errmsg,
+    payload.msg,
+    payload.errorMessage,
+  ) || "unknown error";
+
+  const hasFailureSuccessFlag = payload.success === false || payload.result === false;
+  const hasFailureCode = typeof code === "string" && code !== "" && code !== "0";
+  if (!hasFailureSuccessFlag && !hasFailureCode) {
+    return;
+  }
+
+  const reason = [
+    code && code !== "0" ? `code=${code}` : "",
+    message !== "unknown error" ? `message=${message}` : "",
+  ].filter(Boolean).join(" ");
+  throw new Error(`Session webhook ${context.msgtype} send failed${reason ? `: ${reason}` : ""}`);
+}
+
 function isProactivePermissionOrScopeError(code: string | null): boolean {
   if (!code) {
     return false;
@@ -389,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 {
@@ -400,7 +494,7 @@ export async function sendProactiveMedia(
     if (!uploadResult) {
       return { ok: false, error: "Failed to upload media" };
     }
-    const { mediaId, buffer } = uploadResult;
+    const { mediaId, buffer, durationMs: uploadedDurationMs } = uploadResult;
 
     const token = await getAccessToken(config, log);
     const { targetId, isExplicitUser } = stripTargetPrefix(target);
@@ -421,7 +515,8 @@ export async function sendProactiveMedia(
       msgParam = JSON.stringify({ photoURL: mediaId });
     } else if (mediaType === "voice") {
       msgKey = "sampleAudio";
-      const durationMs = await getVoiceDurationMs(mediaPath, mediaType, log, { preReadBuffer: buffer });
+      const durationMs = uploadedDurationMs
+        ?? await getVoiceDurationMs(mediaPath, mediaType, log, { preReadBuffer: buffer });
       msgParam = JSON.stringify({ mediaId, duration: String(durationMs) });
     } else {
       // sampleVideo requires picMediaId; fallback to sampleFile for broader compatibility.
@@ -476,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);
@@ -540,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,
@@ -555,14 +732,18 @@ export async function sendBySession(
       mediaLocalRoots: options.mediaLocalRoots,
     });
     if (uploadResult) {
-      const { mediaId, buffer } = uploadResult;
+      const { mediaId, buffer, durationMs: uploadedDurationMs } = uploadResult;
       let body: any;
 
       if (options.mediaType === "image") {
         body = { msgtype: "image", image: { media_id: mediaId } };
       } else if (options.mediaType === "voice") {
-        const durationMs = await getVoiceDurationMs(options.mediaPath, options.mediaType, log, { preReadBuffer: buffer });
+        const durationMs = uploadedDurationMs
+          ?? await getVoiceDurationMs(options.mediaPath, options.mediaType, log, { preReadBuffer: buffer });
         body = { msgtype: "voice", voice: { media_id: mediaId, duration: String(durationMs) } };
+        log?.debug?.(
+          `[DingTalk] Sending session voice message mediaId=${mediaId} durationMs=${durationMs}`,
+        );
       } else if (options.mediaType === "video") {
         body = { msgtype: "video", video: { media_id: mediaId } };
       } else if (options.mediaType === "file") {
@@ -577,6 +758,17 @@ export async function sendBySession(
           headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
           ...getProxyBypassOption(config),
         });
+        log?.debug?.(
+          `[DingTalk] Session webhook response msgtype=${body.msgtype} ${summarizeSessionWebhookResponse(result.data)}`,
+        );
+        ensureSessionWebhookBusinessSuccess(result.data, { msgtype: body.msgtype });
+        const delivery = extractOutboundDeliveryMetadata(result.data);
+        if (!delivery.messageId && !delivery.processQueryKey && !delivery.outTrackId) {
+          log?.warn?.(
+            `[DingTalk] Session webhook ${body.msgtype} response missing delivery metadata; ` +
+            summarizeSessionWebhookResponse(result.data),
+          );
+        }
         return result.data;
       }
     } else {
@@ -624,6 +816,10 @@ export async function sendBySession(
       headers: { "x-acs-dingtalk-access-token": token, "Content-Type": "application/json" },
       ...getProxyBypassOption(config),
     });
+    log?.debug?.(
+      `[DingTalk] Session webhook response msgtype=${body.msgtype} ${summarizeSessionWebhookResponse(result.data)}`,
+    );
+    ensureSessionWebhookBusinessSuccess(result.data, { msgtype: body.msgtype });
     lastResult = result.data;
   }
   return lastResult;
@@ -662,6 +858,28 @@ export async function sendMessage(
       }
     }
 
+    if (options.sessionWebhook && options.mediaPath && options.mediaType === "voice") {
+      log?.debug?.(
+        "[DingTalk] Session webhook does not support voice replies reliably; " +
+        "using proactive media API for this voice response",
+      );
+      const proactiveVoiceResult = await sendProactiveMedia(
+        config,
+        conversationId,
+        options.mediaPath,
+        options.mediaType,
+        options,
+      );
+      if (!proactiveVoiceResult.ok) {
+        return { ok: false, error: proactiveVoiceResult.error || "Voice reply send failed" };
+      }
+      return {
+        ok: true,
+        data: proactiveVoiceResult.data,
+        messageId: proactiveVoiceResult.messageId,
+      };
+    }
+
     if (options.sessionWebhook) {
       const data = await sendBySession(config, options.sessionWebhook, text, options);
       const delivery = extractOutboundDeliveryMetadata(data);

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;
+}