feat: add native result-file delivery

src/channels/feishu/feishu-channel.mjs

@@ -1,6 +1,22 @@
+import { createHash } from 'node:crypto';
+
+import { trackOutboundArtifactProviderPromise } from '../shared/semantic/artifact.mjs';
+import { createDeliveryReceipt } from '../shared/semantic/delivery.mjs';
+
 const STREAM_ELEMENT_ID = 'stream_md';
 const DEFAULT_INITIAL_TEXT = '已连接 DeepSeek Harness，正在思考…';
 const MAX_STREAM_CHARS = 28000;
+const MAX_FILE_OPERATION_TIMEOUT_MS = 120_000;
+
+const FILE_DELIVERY_ERRORS = new Map([
+  [99991672, ['artifact-permission-required', 'Feishu file delivery requires the im:resource permission.']],
+  [234006, ['artifact-too-large', 'The result file exceeds Feishu\'s size limit.']],
+  [234010, ['artifact-empty', 'Feishu does not accept empty files.']],
+  [230017, ['artifact-provider-rejected', 'Feishu rejected the uploaded file ownership.']],
+  [230020, ['artifact-rate-limited', 'Feishu temporarily rate-limited file delivery.']],
+  [230049, ['artifact-delivery-uncertain', 'Feishu could not confirm the file message result.']],
+  [230055, ['artifact-provider-rejected', 'Feishu rejected the file message type.']],
+]);
 
 function assertApiSuccess(operation, response) {
   if (response?.code && response.code !== 0) {
@@ -9,6 +25,103 @@ function assertApiSuccess(operation, response) {
   return response;
 }
 
+function providerErrorCode(cause) {
+  const pending = [cause];
+  const seen = new Set();
+  let fallback;
+  while (pending.length > 0) {
+    const value = pending.shift();
+    if (!value || seen.has(value)) continue;
+    if (typeof value === 'object') seen.add(value);
+    if (Array.isArray(value)) {
+      pending.push(...value);
+      continue;
+    }
+    const code = Number(value?.code);
+    if (Number.isFinite(code) && code !== 0) {
+      if (FILE_DELIVERY_ERRORS.has(code)) return code;
+      fallback ??= code;
+    }
+    pending.push(value?.response?.data, value?.data, value?.error, value?.cause);
+  }
+  return fallback;
+}
+
+function fileDeliveryError(stage, cause, providerCode, { uncertain = false } = {}) {
+  const explicitCode = providerCode === undefined || providerCode === null
+    ? undefined
+    : Number(providerCode);
+  const code = Number.isFinite(explicitCode) && explicitCode !== 0
+    ? explicitCode
+    : providerErrorCode(cause);
+  const fallback = Number.isFinite(code)
+    ? ['artifact-provider-rejected', `Feishu rejected file ${stage}.`]
+    : uncertain
+      ? ['artifact-delivery-uncertain', 'Feishu could not confirm the file message result.']
+      : ['artifact-provider-failed', `Feishu file ${stage} failed.`];
+  const [errorCode, message] = FILE_DELIVERY_ERRORS.get(code) ?? fallback;
+  const error = new Error(message, { cause });
+  error.code = errorCode;
+  if (Number.isFinite(code)) error.providerCode = code;
+  return error;
+}
+
+function boundedFileTimeout(value, name) {
+  if (!Number.isInteger(value) || value < 1 || value > MAX_FILE_OPERATION_TIMEOUT_MS) {
+    throw new TypeError(`${name} must be an integer between 1 and ${MAX_FILE_OPERATION_TIMEOUT_MS}`);
+  }
+  return value;
+}
+
+function abortReason(signal) {
+  return signal?.reason ?? new DOMException('The operation was aborted', 'AbortError');
+}
+
+function operationTimeout(stage) {
+  const error = new Error(`Feishu file ${stage} timed out.`);
+  error.code = 'provider-timeout';
+  return error;
+}
+
+function waitForFileOperation(operation, { signal, timeoutMs, stage }) {
+  signal?.throwIfAborted();
+  const deadline = new AbortController();
+  const operationSignal = signal
+    ? AbortSignal.any([signal, deadline.signal])
+    : deadline.signal;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      operationSignal.removeEventListener('abort', onAbort);
+      callback(value);
+    };
+    const onAbort = () => finish(
+      reject,
+      signal?.aborted ? abortReason(signal) : operationTimeout(stage),
+    );
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    operationSignal.addEventListener('abort', onAbort, { once: true });
+
+    Promise.resolve().then(() => operation(operationSignal)).then(
+      (value) => finish(resolve, value),
+      (error) => finish(reject, error),
+    );
+    if (operationSignal.aborted) onAbort();
+  });
+}
+
+function deliveryUuid(file, chatId) {
+  const digest = createHash('sha256')
+    .update(`${file.deliveryKey}\u0000${chatId}`)
+    .digest('hex')
+    .slice(0, 40);
+  return `dshim_${digest}`;
+}
+
 function summaryOf(text) {
   const summary = String(text ?? '').replace(/\s+/g, ' ').trim();
   return summary.length <= 50 ? summary : `${summary.slice(0, 49)}…`;
@@ -39,10 +152,19 @@ function streamingCard(initialText) {
 export class VerifiedFeishuChannel {
   #client;
   #initialText;
+  #fileUploadTimeoutMs;
+  #fileMessageTimeoutMs;
 
-  constructor({ client, initialText = DEFAULT_INITIAL_TEXT }) {
+  constructor({
+    client,
+    initialText = DEFAULT_INITIAL_TEXT,
+    fileUploadTimeoutMs = MAX_FILE_OPERATION_TIMEOUT_MS,
+    fileMessageTimeoutMs = MAX_FILE_OPERATION_TIMEOUT_MS,
+  }) {
     this.#client = client;
     this.#initialText = initialText;
+    this.#fileUploadTimeoutMs = boundedFileTimeout(fileUploadTimeoutMs, 'fileUploadTimeoutMs');
+    this.#fileMessageTimeoutMs = boundedFileTimeout(fileMessageTimeoutMs, 'fileMessageTimeoutMs');
   }
 
   async stream(chatId, input, options = {}) {
@@ -107,6 +229,110 @@ export class VerifiedFeishuChannel {
     }
   }
 
+  async sendFile(chatId, file, { replyTo, signal } = {}) {
+    signal?.throwIfAborted();
+    if (typeof chatId !== 'string' || !chatId) throw new TypeError('chatId is required');
+    if (!file || typeof file !== 'object'
+      || typeof file.artifactId !== 'string' || !file.artifactId
+      || typeof file.deliveryKey !== 'string' || !file.deliveryKey
+      || typeof file.fileName !== 'string' || !file.fileName
+      || !Buffer.isBuffer(file.bytes)) {
+      throw new TypeError('A materialized result file is required');
+    }
+    let uploaded;
+    try {
+      uploaded = await waitForFileOperation((operationSignal) => {
+        operationSignal.throwIfAborted();
+        const pending = this.#client.im.v1.file.create({
+          data: {
+            file_type: 'stream',
+            file_name: file.fileName,
+            file: file.bytes,
+          },
+        });
+        trackOutboundArtifactProviderPromise(file, pending);
+        return pending;
+      }, {
+        signal,
+        timeoutMs: this.#fileUploadTimeoutMs,
+        stage: 'upload',
+      });
+    } catch (error) {
+      if (signal?.aborted) throw abortReason(signal);
+      throw fileDeliveryError('upload', error);
+    }
+    signal?.throwIfAborted();
+    const fileKey = uploaded?.file_key;
+    if (typeof fileKey !== 'string' || !fileKey) {
+      throw fileDeliveryError('upload', undefined, uploaded?.code);
+    }
+
+    const uuid = deliveryUuid(file, chatId);
+    const content = JSON.stringify({ file_key: fileKey });
+    const request = replyTo
+      ? {
+          path: { message_id: replyTo },
+          data: { msg_type: 'file', content, uuid },
+        }
+      : {
+          params: { receive_id_type: 'chat_id' },
+          data: { receive_id: chatId, msg_type: 'file', content, uuid },
+        };
+    const send = () => {
+      const pending = replyTo
+        ? this.#client.im.v1.message.reply(request)
+        : this.#client.im.v1.message.create(request);
+      trackOutboundArtifactProviderPromise(file, pending);
+      return pending;
+    };
+
+    let response;
+    try {
+      response = await waitForFileOperation(async (operationSignal) => {
+        operationSignal.throwIfAborted();
+        let result;
+        try {
+          result = await send();
+        } catch (error) {
+          if (providerErrorCode(error) !== 230049) throw error;
+          result = { code: 230049 };
+        }
+        operationSignal.throwIfAborted();
+
+        // Feishu documents 230049 as an uncertain asynchronous send result.
+        // Reuse the same file_key and UUID once so the provider can deduplicate.
+        if (Number(result?.code) === 230049) {
+          result = await send();
+          operationSignal.throwIfAborted();
+        }
+        return result;
+      }, {
+        signal,
+        timeoutMs: this.#fileMessageTimeoutMs,
+        stage: 'message send',
+      });
+    } catch (error) {
+      if (signal?.aborted) throw abortReason(signal);
+      throw fileDeliveryError('message send', error, undefined, { uncertain: true });
+    }
+    if (Number.isFinite(Number(response?.code)) && Number(response.code) !== 0) {
+      throw fileDeliveryError('message send', undefined, response.code, { uncertain: true });
+    }
+    const messageId = response?.data?.message_id;
+    if (typeof messageId !== 'string' || !messageId) {
+      throw fileDeliveryError('message send', undefined, undefined, { uncertain: true });
+    }
+    return createDeliveryReceipt({
+      deliveryId: file.deliveryKey,
+      presentation: 'feishu-file',
+      providerMessageIds: [messageId],
+      artifacts: [{
+        artifactId: file.artifactId,
+        outcome: 'sent',
+      }],
+    });
+  }
+
   async #sendCard(chatId, cardId, replyTo) {
     const content = JSON.stringify({ type: 'card', data: { card_id: cardId } });
     const response = replyTo