@xmanrui/dsh-im 1.4.0 → 1.5.0

package/src/channels/qq/qq-bridge.mjs

@@ -32,14 +32,11 @@ import {
   prefetchInboundFiles,
 } from '../shared/inbound-file.mjs';
 import {
-  materializeOutboundArtifact,
-  releaseOutboundArtifact,
   trackOutboundArtifactProviderPromise,
 } from '../shared/semantic/artifact.mjs';
+import { deliverOutboundArtifacts } from '../shared/semantic/artifact-delivery.mjs';
 import {
-  createArtifactFailureReceipt,
   createDeliveryReceipt,
-  mergeDeliveryReceipts,
   providerMessageIdsFor,
 } from '../shared/semantic/delivery.mjs';
 import { sendMarkdownReply } from './markdown-reply.mjs';
@@ -210,7 +207,7 @@ function qqArtifactError(error, { dispatched = false } = {}) {
   if (status === 401 || status === 403) wrapped.code = 'artifact-permission-required';
   else if (status === 413) wrapped.code = 'artifact-too-large';
   else if (status === 429) wrapped.code = 'artifact-rate-limited';
-  else if (status === 400 || status === 404) {
+  else if ([400, 404, 405, 406, 410, 415, 422].includes(status)) {
     wrapped.code = 'artifact-provider-rejected';
   } else {
     wrapped.code = dispatched ? 'artifact-delivery-uncertain' : 'artifact-provider-failed';
@@ -245,6 +242,68 @@ function waitWithSignal(promise, signal) {
   });
 }
 
+/** Send one materialized artifact through QQ's native image message. */
+export async function sendQqImage(
+  bot,
+  target,
+  file,
+  { signal, timeoutMs = DEFAULT_FILE_UPLOAD_TIMEOUT_MS } = {},
+) {
+  signal?.throwIfAborted();
+  if (typeof bot?.sendImage !== 'function') {
+    const unavailable = new Error('QQ image delivery is unavailable');
+    unavailable.code = 'artifact-provider-unavailable';
+    throw unavailable;
+  }
+
+  try {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const waitSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    const pending = bot.sendImage(
+      target,
+      { buffer: file.bytes },
+      { onProgress: () => signal?.throwIfAborted() },
+    );
+    trackOutboundArtifactProviderPromise(file, pending);
+    return await waitWithSignal(pending, waitSignal);
+  } catch (error) {
+    if (signal?.aborted) throw abortReason(signal);
+    throw qqArtifactError(error, { dispatched: true });
+  }
+}
+
+async function sendQqFile(
+  bot,
+  target,
+  file,
+  { signal, timeoutMs = DEFAULT_FILE_UPLOAD_TIMEOUT_MS } = {},
+) {
+  signal?.throwIfAborted();
+  if (typeof bot?.sendFile !== 'function') {
+    const unavailable = new Error('QQ file delivery is unavailable');
+    unavailable.code = 'artifact-provider-unavailable';
+    throw unavailable;
+  }
+
+  try {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const waitSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    const pending = bot.sendFile(
+      target,
+      { buffer: file.bytes },
+      {
+        fileName: file.fileName,
+        onProgress: () => signal?.throwIfAborted(),
+      },
+    );
+    trackOutboundArtifactProviderPromise(file, pending);
+    return await waitWithSignal(pending, waitSignal);
+  } catch (error) {
+    if (signal?.aborted) throw abortReason(signal);
+    throw qqArtifactError(error, { dispatched: true });
+  }
+}
+
 function canClaimInteractionReply(message, pending) {
   return pending.questions[pending.index]
     && nonEmptyString(message?.senderId) === pending.actor
@@ -491,80 +550,35 @@ export class QqHarnessBridge {
     if (artifacts.length === 0) {
       return { receipt: baseReceipt, failureNoticeVisible: false };
     }
-    const receipts = baseReceipt ? [baseReceipt] : [];
-    let failureNoticeVisible = false;
-    for (const artifact of artifacts) {
-      this.#signal?.throwIfAborted();
-      try {
-        if (typeof this.#bot.sendFile !== 'function') {
-          const unavailable = new Error('QQ file delivery is unavailable');
-          unavailable.code = 'artifact-provider-unavailable';
-          throw unavailable;
-        }
-        const file = await materializeOutboundArtifact(artifact, {
-          signal: this.#signal,
-        });
-        this.#signal?.throwIfAborted();
-        let result;
-        try {
-          const timeout = AbortSignal.timeout(this.#fileUploadTimeoutMs);
-          const waitSignal = this.#signal ? AbortSignal.any([this.#signal, timeout]) : timeout;
-          const pending = this.#bot.sendFile(
-            target,
-            { buffer: file.bytes },
-            {
-              fileName: file.fileName,
-              onProgress: () => this.#signal?.throwIfAborted(),
-            },
-          );
-          trackOutboundArtifactProviderPromise(file, pending);
-          result = await waitWithSignal(pending, waitSignal);
-        } catch (error) {
-          if (this.#signal?.aborted) throw abortReason(this.#signal);
-          throw qqArtifactError(error, { dispatched: true });
-        }
-        this.#signal?.throwIfAborted();
-        const messageId = nonEmptyString(result?.message?.id);
-        receipts.push(createDeliveryReceipt({
-          deliveryId: file.deliveryKey,
-          presentation: 'qq-file',
-          providerMessageIds: messageId ? [messageId] : [],
-          artifacts: [{ artifactId: file.artifactId, outcome: 'sent' }],
-        }));
-        this.#status.artifactsSent = (this.#status.artifactsSent ?? 0) + 1;
-      } catch (rawError) {
-        if (this.#signal?.aborted) throw rawError;
-        const error = qqArtifactError(rawError);
-        this.#status.artifactSendErrors = (this.#status.artifactSendErrors ?? 0) + 1;
-        this.#logger.warn?.(
-          `[dsh-im:qq] result file delivery failed (${error?.code ?? error?.name ?? 'unknown'})`,
-        );
-        let providerMessageIds = [];
-        try {
-          const notice = await this.#bot.sendText(target, artifactFailureText(artifact?.fileName, error));
-          failureNoticeVisible = true;
-          providerMessageIds = providerMessageIdsFor(notice);
-        } catch (noticeError) {
-          if (this.#signal?.aborted) throw noticeError;
-          this.#logger.warn?.('[dsh-im:qq] unable to send the safe result-file failure notice');
-        }
-        receipts.push(createArtifactFailureReceipt({
-          artifactId: artifact?.artifactId ?? 'unknown',
-          deliveryId: artifact?.deliveryKey ?? artifact?.artifactId ?? 'unknown',
-          error,
-          providerMessageIds,
-        }));
-      } finally {
-        releaseOutboundArtifact(artifact);
-      }
-    }
-    return {
-      receipt: mergeDeliveryReceipts({
-        deliveryId: replyTo,
-        presentation: baseReceipt ? 'qq-text-and-files' : 'qq-files',
-        receipts,
+    const delivery = await deliverOutboundArtifacts({
+      artifacts,
+      baseReceipt,
+      deliveryId: replyTo,
+      aggregatePresentation: baseReceipt ? 'qq-text-and-files' : 'qq-files',
+      alwaysMerge: true,
+      channelKey: 'qq',
+      signal: this.#signal,
+      sendImage: (file) => sendQqImage(this.#bot, target, file, {
+        signal: this.#signal,
+        timeoutMs: this.#fileUploadTimeoutMs,
+      }),
+      sendFile: (file) => sendQqFile(this.#bot, target, file, {
+        signal: this.#signal,
+        timeoutMs: this.#fileUploadTimeoutMs,
       }),
-      failureNoticeVisible,
+      sendFailureNotice: (artifact, error) => this.#bot.sendText(
+        target,
+        artifactFailureText(artifact?.fileName, error),
+      ),
+      logger: this.#logger,
+    });
+    this.#status.artifactsSent = (this.#status.artifactsSent ?? 0)
+      + delivery.artifactsSent;
+    this.#status.artifactSendErrors = (this.#status.artifactSendErrors ?? 0)
+      + delivery.artifactSendErrors;
+    return {
+      receipt: delivery.receipt,
+      failureNoticeVisible: delivery.failureNoticeVisible,
     };
   }
 

package/src/channels/shared/semantic/artifact-delivery.mjs

@@ -0,0 +1,170 @@
+import {
+  materializeOutboundArtifact,
+  releaseOutboundArtifact,
+} from './artifact.mjs';
+import {
+  createArtifactFailureReceipt,
+  createDeliveryReceipt,
+  mergeDeliveryReceipts,
+  providerMessageIdsFor,
+} from './delivery.mjs';
+
+function unavailableError() {
+  const error = new Error('Native file delivery is unavailable');
+  error.code = 'artifact-provider-unavailable';
+  return error;
+}
+
+function isAbort(error, signal) {
+  return signal?.aborted
+    || error?.name === 'AbortError'
+    || error?.code === 'ABORT_ERR';
+}
+
+function providerIds(value) {
+  if (Array.isArray(value)) {
+    return [...new Set(value
+      .filter((candidate) => (
+        (typeof candidate === 'string' && candidate.trim())
+          || Number.isSafeInteger(candidate)
+      ))
+      .map(String))];
+  }
+  return providerMessageIdsFor(value);
+}
+
+async function sendMaterializedArtifact(file, {
+  sendFile,
+  sendImage,
+  signal,
+}) {
+  if (file.mediaType?.startsWith('image/') && typeof sendImage === 'function') {
+    try {
+      return {
+        presentation: 'image',
+        result: await sendImage(file),
+      };
+    } catch (error) {
+      if (isAbort(error, signal) || error?.code === 'artifact-delivery-uncertain') {
+        throw error;
+      }
+    }
+  }
+  signal?.throwIfAborted();
+  if (typeof sendFile !== 'function') throw unavailableError();
+  return {
+    presentation: 'file',
+    result: await sendFile(file),
+  };
+}
+
+/**
+ * Deliver registered artifacts with one shared image-first policy while keeping
+ * provider protocol details inside the channel-supplied send closures.
+ */
+export async function deliverOutboundArtifacts({
+  artifacts = [],
+  baseReceipt = null,
+  deliveryId,
+  aggregatePresentation,
+  alwaysMerge = false,
+  channelKey,
+  signal,
+  sendFile,
+  sendImage,
+  sendFailureNotice,
+  logger,
+}) {
+  const receipts = baseReceipt ? [baseReceipt] : [];
+  let userVisible = Boolean(baseReceipt);
+  let failureNoticeVisible = false;
+  let artifactsSent = 0;
+  let artifactSendErrors = 0;
+
+  let artifactIndex = 0;
+  try {
+    while (artifactIndex < artifacts.length) {
+      const artifact = artifacts[artifactIndex];
+      artifactIndex += 1;
+      try {
+        signal?.throwIfAborted();
+        const file = await materializeOutboundArtifact(artifact, { signal });
+        signal?.throwIfAborted();
+        const sent = await sendMaterializedArtifact(file, {
+          sendFile,
+          sendImage,
+          signal,
+        });
+        signal?.throwIfAborted();
+        receipts.push(createDeliveryReceipt({
+          deliveryId: file.deliveryKey,
+          presentation: `${channelKey}-${sent.presentation}`,
+          providerMessageIds: providerIds(sent.result),
+          artifacts: [{ artifactId: file.artifactId, outcome: 'sent' }],
+        }));
+        artifactsSent += 1;
+        userVisible = true;
+      } catch (error) {
+        if (isAbort(error, signal)) throw error;
+        artifactSendErrors += 1;
+        logger?.warn?.(
+          `[dsh-im:${channelKey}] result artifact delivery failed (${error?.code ?? 'unknown'})`,
+        );
+        let messageIds = [];
+        if (typeof sendFailureNotice === 'function') {
+          try {
+            signal?.throwIfAborted();
+            const notice = await sendFailureNotice(artifact, error);
+            signal?.throwIfAborted();
+            messageIds = providerIds(notice);
+            failureNoticeVisible = true;
+          } catch (noticeError) {
+            if (isAbort(noticeError, signal)) throw noticeError;
+            logger?.warn?.(
+              `[dsh-im:${channelKey}] unable to send the safe artifact failure notice`,
+            );
+          }
+        }
+        const failureReceipt = createArtifactFailureReceipt({
+          artifactId: artifact?.artifactId ?? 'unknown',
+          deliveryId: artifact?.deliveryKey ?? artifact?.artifactId ?? 'unknown',
+          error,
+          providerMessageIds: messageIds,
+        });
+        receipts.push(failureReceipt);
+        if (failureNoticeVisible || failureReceipt.artifacts[0]?.outcome === 'unknown') {
+          userVisible = true;
+        }
+      } finally {
+        releaseOutboundArtifact(artifact);
+      }
+    }
+  } finally {
+    while (artifactIndex < artifacts.length) {
+      releaseOutboundArtifact(artifacts[artifactIndex]);
+      artifactIndex += 1;
+    }
+  }
+
+  let receipt = null;
+  if (receipts.length === 1 && !alwaysMerge) {
+    [receipt] = receipts;
+  } else if (receipts.length > 0) {
+    receipt = mergeDeliveryReceipts({
+      deliveryId: deliveryId
+        ?? baseReceipt?.deliveryId
+        ?? artifacts[0]?.deliveryKey,
+      presentation: aggregatePresentation
+        ?? `${channelKey}-${baseReceipt ? 'text-and-files' : 'files'}`,
+      receipts,
+    });
+  }
+
+  return {
+    receipt,
+    userVisible,
+    failureNoticeVisible,
+    artifactsSent,
+    artifactSendErrors,
+  };
+}

package/src/channels/shared/semantic/artifact.mjs

@@ -576,7 +576,7 @@ export function createOutboundArtifactTool({ registry = outboundArtifactRegistry
   };
   const definition = Object.freeze({
     name: OUTBOUND_ARTIFACT_TOOL,
-    description: 'Send a readable file to the user through the current conversation. Existing and newly created files are both valid.',
+    description: 'Send a readable file or generated image to the user through the current conversation. Existing and newly created files are both valid.',
     parameters: {
       type: 'object',
       additionalProperties: false,
@@ -654,7 +654,7 @@ export function installOutboundArtifactTool(ctx, { registry = outboundArtifactRe
   ctx.systemPrompt.section({
     name: 'dsh-im:return-file',
     order: 115,
-    text: `When the user asks to receive a file, call ${OUTBOUND_ARTIFACT_TOOL} with its path. Existing files can be sent directly; do not recreate or rename a file solely for delivery.`,
+    text: `When the user asks to receive a file or generated image, call ${OUTBOUND_ARTIFACT_TOOL} with its path. Existing files can be sent directly; do not recreate or rename a file solely for delivery.`,
   });
   return true;
 }

package/src/channels/shared/semantic/delivery.mjs

@@ -34,6 +34,8 @@ export function providerMessageIdsFor(value) {
     value.message?.ts,
     value.key?.id,
     value.data?.message_id,
+    value.body?.msgid,
+    value.body?.message_id,
   ];
   const id = candidates.find((candidate) => (
     (typeof candidate === 'string' && candidate.trim())

package/src/channels/shared/text-harness-bridge.mjs

@@ -32,14 +32,9 @@ import {
   harnessQuestionText,
   validHarnessQuestion,
 } from './harness-question.mjs';
+import { deliverOutboundArtifacts } from './semantic/artifact-delivery.mjs';
 import {
-  materializeOutboundArtifact,
-  releaseOutboundArtifact,
-} from './semantic/artifact.mjs';
-import {
-  createArtifactFailureReceipt,
   createDeliveryReceipt,
-  mergeDeliveryReceipts,
   providerMessageIdsFor,
 } from './semantic/delivery.mjs';
 
@@ -339,73 +334,29 @@ export class TextHarnessBridge {
   }
 
   async #deliverArtifacts(target, replyTo, artifacts = [], baseReceipt) {
-    const receipts = baseReceipt ? [baseReceipt] : [];
-    let userVisible = Boolean(baseReceipt);
-    for (const artifact of artifacts) {
-      this.#signal?.throwIfAborted();
-      try {
-        if (typeof this.#bot.sendFile !== 'function') {
-          const unavailable = new Error('Native file delivery is unavailable');
-          unavailable.code = 'artifact-provider-unavailable';
-          throw unavailable;
-        }
-        const file = await materializeOutboundArtifact(artifact, {
-          signal: this.#signal,
-        });
-        this.#signal?.throwIfAborted();
-        const result = await this.#bot.sendFile(target, file);
-        receipts.push(createDeliveryReceipt({
-          deliveryId: file.deliveryKey,
-          presentation: `${this.#descriptor.key}-file`,
-          providerMessageIds: providerMessageIdsFor(result),
-          artifacts: [{ artifactId: file.artifactId, outcome: 'sent' }],
-        }));
-        userVisible = true;
-        this.#status.artifactsSent = (this.#status.artifactsSent ?? 0) + 1;
-      } catch (error) {
-        if (this.#signal?.aborted) throw error;
-        this.#status.artifactSendErrors = (this.#status.artifactSendErrors ?? 0) + 1;
-        this.#logger.warn?.(
-          `[dsh-im:${this.#descriptor.key}] result file delivery failed (${error?.code ?? 'unknown'})`,
-        );
-        let providerMessageIds = [];
-        let noticeSent = false;
-        try {
-          const notice = await this.#bot.sendText(
-            target,
-            artifactFailureText(artifact?.fileName, error, this.#descriptor),
-          );
-          providerMessageIds = providerMessageIdsFor(notice);
-          noticeSent = true;
-        } catch {
-          this.#logger.warn?.(
-            `[dsh-im:${this.#descriptor.key}] unable to send the safe result-file failure notice`,
-          );
-        }
-        const failureReceipt = createArtifactFailureReceipt({
-          artifactId: artifact?.artifactId ?? 'unknown',
-          deliveryId: artifact?.deliveryKey ?? artifact?.artifactId ?? 'unknown',
-          error,
-          providerMessageIds,
-        });
-        receipts.push(failureReceipt);
-        if (noticeSent || failureReceipt.artifacts[0]?.outcome === 'unknown') userVisible = true;
-      } finally {
-        releaseOutboundArtifact(artifact);
-      }
-    }
-    const receipt = receipts.length === 0
-      ? null
-      : receipts.length === 1
-        ? receipts[0]
-        : mergeDeliveryReceipts({
-            deliveryId: replyTo,
-            presentation: baseReceipt
-              ? `${this.#descriptor.key}-text-and-files`
-              : `${this.#descriptor.key}-files`,
-            receipts,
-          });
-    return { receipt, userVisible };
+    const delivery = await deliverOutboundArtifacts({
+      artifacts,
+      baseReceipt,
+      deliveryId: replyTo,
+      channelKey: this.#descriptor.key,
+      signal: this.#signal,
+      sendImage: typeof this.#bot.sendImage === 'function'
+        ? (file) => this.#bot.sendImage(target, file)
+        : undefined,
+      sendFile: typeof this.#bot.sendFile === 'function'
+        ? (file) => this.#bot.sendFile(target, file)
+        : undefined,
+      sendFailureNotice: (artifact, error) => this.#bot.sendText(
+        target,
+        artifactFailureText(artifact?.fileName, error, this.#descriptor),
+      ),
+      logger: this.#logger,
+    });
+    this.#status.artifactsSent = (this.#status.artifactsSent ?? 0)
+      + delivery.artifactsSent;
+    this.#status.artifactSendErrors = (this.#status.artifactSendErrors ?? 0)
+      + delivery.artifactSendErrors;
+    return { receipt: delivery.receipt, userVisible: delivery.userVisible };
   }
 
   async #process(message, messageId, senderId, conversationKey, {

package/src/channels/telegram/telegram-api.mjs

@@ -35,33 +35,33 @@ function preserveProviderMetadata(target, source) {
   return target;
 }
 
-function telegramArtifactProviderError(cause) {
+function telegramArtifactProviderError(cause, mediaLabel = 'document') {
   const providerCode = Number(cause?.providerCode);
   const status = Number(cause?.status);
   const message = cleanString(cause?.message) ?? '';
   let code = 'artifact-provider-rejected';
-  let summary = 'Telegram rejected the document.';
+  let summary = `Telegram rejected the ${mediaLabel}.`;
   if (providerCode === 401 || providerCode === 403 || status === 401 || status === 403) {
     code = 'artifact-permission-required';
-    summary = 'Telegram denied permission to send the document.';
+    summary = `Telegram denied permission to send the ${mediaLabel}.`;
   } else if (providerCode === 413 || status === 413
     || /(?:file|request|entity).{0,20}(?:too (?:big|large)|size limit)|too (?:big|large)/i.test(message)) {
     code = 'artifact-too-large';
-    summary = 'The document exceeds Telegram\'s size limit.';
+    summary = `The ${mediaLabel} exceeds Telegram's size limit.`;
   } else if (providerCode === 429 || status === 429) {
     code = 'artifact-rate-limited';
-    summary = 'Telegram rate-limited document delivery.';
+    summary = `Telegram rate-limited ${mediaLabel} delivery.`;
   } else if (providerCode >= 500 || status >= 500) {
     code = 'artifact-delivery-uncertain';
-    summary = 'Telegram document delivery result is uncertain.';
+    summary = `Telegram ${mediaLabel} delivery result is uncertain.`;
   }
   const error = new Error(summary, { cause });
   error.code = code;
   return preserveProviderMetadata(error, cause);
 }
 
-function uncertainTelegramDelivery(cause) {
-  const error = new Error('Telegram document delivery result is uncertain', { cause });
+function uncertainTelegramDelivery(cause, mediaLabel = 'document') {
+  const error = new Error(`Telegram ${mediaLabel} delivery result is uncertain`, { cause });
   error.code = 'artifact-delivery-uncertain';
   return preserveProviderMetadata(error, cause);
 }
@@ -184,15 +184,41 @@ export class TelegramApi {
   }
 
   async sendDocument({ chatId, file, replyToMessageId, messageThreadId, signal }) {
+    return this.#sendArtifact('sendDocument', 'document', 'document', {
+      chatId,
+      file,
+      replyToMessageId,
+      messageThreadId,
+      signal,
+    });
+  }
+
+  async sendPhoto({ chatId, file, replyToMessageId, messageThreadId, signal }) {
+    return this.#sendArtifact('sendPhoto', 'photo', 'photo', {
+      chatId,
+      file,
+      replyToMessageId,
+      messageThreadId,
+      signal,
+    });
+  }
+
+  async #sendArtifact(method, fieldName, mediaLabel, {
+    chatId,
+    file,
+    replyToMessageId,
+    messageThreadId,
+    signal,
+  }) {
     if (!file || typeof file !== 'object'
       || typeof file.fileName !== 'string' || !file.fileName
       || !Buffer.isBuffer(file.bytes)) {
-      throw new TypeError('A Telegram document is required');
+      throw new TypeError(`A Telegram ${mediaLabel} is required`);
     }
     const payload = new FormData();
     payload.append('chat_id', String(chatId));
     payload.append(
-      'document',
+      fieldName,
       new Blob([file.bytes], { type: file.mediaType ?? 'application/octet-stream' }),
       file.fileName,
     );
@@ -206,7 +232,7 @@ export class TelegramApi {
     if (signal?.aborted) throw abortReason(signal);
     const uploadSignal = requestSignal(signal, this.#fileUploadTimeoutMs);
     try {
-      return await this.#call('sendDocument', payload, {
+      return await this.#call(method, payload, {
         signal: uploadSignal,
         timeoutMs: this.#fileUploadTimeoutMs,
         multipart: true,
@@ -214,9 +240,9 @@ export class TelegramApi {
     } catch (error) {
       if (signal?.aborted) throw abortReason(signal);
       if (error?.code?.startsWith?.('telegram-')) {
-        throw telegramArtifactProviderError(error);
+        throw telegramArtifactProviderError(error, mediaLabel);
       }
-      throw uncertainTelegramDelivery(error);
+      throw uncertainTelegramDelivery(error, mediaLabel);
     }
   }
 

package/src/channels/telegram/telegram-runtime.mjs

@@ -211,6 +211,16 @@ export class TelegramBotClient {
     });
   }
 
+  sendImage(target, file) {
+    return this.#api.sendPhoto({
+      chatId: target.chatId,
+      file,
+      replyToMessageId: target.replyToMessageId,
+      messageThreadId: target.messageThreadId,
+      signal: this.#signal,
+    });
+  }
+
   async openStream(target) {
     const stream = createEditableMessageStream({
       limit: 4_000,