@xmanrui/dsh-im 4.32.0 → 4.34.0

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

@@ -0,0 +1,149 @@
+import { createCommandListSnapshots } from './command-list-snapshots.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';
+
+const COMMAND = /^\/(?:permission|permissionlist)(?=$|\s)/iu;
+const SNAPSHOTS = createCommandListSnapshots();
+const USAGE = '用法：/permission 查看当前权限；/permissionlist 列出档位；/permission <序号或完整ID> 切换；纯数字 ID 使用 /permission id:<ID>。';
+const SCOPE = '仅影响当前会话；沙箱与审批策略会同时按 Host 的档位定义更新。';
+const REFRESH = '请先执行 /permissionlist，再按列表序号选择权限档位。';
+const validId = (id) => typeof id === 'string' && /^[^\s\p{Cc}\p{Cf}]+$/u.test(id);
+const display = (value) => typeof value === 'string'
+  ? value.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, ' ').trim() : '';
+
+function result(message) {
+  return { handled: true, message, messages: splitWorkspaceCommandMessage(message) };
+}
+
+function permissions(value) {
+  if (!value || !validId(value.currentValue) || !Array.isArray(value.options)
+    || value.options.some((item) => !item || !validId(item.value))) {
+    throw new TypeError('Harness returned invalid permissions');
+  }
+  const seen = new Set();
+  return {
+    currentValue: value.currentValue,
+    options: value.options.filter((item) => {
+      if (item.value === 'custom' || seen.has(item.value)) return false;
+      seen.add(item.value);
+      return true;
+    }),
+  };
+}
+
+function description(item) {
+  // Translate known Host copy, not an assumed ID -> policy mapping: presets are configurable.
+  const text = display(item.description);
+  if (text === 'Full file access without approval prompts.') {
+    return t('完全文件访问，不再请求审批。');
+  }
+  if (text === 'Write inside the workspace and permitted temporary directories; wider retries require approval.') {
+    return t('可写工作区和允许的临时目录；扩大访问范围需要审批。');
+  }
+  return text;
+}
+
+function errorMessage(error, writing) {
+  const code = error?.code ?? error?.failure?.code;
+  if (code === WORKSPACE_SESSION_STALE || code === 'workspace-bot-not-found') {
+    return t('工作区或机器人状态已发生变化，请重试。');
+  }
+  if (['session-not-found', 'session/not-found', 'agent-not-found'].includes(code)) {
+    return t('当前聊天绑定的会话已不存在，请先绑定或建立会话。');
+  }
+  if (['commands-unavailable', 'permissions-unavailable', 'harness-api-not-found',
+    'endpoint-not-found', 'gateway/endpoint-not-found'].includes(code)) {
+    return t('当前 Host 暂不支持从机器人查看或切换权限档位。');
+  }
+  return writing
+    ? t('未能确认权限切换结果，请执行 /permission 核对当前档位。')
+    : t('暂时无法获取权限档位，请稍后重试。');
+}
+
+export function isPermissionCommand(text) {
+  return typeof text === 'string' && COMMAND.test(text.trim());
+}
+
+export async function runPermissionCommand(text, harness, state, key, options = {}) {
+  if (!isPermissionCommand(text)) return null;
+  if (options.hasImages || options.hasFiles) {
+    return result(t('权限命令仅支持纯文字，请移除图片或文件后重试。'));
+  }
+  const match = /^\/(permission|permissionlist)(?:[ \t]+([^\s]+))?[ \t]*$/iu.exec(text.trim());
+  if (!match || (match[1].toLowerCase() === 'permissionlist' && match[2])) return result(t(USAGE));
+  const list = match[1].toLowerCase() === 'permissionlist';
+  const requested = match[2];
+  if (requested && (!validId(requested) || requested.startsWith('--'))) return result(t(USAGE));
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000);
+  let writing = false;
+  try {
+    return await withSessionBindingLock(state, key, async () => {
+      signal.throwIfAborted();
+      const sessionId = state.sessionFor?.(key);
+      if (!sessionId) return result(t('当前聊天尚未绑定会话，请先发送普通消息建立会话，或使用 /session 绑定已有会话。'));
+      const session = typeof harness.workspaceSession === 'function'
+        ? harness.workspaceSession(sessionId, key)
+        : {
+            permissions: harness.getSessionPermissions && ((opts) => harness.getSessionPermissions(sessionId, opts)),
+            executeCommand: harness.executeCommand && ((line, opts) => harness.executeCommand(sessionId, line, opts)),
+          };
+      if (!requested) {
+        if (typeof session?.permissions !== 'function') return result(t('当前 Host 暂不支持从机器人查看或切换权限档位。'));
+        const current = permissions(await session.permissions({ signal }));
+        if (state.sessionFor(key) !== sessionId) return result(t('当前会话已变化，请重新执行 /permissionlist。'));
+        const lines = [t('当前会话权限：{id}', { id: current.currentValue }), ''];
+        if (list) {
+          SNAPSHOTS.save(state, key, { sessionId, ids: current.options.map((item) => item.value) });
+          for (const [index, item] of current.options.entries()) {
+            const label = display(item.name);
+            const detail = description(item);
+            lines.push(`${index + 1}. ${item.value}${label && label !== item.value ? `（${label}）` : ''}${item.value === current.currentValue ? t(' ✓ 当前') : ''}${detail ? ` — ${detail}` : ''}`);
+          }
+          if (!current.options.length) lines.push(t('当前没有可用权限档位。'));
+          lines.push('', t('切换：/permission <序号或完整ID>'));
+        } else {
+          lines.push(t('查看可用档位与序号：/permissionlist'));
+        }
+        lines.push(t(SCOPE));
+        return result(lines.join('\n'));
+      }
+
+      let selected = requested;
+      const numericId = /^id:(\d+)$/iu.exec(requested);
+      if (numericId) selected = numericId[1];
+      else if (/^\d+$/u.test(requested)) {
+        const snapshot = SNAPSHOTS.load(state, key);
+        if (!snapshot || snapshot.sessionId !== sessionId) return result(t(REFRESH));
+        const index = Number(requested);
+        if (!Number.isSafeInteger(index) || index < 1 || !snapshot.ids[index - 1]) {
+          return result(t('权限档位序号无效，请重新执行 /permissionlist。'));
+        }
+        selected = snapshot.ids[index - 1];
+      }
+      if (selected === 'custom' || /^id:/iu.test(selected)) return result(t(USAGE));
+      if (typeof session?.executeCommand !== 'function') return result(t('当前 Host 暂不支持从机器人查看或切换权限档位。'));
+      signal.throwIfAborted();
+      writing = true;
+      const execution = await session.executeCommand(`/permission ${selected}`, { signal });
+      if (execution === undefined) return result(t('当前 Host 未注册 /permission 命令，请确认权限预设组件已启用。'));
+      const outcome = execution?.result;
+      if (!outcome || !['success', 'error'].includes(outcome.kind)
+        || (outcome.text !== undefined && typeof outcome.text !== 'string')) throw new TypeError('Invalid permission command result');
+      if (outcome.kind === 'error') {
+        if (outcome.text?.startsWith('unknown preset ')) {
+          return result(t('该权限档位不存在或已不可用，请重新执行 /permissionlist。'));
+        }
+        return result([t('权限切换失败。'), display(outcome.text)].filter(Boolean).join('\n'));
+      }
+      return result([
+        t('当前会话权限已切换为：{id}', { id: selected }), '', t(SCOPE),
+        ...(selected === 'danger-full-access' ? [t('恢复工作区权限：/permission workspace-write（需 Host 支持该档位）')] : []),
+      ].join('\n'));
+    });
+  } catch (error) {
+    return result(errorMessage(error, writing));
+  }
+}

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

@@ -1,3 +1,4 @@
+import { createCommandListSnapshots, COMMAND_LIST_TTL_MS, COMMAND_LIST_MAX_ENTRIES } from './command-list-snapshots.mjs';
 import {
   normalizeAgentPresetCatalog,
   normalizeAgentPresetId,
@@ -19,9 +20,9 @@ const PRESET_USAGE = [
   '/preset --default  跟随 Host 默认',
 ].join('\n');
 const UNSAFE_DISPLAY_TEXT_GLOBAL = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu;
-const LIST_SNAPSHOTS = new WeakMap();
-export const PRESET_LIST_SNAPSHOT_TTL_MS = 15 * 60_000;
-export const PRESET_LIST_SNAPSHOT_MAX_ENTRIES = 256;
+const LIST_SNAPSHOTS = createCommandListSnapshots();
+export const PRESET_LIST_SNAPSHOT_TTL_MS = COMMAND_LIST_TTL_MS;
+export const PRESET_LIST_SNAPSHOT_MAX_ENTRIES = COMMAND_LIST_MAX_ENTRIES;
 
 function commandResult(message) {
   return {
@@ -140,59 +141,13 @@ function formatUpdated(settings) {
   ].join('\n');
 }
 
-function stateSnapshots(state, { create = false } = {}) {
-  if ((typeof state !== 'object' || state === null) && typeof state !== 'function') return null;
-  let snapshots = LIST_SNAPSHOTS.get(state);
-  if (!snapshots && create) {
-    snapshots = new Map();
-    LIST_SNAPSHOTS.set(state, snapshots);
-  }
-  return snapshots ?? null;
-}
-
-function pruneExpiredSnapshots(snapshots, now) {
-  for (const [snapshotKey, snapshot] of snapshots) {
-    if (snapshot.expiresAt <= now) snapshots.delete(snapshotKey);
-  }
-}
-
-function saveSnapshot(state, key, items) {
-  const snapshots = stateSnapshots(state, { create: true });
-  if (!snapshots) return;
-  const now = Date.now();
-  pruneExpiredSnapshots(snapshots, now);
-  snapshots.delete(key);
-  snapshots.set(key, {
-    expiresAt: now + PRESET_LIST_SNAPSHOT_TTL_MS,
-    ids: items.map((item) => item.id),
-  });
-  while (snapshots.size > PRESET_LIST_SNAPSHOT_MAX_ENTRIES) {
-    const oldest = snapshots.keys().next();
-    if (oldest.done) break;
-    snapshots.delete(oldest.value);
-  }
-}
-
-function loadSnapshot(state, key) {
-  const snapshots = stateSnapshots(state);
-  const snapshot = snapshots?.get(key);
-  if (!snapshots || !snapshot) return null;
-  if (snapshot.expiresAt <= Date.now()) {
-    snapshots.delete(key);
-    return null;
-  }
-  snapshots.delete(key);
-  snapshots.set(key, snapshot);
-  return snapshot.ids;
-}
-
 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: t('Agent Preset 序号无效，请先执行 /presetlist。') };
   }
-  const snapshot = loadSnapshot(state, key);
+  const snapshot = LIST_SNAPSHOTS.load(state, key);
   if (!snapshot) {
     return { numeric: true, error: t('请先执行 /presetlist，再按列表序号选择 Agent Preset。') };
   }
@@ -260,7 +215,7 @@ export async function runPresetCommand(text, harness, state, key, options = {})
     if (!/^\/(?:presetlist|presets)[ \t]*$/iu.test(command)) return commandResult(t(PRESET_LIST_USAGE));
     try {
       const current = await settings(harness, requestOptions);
-      saveSnapshot(state, key, current.agentPresetCatalog.items);
+      LIST_SNAPSHOTS.save(state, key, current.agentPresetCatalog.items.map((item) => item.id));
       return commandResult(formatList(current));
     } catch (error) {
       return commandResult(presetErrorMessage(error, 'list'));

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

@@ -276,8 +276,8 @@ export class OutboundArtifactRegistry {
   }
 
   /**
-   * Bind one channel request to the Turn it starts. This owns cleanup only:
-   * it never changes tool visibility or decides whether a file may be sent.
+   * Bind one channel delivery consumer to the Turn its request starts.
+   * Only this consumer can retain files for delivery after the Turn ends.
    */
   openConsumer(sessionId, promptRpcId) {
     if (typeof sessionId !== 'string' || !sessionId
@@ -310,8 +310,24 @@ export class OutboundArtifactRegistry {
     };
   }
 
-  /** Observe durable Session events solely to terminate unclaimed snapshots. */
-  observeSessionEvent(session, event) {
+  /** The Host claims input before assembling the first step's prompt. */
+  observeClaimedMessage(session, message, turn) {
+    const sessionId = sessionIdOf(session);
+    if (!sessionId || !Number.isInteger(turn) || turn < 0
+      || this.#currentTurn(session) !== turn) return;
+    this.#bindConsumer(sessionId, message?.source?.rpcId, turn);
+  }
+
+  #bindConsumer(sessionId, rpcId, turn) {
+    if (typeof rpcId !== 'string' || !rpcId) return;
+    const consumer = this.#consumersByPrompt.get(promptKey(sessionId, rpcId));
+    if (!consumer || consumer.released) return;
+    consumer.turn = turn;
+    this.#consumersByTurn.set(turnKey(sessionId, turn), consumer);
+  }
+
+  /** Observe durable Session events to bind delivery ownership and clean up. */
+  observeSessionEvent(session, event, { logger } = {}) {
     const sessionId = sessionIdOf(session);
     if (!sessionId || !event || typeof event !== 'object') return;
     if (event.type === 'turn/start') {
@@ -321,21 +337,50 @@ export class OutboundArtifactRegistry {
     }
     if (event.type === 'user/message') {
       const rpcId = event.data?.source?.rpcId;
-      const turn = this.#openTurns.get(sessionId) ?? currentTurn({ session });
+      const turn = this.#currentTurn(session);
       if (typeof rpcId !== 'string' || !rpcId || !Number.isInteger(turn)) return;
       this.#openTurns.set(sessionId, turn);
-      const consumer = this.#consumersByPrompt.get(promptKey(sessionId, rpcId));
-      if (!consumer || consumer.released) return;
-      consumer.turn = turn;
-      this.#consumersByTurn.set(turnKey(sessionId, turn), consumer);
+      this.#bindConsumer(sessionId, rpcId, turn);
       return;
     }
     if (event.type !== 'turn/end') return;
     const turn = event.data?.turn;
     if (!Number.isInteger(turn) || turn < 0) return;
-    if (this.#openTurns.get(sessionId) === turn) this.#openTurns.delete(sessionId);
+    // Retain the observed closed state so a stale Session snapshot cannot
+    // reopen a Turn while its consumer is still waiting to claim the files.
+    if (this.#currentTurn(session) === turn) this.#openTurns.set(sessionId, null);
+    if (!this.#consumerForTurn(sessionId, turn)) {
+      const keyForTurn = turnKey(sessionId, turn);
+      const artifactCount = (this.#turns.get(keyForTurn)?.size ?? 0)
+        + (this.#stagedTurns.get(keyForTurn)?.size ?? 0);
+      this.discard(sessionId, turn);
+      if (artifactCount > 0) {
+        logger?.warn?.('[dsh-im] discarded files without an active IM delivery consumer:', {
+          sessionId, turn, artifactCount,
+        });
+      }
+    }
+  }
+
+  #currentTurn(session) {
+    const sessionId = sessionIdOf(session);
+    return this.#openTurns.has(sessionId)
+      ? this.#openTurns.get(sessionId)
+      : currentTurn({ session });
+  }
+
+  #consumerForTurn(sessionId, turn) {
     const consumer = this.#consumersByTurn.get(turnKey(sessionId, turn));
-    if (!consumer || consumer.released) this.discard(sessionId, turn);
+    return consumer && !consumer.released && consumer.turn === turn
+      && this.#consumersByPrompt.get(promptKey(sessionId, consumer.promptRpcId)) === consumer
+      ? consumer : null;
+  }
+
+  /** Prompt guidance follows the active Turn's actual delivery owner. */
+  hasActiveConsumer(session) {
+    const turn = this.#currentTurn(session);
+    return Number.isInteger(turn)
+      && this.#consumerForTurn(sessionIdOf(session), turn) !== null;
   }
 
   /** A disposed Session cannot have another channel consumer claim its files. */
@@ -371,7 +416,7 @@ export class OutboundArtifactRegistry {
     const agent = exec?.agent;
     const sessionId = agent?.session?.header?.id;
     const workspace = agent?.session?.header?.cwd;
-    const turn = this.#openTurns.get(sessionId) ?? currentTurn(agent);
+    const turn = this.#currentTurn(agent?.session);
     if (typeof sessionId !== 'string' || !sessionId
       || typeof workspace !== 'string' || !workspace || turn === null) {
       throw artifactError(
@@ -380,8 +425,25 @@ export class OutboundArtifactRegistry {
       );
     }
 
+    const consumer = this.#consumerForTurn(sessionId, turn);
+    const unavailable = () => artifactError(
+      'artifact-consumer-required',
+      'No active IM delivery consumer owns this turn. The file was not queued. Use the host present tool if available to return the file in this conversation.',
+    );
+    if (!consumer) throw unavailable();
+
     const snapshot = await snapshotFile(workspace, requestedPath, exec?.signal);
     const { storagePath, ...snapshotMetadata } = snapshot;
+    // Copying and hashing yield to cancellation, disposal and Turn completion.
+    // Never leave a late snapshot behind after its delivery owner has gone.
+    try {
+      exec?.signal?.throwIfAborted();
+      if (this.#currentTurn(agent?.session) !== turn
+        || this.#consumerForTurn(sessionId, turn) !== consumer) throw unavailable();
+    } catch (error) {
+      await unlink(storagePath).catch(() => undefined);
+      throw error;
+    }
     const artifact = Object.freeze({
       kind: ARTIFACT_KIND,
       schemaVersion: 1,
@@ -578,7 +640,7 @@ export function createOutboundArtifactTool({ registry = outboundArtifactRegistry
   };
   const definition = Object.freeze({
     name: OUTBOUND_ARTIFACT_TOOL,
-    description: 'Register a readable file or generated image for delivery through the current conversation after this turn. Existing and newly created files are both valid. Success means queued, not sent; do not claim the user has received the file.',
+    description: 'Register a readable file or generated image for delivery through the current IM conversation after this turn. Requires an active IM delivery consumer; in Web, Desktop, or CLI conversations use the host present tool if available. Existing and newly created files are both valid. Success means queued, not sent; do not claim the user has received the file.',
     parameters: {
       type: 'object',
       additionalProperties: false,
@@ -643,20 +705,28 @@ export function createOutboundArtifactTool({ registry = outboundArtifactRegistry
   return Object.freeze({ definition, onResult });
 }
 
-/** Register the file-return tool without a per-request Gate. */
+/** Register the file-return tool with guidance scoped to an owned IM Turn. */
 export function installOutboundArtifactTool(ctx, { registry = outboundArtifactRegistry } = {}) {
   if (typeof ctx?.tools?.register !== 'function'
-    || typeof ctx?.systemPrompt?.section !== 'function'
+    || typeof ctx?.systemPrompt?.context !== 'function'
     || typeof ctx?.on !== 'function') return false;
+  const logger = typeof ctx.logger === 'function'
+    ? ctx.logger('dsh-im:outbound-artifact')
+    : (ctx.logger ?? console);
   const tool = createOutboundArtifactTool({ registry });
   ctx.tools.register(tool.definition);
   ctx.on('tools/result', tool.onResult);
-  ctx.on('session/event', (session, event) => registry.observeSessionEvent(session, event));
+  ctx.on('agent/inbox/claimed', ({ agent, message, turn }) => {
+    registry.observeClaimedMessage(agent?.session, message, turn);
+  }, { global: true });
+  ctx.on('session/event', (session, event) => registry.observeSessionEvent(session, event, { logger }));
   ctx.on('session/disposed', (session) => registry.disposeSession(session));
-  ctx.systemPrompt.section({
+  ctx.systemPrompt.context({
     name: 'dsh-im:return-file',
     order: 115,
-    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. This tool only registers the file; the channel uploads and sends it after your turn finishes. In your reply say the file is prepared or queued, never that it has already been sent or received. The channel reports delivery failures separately.`,
+    text: (assembly) => registry.hasActiveConsumer(assembly?.agent?.session)
+      ? `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. This tool only registers the file; the channel uploads and sends it after your turn finishes. In your reply say the file is prepared or queued, never that it has already been sent or received. The channel reports delivery failures separately.`
+      : '',
   });
   return true;
 }

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

@@ -1,5 +1,4 @@
 import { extractConnectionEvidence, createConnectionDiagnostics, atConnectionStage } from '../shared/connection-error.mjs';
-import { randomInt } from 'node:crypto';
 
 import { createEditableMessageStream } from '../shared/editable-message-stream.mjs';
 import { createTextDeliveryBlock } from '../shared/semantic/delivery.mjs';
@@ -357,6 +356,11 @@ function telegramMessageId(value) {
   return Number.isSafeInteger(value?.message_id) ? String(value.message_id) : null;
 }
 
+function telegramMessageUnchanged(error) {
+  return error?.providerCode === 400
+    && /^(?:Bad Request: )?message is not modified(?::|$)/iu.test(error?.message ?? '');
+}
+
 function telegramFailure(error) {
   const providerCode = Number(error?.providerCode);
   const status = Number(error?.status);
@@ -687,6 +691,9 @@ export class TelegramBotClient {
           messageId: placeholderMessageId,
           text: chunks[0],
           signal: this.#signal,
+        }).catch((error) => {
+          // The final answer may already be visible from the last progress edit.
+          if (!telegramMessageUnchanged(error)) throw error;
         });
         firstUnsent = 1;
       } catch (error) {
@@ -814,6 +821,8 @@ export class TelegramBotClient {
         messageId,
         richMessage: { markdown: chunks[0].markdown },
         signal: this.#signal,
+      }).catch((error) => {
+        if (!telegramMessageUnchanged(error)) throw error;
       });
     } catch (error) {
       const failure = telegramFailure(error);
@@ -869,31 +878,8 @@ export class TelegramBotClient {
   }
 
   async openDeliveryStream(target) {
-    if (target.chatType === 'private') {
-      const draftId = randomInt(1, 2_147_483_647);
-      const updateDraft = async (block) => {
-        const richMessage = { markdown: toTelegramRichMarkdown(block.text) };
-        await this.#api.sendRichMessageDraft({
-          chatId: target.chatId,
-          draftId,
-          richMessage,
-          messageThreadId: target.messageThreadId,
-          signal: this.#signal,
-        });
-        return deliveryResult('telegram-rich-draft', []);
-      };
-      const stream = new TelegramDeliveryStream({
-        update: updateDraft,
-        finish: (block) => this.#sendRich(target, block),
-        fail: (block) => this.#sendPlain(target, block.text),
-        presentation: 'telegram-rich-draft',
-        keepalive: true,
-        logger: this.#logger,
-      });
-      await stream.update(createTextDeliveryBlock(t('正在处理…'), 'plain'));
-      return stream;
-    }
-
+    // Real messages keep the Android composer available for /stop and /steer;
+    // private-chat Rich Drafts can block sending for the whole turn (#276).
     const placeholder = await this.#api.sendMessage({
       chatId: target.chatId,
       text: t('正在处理…'),