@xmanrui/dsh-im 1.4.0 → 2.0.0

package/src/channels/shared/model-command.mjs

@@ -1,4 +1,5 @@
 import { splitWorkspaceCommandMessage } from './workspace-command.mjs';
+import { t } from './i18n.mjs';
 import { WORKSPACE_SESSION_STALE } from './workspace-session.mjs';
 import { withSessionBindingLock } from './session-binding-lock.mjs';
 
@@ -109,9 +110,9 @@ function modelNumberRequest(requested) {
 
 function invalidModelNumberMessage(requested) {
   return [
-    `模型序号无效：${safeDisplayText(requested)}`,
+    t('模型序号无效：{input}', { input: safeDisplayText(requested) }),
     '',
-    '请发送 /models 查看并输入有效的正整数序号。',
+    t('请发送 /models 查看并输入有效的正整数序号。'),
   ].join('\n');
 }
 
@@ -119,43 +120,43 @@ function formatCatalog(catalog) {
   const currentId = catalog.current
     ? modelId(catalog.current.provider, catalog.current.model)
     : null;
-  const lines = ['可用模型：'];
+  const lines = [t('可用模型：')];
   let index = 0;
-  if (catalog.groups.length === 0) lines.push('', '当前没有可用模型。');
+  if (catalog.groups.length === 0) lines.push('', t('当前没有可用模型。'));
   for (const group of catalog.groups) {
     lines.push('', safeDisplayText(group.name) || safeDisplayText(group.id));
     for (const model of group.models) {
       index += 1;
       const id = modelId(group.id, model.id);
-      lines.push(`${index}. ${safeDisplayText(id)}${id === currentId ? '（当前）' : ''}`);
+      lines.push(`${index}. ${safeDisplayText(id)}${id === currentId ? t('（当前）') : ''}`);
     }
   }
   if (catalog.failures.length > 0) {
-    lines.push('', '以下模型提供方暂时不可用：');
+    lines.push('', t('以下模型提供方暂时不可用：'));
     for (const failure of catalog.failures) {
       lines.push(`- ${safeDisplayText(failure.name) || safeDisplayText(failure.id)}`);
     }
   }
-  if (index > 0) lines.push('', '切换模型：/model <序号>');
+  if (index > 0) lines.push('', t('切换模型：/model <序号>'));
   return lines.join('\n');
 }
 
 function currentModelMessage(current) {
   return [
-    '当前模型：',
+    t('当前模型：'),
     modelId(current.provider, current.model),
     '',
-    '查看全部模型：/models',
-    '切换模型：/model <序号>',
+    t('查看全部模型：/models'),
+    t('切换模型：/model <序号>'),
   ].join('\n');
 }
 
 function noSessionMessage() {
   return [
-    '当前聊天还没有会话。',
+    t('当前聊天还没有会话。'),
     '',
-    '查看模型：/models',
-    '选择模型：/model <序号>',
+    t('查看模型：/models'),
+    t('选择模型：/model <序号>'),
   ].join('\n');
 }
 
@@ -166,26 +167,26 @@ function errorCode(error) {
 function modelErrorMessage(error, action) {
   const code = errorCode(error);
   if (code === 'agent-busy') {
-    return '当前任务正在运行，请等待完成或先发送 /stop。';
+    return t('当前任务正在运行，请等待完成或先发送 /stop。');
   }
   if (code === 'session-not-found') {
-    return '当前聊天绑定的会话已不存在，请重试。';
+    return t('当前聊天绑定的会话已不存在，请重试。');
   }
   if (code === 'model-unavailable') {
-    return '无法切换到该模型。模型当前不可用，或不支持当前会话中的图片。';
+    return t('无法切换到该模型。模型当前不可用，或不支持当前会话中的图片。');
   }
   if (code === WORKSPACE_SESSION_STALE || code === 'workspace-bot-not-found') {
-    return '工作区或机器人状态已发生变化，请重试。';
+    return t('工作区或机器人状态已发生变化，请重试。');
   }
   if (code === SESSION_BINDING_CHANGED) {
-    return '当前聊天绑定的会话已发生变化，请重试。';
+    return t('当前聊天绑定的会话已发生变化，请重试。');
   }
   if (code === 'cancelled' || error?.name === 'AbortError') {
-    return action === 'list' ? '获取模型列表已取消。' : '模型切换已取消。';
+    return action === 'list' ? t('获取模型列表已取消。') : t('模型切换已取消。');
   }
   return action === 'list'
-    ? '暂时无法获取模型列表，请稍后重试。'
-    : '模型切换失败，请稍后重试。';
+    ? t('暂时无法获取模型列表，请稍后重试。')
+    : t('模型切换失败，请稍后重试。');
 }
 
 async function boundSession(harness, state, key, options) {
@@ -243,12 +244,12 @@ export async function runModelCommand(text, harness, state, key, options = {}) {
   if (!isModelCommand(text)) return null;
   const command = text.trim();
   if (options.hasImages) {
-    return commandResult('模型命令仅支持纯文字，请移除图片后重试。');
+    return commandResult(t('模型命令仅支持纯文字，请移除图片后重试。'));
   }
   const requestOptions = rpcOptions(options.signal);
 
   if (isModelsCommand(command)) {
-    if (!/^\/models[ \t]*$/iu.test(command)) return commandResult(MODELS_USAGE);
+    if (!/^\/models[ \t]*$/iu.test(command)) return commandResult(t(MODELS_USAGE));
     try {
       const bound = await boundSession(harness, state, key, requestOptions);
       const catalog = bound
@@ -261,7 +262,7 @@ export async function runModelCommand(text, harness, state, key, options = {}) {
   }
 
   const match = /^\/model(?:[ \t]+([^\s]+))?[ \t]*$/iu.exec(command);
-  if (!match) return commandResult(MODEL_USAGE);
+  if (!match) return commandResult(t(MODEL_USAGE));
   const requested = match[1];
   if (!requested) {
     try {
@@ -279,13 +280,13 @@ export async function runModelCommand(text, harness, state, key, options = {}) {
   }
   if (!numberRequest
     && (!requested.includes('/') || requested.startsWith('/') || requested.endsWith('/'))) {
-    return commandResult(MODEL_USAGE);
+    return commandResult(t(MODEL_USAGE));
   }
   if (options.pendingInteraction) {
     return commandResult([
-      '当前任务正在等待你的回答或审批。',
+      t('当前任务正在等待你的回答或审批。'),
       '',
-      '请先处理当前请求，或者发送 /stop 停止任务。',
+      t('请先处理当前请求，或者发送 /stop 停止任务。'),
     ].join('\n'));
   }
 
@@ -293,7 +294,7 @@ export async function runModelCommand(text, harness, state, key, options = {}) {
     return await withSessionBindingLock(state, key, async () => {
       const bound = await boundSession(harness, state, key, requestOptions);
       if (bound && await sessionIsBusy(bound.session, options.control, requestOptions)) {
-        return commandResult('当前任务正在运行，请等待完成或先发送 /stop。');
+        return commandResult(t('当前任务正在运行，请等待完成或先发送 /stop。'));
       }
 
       const catalog = bound
@@ -305,9 +306,9 @@ export async function runModelCommand(text, harness, state, key, options = {}) {
       if (!selection) {
         if (numberRequest) return commandResult(invalidModelNumberMessage(requested));
         return commandResult([
-          `没有找到模型：${safeDisplayText(requested)}`,
+          t('没有找到模型：{model}', { model: safeDisplayText(requested) }),
           '',
-          '请发送 /models 查看可用模型。',
+          t('请发送 /models 查看可用模型。'),
         ].join('\n'));
       }
 
@@ -344,7 +345,10 @@ export async function runModelCommand(text, harness, state, key, options = {}) {
           throw stale;
         }
       }
-      return commandResult(`模型已切换为：\n${modelId(selection.provider, selection.model)}\n\n后续消息将使用该模型。`);
+      return commandResult(t(`模型已切换为：
+{model}
+
+后续消息将使用该模型。`, { model: modelId(selection.provider, selection.model) }));
     });
   } catch (error) {
     return commandResult(modelErrorMessage(error, 'select'));

package/src/channels/shared/preset-command.mjs

@@ -2,6 +2,7 @@ import {
   normalizeAgentPresetCatalog,
   normalizeAgentPresetId,
 } from './agent-preset.mjs';
+import { t } from './i18n.mjs';
 import { withSessionBindingLock } from './session-binding-lock.mjs';
 import { splitWorkspaceCommandMessage } from './workspace-command.mjs';
 import { WORKSPACE_SESSION_STALE } from './workspace-session.mjs';
@@ -59,7 +60,7 @@ function normalizeSettings(value) {
 
 function presetItemText(item) {
   const label = safeDisplayText(item.label) || item.id;
-  return `${label}（${item.id}）`;
+  return t('{label}（{id}）', { label, id: item.id });
 }
 
 function itemFor(catalog, id) {
@@ -67,11 +68,11 @@ function itemFor(catalog, id) {
 }
 
 function defaultDescription(catalog) {
-  if (!catalog.defaultId) return '未设置或当前不可用';
+  if (!catalog.defaultId) return t('未设置或当前不可用');
   const item = itemFor(catalog, catalog.defaultId);
   return item
     ? presetItemText(item)
-    : `${catalog.defaultId}（当前不可用）`;
+    : t('{id}（当前不可用）', { id: catalog.defaultId });
 }
 
 function currentDescription(settings) {
@@ -79,63 +80,63 @@ function currentDescription(settings) {
   if (agentPreset === null) {
     const item = itemFor(catalog, catalog.defaultId);
     return item
-      ? `跟随 Host 默认：${presetItemText(item)}`
-      : '跟随 Host 默认（Host 默认当前不可用）';
+      ? t('跟随 Host 默认：{preset}', { preset: presetItemText(item) })
+      : t('跟随 Host 默认（Host 默认当前不可用）');
   }
   const item = itemFor(catalog, agentPreset);
   return item
     ? presetItemText(item)
-    : `${agentPreset}（已不可用）`;
+    : t('{id}（已不可用）', { id: agentPreset });
 }
 
 function formatCurrent(settings) {
   return [
-    '当前机器人用于新会话的 Agent Preset：',
+    t('当前机器人用于新会话的 Agent Preset：'),
     currentDescription(settings),
     '',
-    '已有会话不会受此设置影响。',
-    '查看可用项：/presetlist',
-    '恢复跟随 Host 默认：/preset --default',
+    t('已有会话不会受此设置影响。'),
+    t('查看可用项：/presetlist'),
+    t('恢复跟随 Host 默认：/preset --default'),
   ].join('\n');
 }
 
 function formatList(settings) {
   const { agentPreset, agentPresetCatalog: catalog } = settings;
   const lines = [
-    '当前机器人用于新会话的 Agent Preset：',
+    t('当前机器人用于新会话的 Agent Preset：'),
     currentDescription(settings),
     '',
-    `Host 默认：${defaultDescription(catalog)}`,
+    t('Host 默认：{preset}', { preset: defaultDescription(catalog) }),
     '',
-    `可用 Agent Preset（${catalog.items.length}）：`,
+    t('可用 Agent Preset（{count}）：', { count: catalog.items.length }),
   ];
   if (catalog.items.length === 0) {
-    lines.push('当前没有可用 Agent Preset。');
+    lines.push(t('当前没有可用 Agent Preset。'));
   } else {
     catalog.items.forEach((item, index) => {
       const markers = [];
-      if (item.id === catalog.defaultId) markers.push('Host 默认');
-      if (item.id === agentPreset) markers.push('当前选择');
-      if (agentPreset === null && item.id === catalog.defaultId) markers.push('当前生效');
+      if (item.id === catalog.defaultId) markers.push(t('Host 默认'));
+      if (item.id === agentPreset) markers.push(t('当前选择'));
+      if (agentPreset === null && item.id === catalog.defaultId) markers.push(t('当前生效'));
       const annotation = markers.length > 0 ? `（${markers.join('，')}）` : '';
       lines.push(`${index + 1}. ${presetItemText(item)}${annotation}`);
     });
   }
   lines.push(
     '',
-    '选择：/preset <序号或 ID>',
-    '纯数字 ID：/preset id:<ID>',
-    '恢复跟随 Host 默认：/preset --default',
+    t('选择：/preset <序号或 ID>'),
+    t('纯数字 ID：/preset id:<ID>'),
+    t('恢复跟随 Host 默认：/preset --default'),
   );
   return lines.join('\n');
 }
 
 function formatUpdated(settings) {
   return [
-    '当前机器人用于新会话的 Agent Preset 已设置为：',
+    t('当前机器人用于新会话的 Agent Preset 已设置为：'),
     currentDescription(settings),
     '',
-    '已有会话不变。若当前聊天已有会话，请先发送 /new，再发送普通消息，才会使用新设置创建会话。',
+    t('已有会话不变。若当前聊天已有会话，请先发送 /new，再发送普通消息，才会使用新设置创建会话。'),
   ].join('\n');
 }
 
@@ -189,16 +190,16 @@ function presetFromSnapshot(state, key, requested) {
   if (!/^\d+$/u.test(requested)) return { numeric: false, id: null };
   const index = Number(requested);
   if (!Number.isSafeInteger(index) || index < 1) {
-    return { numeric: true, error: 'Agent Preset 序号无效，请先执行 /presetlist。' };
+    return { numeric: true, error: t('Agent Preset 序号无效，请先执行 /presetlist。') };
   }
   const snapshot = loadSnapshot(state, key);
   if (!snapshot) {
-    return { numeric: true, error: '请先执行 /presetlist，再按列表序号选择 Agent Preset。' };
+    return { numeric: true, error: t('请先执行 /presetlist，再按列表序号选择 Agent Preset。') };
   }
   const id = snapshot[index - 1];
   return id
     ? { numeric: true, id }
-    : { numeric: true, error: 'Agent Preset 序号不存在，请重新执行 /presetlist。' };
+    : { numeric: true, error: t('Agent Preset 序号不存在，请重新执行 /presetlist。') };
 }
 
 function errorCode(error) {
@@ -208,22 +209,23 @@ function errorCode(error) {
 function presetErrorMessage(error, action) {
   const code = errorCode(error);
   if (code === 'agent-preset-invalid') {
-    return `Agent Preset ID 格式无效。\n${PRESET_USAGE}`;
+    return t(`Agent Preset ID 格式无效。
+{usage}`, { usage: t(PRESET_USAGE) });
   }
   if (code === 'agent-preset-unavailable') {
-    return 'Agent Preset 不存在或当前不可用，请重新执行 /presetlist。';
+    return t('Agent Preset 不存在或当前不可用，请重新执行 /presetlist。');
   }
   if (code === WORKSPACE_SESSION_STALE || code === 'workspace-bot-not-found') {
-    return '工作区或机器人状态已发生变化，请重试。';
+    return t('工作区或机器人状态已发生变化，请重试。');
   }
   if (code === 'cancelled' || error?.name === 'AbortError') {
-    if (action === 'list') return '获取 Agent Preset 列表已取消。';
-    if (action === 'current') return '获取 Agent Preset 设置已取消。';
-    return 'Agent Preset 修改已取消。';
+    if (action === 'list') return t('获取 Agent Preset 列表已取消。');
+    if (action === 'current') return t('获取 Agent Preset 设置已取消。');
+    return t('Agent Preset 修改已取消。');
   }
-  if (action === 'list') return '暂时无法获取 Agent Preset 列表，请稍后重试。';
-  if (action === 'current') return '暂时无法获取 Agent Preset 设置，请稍后重试。';
-  return 'Agent Preset 修改失败，请稍后重试。';
+  if (action === 'list') return t('暂时无法获取 Agent Preset 列表，请稍后重试。');
+  if (action === 'current') return t('暂时无法获取 Agent Preset 设置，请稍后重试。');
+  return t('Agent Preset 修改失败，请稍后重试。');
 }
 
 async function settings(harness, options) {
@@ -250,12 +252,12 @@ export async function runPresetCommand(text, harness, state, key, options = {})
   if (!isPresetCommand(text)) return null;
   const command = text.trim();
   if (options.hasImages) {
-    return commandResult('Agent Preset 命令仅支持纯文字，请移除图片后重试。');
+    return commandResult(t('Agent Preset 命令仅支持纯文字，请移除图片后重试。'));
   }
   const requestOptions = rpcOptions(options.signal);
 
   if (PRESET_LIST_COMMAND.test(command)) {
-    if (!/^\/presetlist[ \t]*$/iu.test(command)) return commandResult(PRESET_LIST_USAGE);
+    if (!/^\/presetlist[ \t]*$/iu.test(command)) return commandResult(t(PRESET_LIST_USAGE));
     try {
       const current = await settings(harness, requestOptions);
       saveSnapshot(state, key, current.agentPresetCatalog.items);
@@ -266,7 +268,7 @@ export async function runPresetCommand(text, harness, state, key, options = {})
   }
 
   const match = /^\/preset(?:[ \t]+([^\s]+))?[ \t]*$/iu.exec(command);
-  if (!match) return commandResult(PRESET_USAGE);
+  if (!match) return commandResult(t(PRESET_USAGE));
   const requested = match[1];
   if (!requested) {
     try {
@@ -290,7 +292,8 @@ export async function runPresetCommand(text, harness, state, key, options = {})
         selected = fromSnapshot.id;
       } else {
         selected = normalizeAgentPresetId(requested);
-        if (!selected) return commandResult(`Agent Preset ID 格式无效。\n${PRESET_USAGE}`);
+        if (!selected) return commandResult(t(`Agent Preset ID 格式无效。
+{usage}`, { usage: t(PRESET_USAGE) }));
       }
     }
   }

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) && baseReceipt.deliveryOutcome !== 'failed';
+  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

@@ -1,6 +1,8 @@
 export const DELIVERY_RECEIPT_SCHEMA_VERSION = 1;
 
 const ARTIFACT_OUTCOMES = new Set(['sent', 'rejected', 'failed', 'unknown']);
+const DELIVERY_OUTCOMES = new Set(['sent', 'failed', 'unknown']);
+const TEXT_FORMATS = new Set(['plain', 'markdown']);
 const REJECTED_ARTIFACT_ERRORS = new Set([
   'artifact-changed',
   'artifact-context-required',
@@ -34,6 +36,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())
@@ -50,6 +54,24 @@ function requiredString(value, name) {
   return value;
 }
 
+export function createTextDeliveryBlock(value, format = 'plain') {
+  const block = typeof value === 'string'
+    ? { kind: 'text', text: value, format }
+    : value;
+  if (!block || typeof block !== 'object' || Array.isArray(block)
+    || block.kind !== 'text' || typeof block.text !== 'string' || !block.text.trim()) {
+    throw new TypeError('text delivery block must contain non-empty text');
+  }
+  if (!TEXT_FORMATS.has(block.format)) {
+    throw new TypeError('text delivery format must be plain or markdown');
+  }
+  return Object.freeze({
+    kind: 'text',
+    text: block.text,
+    format: block.format,
+  });
+}
+
 function providerIds(values) {
   if (!Array.isArray(values)) throw new TypeError('providerMessageIds must be an array');
   const ids = [];
@@ -96,12 +118,22 @@ export function createDeliveryReceipt({
   presentation,
   providerMessageIds = [],
   artifacts = [],
+  deliveryOutcome,
+  reason,
 }) {
+  if (deliveryOutcome !== undefined && !DELIVERY_OUTCOMES.has(deliveryOutcome)) {
+    throw new TypeError('deliveryOutcome must be sent, failed, or unknown');
+  }
+  const normalizedReason = reason === undefined
+    ? undefined
+    : requiredString(reason, 'delivery reason');
   return Object.freeze({
     schemaVersion: DELIVERY_RECEIPT_SCHEMA_VERSION,
     deliveryId: requiredString(deliveryId, 'deliveryId'),
     presentation: requiredString(presentation, 'presentation'),
     providerMessageIds: providerIds(providerMessageIds),
+    ...(deliveryOutcome === undefined ? {} : { deliveryOutcome }),
+    ...(normalizedReason === undefined ? {} : { reason: normalizedReason }),
     artifacts: artifactResults(artifacts),
   });
 }
@@ -135,11 +167,17 @@ export function mergeDeliveryReceipts({ deliveryId, presentation, receipts }) {
   }
   const messageIds = [];
   const artifacts = new Map();
+  let deliveryOutcome;
+  let reason;
   for (const receipt of receipts) {
     if (!receipt || receipt.schemaVersion !== DELIVERY_RECEIPT_SCHEMA_VERSION) {
       throw new TypeError('receipt must use DeliveryReceipt schema version 1');
     }
     messageIds.push(...(receipt.providerMessageIds ?? []));
+    if (deliveryOutcome === undefined && receipt.deliveryOutcome !== undefined) {
+      deliveryOutcome = receipt.deliveryOutcome;
+      reason = receipt.reason;
+    }
     for (const artifact of receipt.artifacts ?? []) {
       artifacts.set(artifact.artifactId, artifact);
     }
@@ -148,6 +186,8 @@ export function mergeDeliveryReceipts({ deliveryId, presentation, receipts }) {
     deliveryId,
     presentation,
     providerMessageIds: messageIds,
+    deliveryOutcome,
+    reason,
     artifacts: [...artifacts.values()],
   });
 }