@xmanrui/dsh-im 4.32.0 → 4.33.0

package/src/channels/feishu/message-utils.mjs

@@ -1,8 +1,11 @@
+import { addAbortSignal, Readable } from 'node:stream';
+import { downloadFeishuResourceRanges } from './resource-download.mjs';
 import { imageDownloadLimitMessage } from '../shared/image-prompt.mjs';
 import { ImagePromptError } from '../shared/image-prompt.mjs';
 import { t } from '../shared/i18n.mjs';
 
 const FEISHU_MISSING_MESSAGE_SCOPE_CODE = 99991672;
+const FEISHU_RESOURCE_SIZE_LIMIT_CODE = 234037;
 const FEISHU_CARD_MESSAGE_CONTENT_TYPE = 'raw_card_content';
 const FEISHU_ERROR_BODY_LIMIT = 64 * 1024;
 const FEISHU_ERROR_BODY_TIMEOUT_MS = 1_000;
@@ -305,31 +308,6 @@ async function readBoundedStream(stream, { signal, maxBytes }) {
   }
 }
 
-async function readStream(stream, { signal }) {
-  if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') {
-    throw new Error('Feishu file download returned no readable stream');
-  }
-  signal?.throwIfAborted();
-  const abort = () => stream.destroy?.(
-    signal.reason ?? new DOMException('Feishu file download aborted', 'AbortError'),
-  );
-  signal?.addEventListener('abort', abort, { once: true });
-  const chunks = [];
-  let size = 0;
-  try {
-    for await (const chunk of stream) {
-      signal?.throwIfAborted();
-      const data = Buffer.from(chunk);
-      size += data.length;
-      chunks.push(data);
-    }
-    signal?.throwIfAborted();
-    return Buffer.concat(chunks, size);
-  } finally {
-    signal?.removeEventListener('abort', abort);
-  }
-}
-
 function providerCode(value) {
   if (!value || typeof value !== 'object') return null;
   const code = value.code ?? value.error?.code;
@@ -375,7 +353,7 @@ async function feishuProviderCode(error, signal) {
     seen.add(value);
     const directCode = providerCode(value);
     const data = value.response?.data ?? value.data;
-    if (directCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE) {
+    if (directCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE || directCode === FEISHU_RESOURCE_SIZE_LIMIT_CODE) {
       data?.destroy?.();
       return directCode;
     }
@@ -383,21 +361,22 @@ async function feishuProviderCode(error, signal) {
       const body = await readFeishuErrorBody(data, signal);
       try {
         const parsedCode = providerCode(JSON.parse(body));
-        if (parsedCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE) return parsedCode;
+        if (parsedCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE || parsedCode === FEISHU_RESOURCE_SIZE_LIMIT_CODE) return parsedCode;
       } catch {
         // Non-JSON provider failures keep the generic image download message.
       }
     } else {
       const dataCode = providerCode(data);
-      if (dataCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE) return dataCode;
+      if (dataCode === FEISHU_MISSING_MESSAGE_SCOPE_CODE || dataCode === FEISHU_RESOURCE_SIZE_LIMIT_CODE) return dataCode;
     }
     pending.push(value.cause);
   }
   return null;
 }
 
-async function feishuImageDownloadError(error, signal) {
-  if (await feishuProviderCode(error, signal) !== FEISHU_MISSING_MESSAGE_SCOPE_CODE) return error;
+async function feishuImageDownloadError(error, signal, code = undefined) {
+  if (code === undefined) code = await feishuProviderCode(error, signal);
+  if (code !== FEISHU_MISSING_MESSAGE_SCOPE_CODE) return error;
   return new ImagePromptError(
     'feishu-image-permission-required',
     'Feishu image download requires the im:message:readonly tenant scope',
@@ -406,33 +385,59 @@ async function feishuImageDownloadError(error, signal) {
   );
 }
 
-function feishuImageSource(event, client, key) {
-  return {
-    async load({ signal, maxBytes }) {
-      signal?.throwIfAborted();
-      let resource;
+async function feishuResourceStream(event, client, key, type, { signal, maxBytes } = {}) {
+  signal?.throwIfAborted();
+  const path = { message_id: event.message.message_id, file_key: key };
+  let resource;
+  try {
+    resource = await client?.im?.v1?.messageResource?.get?.({ path, params: { type } });
+  } catch (error) {
+    if (signal?.aborted) {
+      error?.response?.data?.destroy?.();
+      signal.throwIfAborted();
+    }
+    const code = await feishuProviderCode(error, signal);
+    if (code !== FEISHU_RESOURCE_SIZE_LIMIT_CODE) {
+      throw type === 'image' ? await feishuImageDownloadError(error, signal, code) : error;
+    }
+    return Readable.from((async function* ranges() {
       try {
-        resource = await client?.im?.v1?.messageResource?.get?.({
-          path: {
-            message_id: event.message.message_id,
-            file_key: key,
-          },
-          params: { type: 'image' },
-        });
+        yield* downloadFeishuResourceRanges(client, path, type, { signal, maxBytes });
       } catch (error) {
-        throw await feishuImageDownloadError(error, signal);
-      }
-      signal?.throwIfAborted();
-      const size = declaredSize(resource?.headers);
-      if (size !== null && size > maxBytes) {
-        resource?.getReadableStream?.().destroy?.();
-        throw new ImagePromptError(
-          'image-too-large',
-          `Feishu image declares ${size} bytes; the limit is ${maxBytes}`,
-          imageDownloadLimitMessage(maxBytes),
-        );
+        try {
+          throw type === 'image' ? await feishuImageDownloadError(error, signal) : error;
+        } finally {
+          error?.response?.data?.destroy?.();
+        }
       }
-      return readBoundedStream(resource?.getReadableStream?.(), { signal, maxBytes });
+    }()), { objectMode: false, signal });
+  }
+  const stream = resource?.getReadableStream?.();
+  try {
+    signal?.throwIfAborted();
+    const size = declaredSize(resource?.headers);
+    if (size !== null && size > maxBytes) {
+      throw new ImagePromptError(
+        'image-too-large',
+        `Feishu image declares ${size} bytes; the limit is ${maxBytes}`,
+        imageDownloadLimitMessage(maxBytes),
+      );
+    }
+    if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') {
+      throw new Error(`Feishu ${type} download returned no readable stream`);
+    }
+    return signal ? addAbortSignal(signal, stream) : stream;
+  } catch (error) {
+    stream?.destroy?.();
+    throw error;
+  }
+}
+
+function feishuImageSource(event, client, key) {
+  return {
+    async load({ signal, maxBytes }) {
+      const stream = await feishuResourceStream(event, client, key, 'image', { signal, maxBytes });
+      return readBoundedStream(stream, { signal, maxBytes });
     },
   };
 }
@@ -443,16 +448,8 @@ function feishuFileSource(event, client, file) {
   return {
     name: nonEmptyString(file?.file_name) ?? 'file',
     async load({ signal } = {}) {
-      signal?.throwIfAborted();
-      const resource = await client?.im?.v1?.messageResource?.get?.({
-        path: {
-          message_id: event.message.message_id,
-          file_key: key,
-        },
-        params: { type: 'file' },
-      });
-      signal?.throwIfAborted();
-      return readStream(resource?.getReadableStream?.(), { signal });
+      const stream = await feishuResourceStream(event, client, key, 'file', { signal });
+      return { stream };
     },
   };
 }

package/src/channels/feishu/multi-bot-controller.mjs

@@ -1,5 +1,5 @@
 import { atConnectionStage, createConnectionDiagnostics } from '../shared/connection-error.mjs';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { connectionTestMessage } from '../shared/connection-test.mjs';
 import { publicMessageFailure } from '../shared/message-failure.mjs';
 import { RegistrationManager } from './registration-manager.mjs';
@@ -563,10 +563,60 @@ export class MultiBotDshFeishuController {
     });
   }
 
+  async #deliveryAccount(config) {
+    let verified;
+    try {
+      const resolved = await this.#credentials.resolve(config.secretRef);
+      if (!resolved?.value) throw new Error('Account credentials unavailable');
+      verified = await this.#verifyApp({ appId: config.appId, appSecret: resolved.value, domain: config.domain });
+    } catch (cause) {
+      const error = new Error('Account credentials could not be verified', { cause });
+      error.code = 'account-unverified';
+      throw error;
+    }
+    if (!verified?.openId || verified.openId !== config.botOpenId) {
+      const error = new Error('Authenticated account identity changed');
+      error.code = 'account-changed';
+      throw error;
+    }
+    const fingerprint = createHash('sha256').update(JSON.stringify({
+      provider: 'feishu', domain: config.domain, appId: config.appId, botOpenId: verified.openId,
+    })).digest('hex');
+    return { fingerprint, ...(verified.name ? { name: verified.name } : {}) };
+  }
+
+  async describeDeliveryAccount(botId) {
+    this.#assertOpen('capability-unavailable');
+    return this.#withBotTransition(botId, async () => {
+      this.#assertOpen('capability-unavailable');
+      const config = this.#requireBot(botId);
+      const account = await this.#deliveryAccount(config);
+      this.#assertOpen('capability-unavailable');
+      return { version: 1, botId, channel: 'feishu', account,
+        connected: isConnected(connectionStatus(this.#runtimes.get(botId))),
+        capabilities: ['proactive-text-checked'] };
+    });
+  }
+
   async sendProactiveText(botId, target, text, options = {}) {
-    this.#assertOpen();
+    const checked = options.expectedFingerprint !== undefined;
+    this.#assertOpen(checked ? 'capability-unavailable' : undefined);
     return this.#withBotTransition(botId, async () => {
-      this.#requireBot(botId);
+      this.#assertOpen(checked ? 'capability-unavailable' : undefined);
+      const config = this.#requireBot(botId);
+      if (checked) {
+        const account = await this.#deliveryAccount(config);
+        if (account.fingerprint !== options.expectedFingerprint) {
+          const error = new Error('Authenticated account identity changed');
+          error.code = 'account-changed';
+          throw error;
+        }
+        // Account verification yields; a Registration can be replaced or disposed
+        // before the SDK request starts. Recheck its owner at the effect boundary.
+        options.beforeSend?.();
+        this.#assertOpen('capability-unavailable');
+        options.signal?.throwIfAborted();
+      }
       const runtime = this.#runtimes.get(botId);
       if (!isConnected(connectionStatus(runtime))
         || typeof runtime.sendProactiveText !== 'function') {
@@ -1386,8 +1436,12 @@ export class MultiBotDshFeishuController {
     return config;
   }
 
-  #assertOpen() {
-    if (this.#closed) throw new Error('The Feishu controller is closed');
+  #assertOpen(code) {
+    if (this.#closed) {
+      const error = new Error('The Feishu controller is closed');
+      if (code) error.code = code;
+      throw error;
+    }
   }
 
   #serializeConfig(operation) {

package/src/channels/feishu/resource-download.mjs

@@ -0,0 +1,120 @@
+import { ImagePromptError, imageDownloadLimitMessage } from '../shared/image-prompt.mjs';
+
+const RESOURCE_CHUNK_BYTES = 8 * 1024 * 1024;
+
+function headerValue(headers, name) {
+  if (typeof headers?.get === 'function') return headers.get(name) ?? null;
+  const key = Object.keys(headers ?? {}).find((key) => key.toLowerCase() === name);
+  return key ? headers[key] : null;
+}
+
+function checkLimit(size, maxBytes) {
+  if (size > maxBytes) {
+    throw new ImagePromptError(
+      'image-too-large',
+      `Feishu image exceeds ${maxBytes} bytes`,
+      imageDownloadLimitMessage(maxBytes),
+    );
+  }
+}
+
+function contentLength(headers) {
+  const value = headerValue(headers, 'content-length');
+  if (value === null || value === undefined) return null;
+  if (!/^\d+$/.test(String(value)) || !Number.isSafeInteger(Number(value))) {
+    throw new Error('Invalid Feishu resource Content-Length');
+  }
+  return Number(value);
+}
+
+function contentRange(headers, start, end, total) {
+  const match = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(headerValue(headers, 'content-range') ?? '');
+  if (!match) throw new Error('Invalid Feishu resource Content-Range');
+  const [first, last, size] = match.slice(1).map(Number);
+  if (![first, last, size].every(Number.isSafeInteger)
+    || first !== start || last < first || last > end || last >= size
+    || (total !== null && size !== total)) {
+    throw new Error('Inconsistent Feishu resource Content-Range');
+  }
+  return { size, length: last - first + 1 };
+}
+
+/** Stream sequential ranges; never buffer an ordinary file or publish a partial success. */
+export async function* downloadFeishuResourceRanges(client, path, type, { signal, maxBytes } = {}) {
+  let offset = 0;
+  let total = null;
+  do {
+    signal?.throwIfAborted();
+    const end = Math.min(
+      offset + RESOURCE_CHUNK_BYTES - 1,
+      (total ?? maxBytes ?? Number.MAX_SAFE_INTEGER) - 1,
+    );
+    let status;
+    const response = await client.request({
+      method: 'GET',
+      url: `open-apis/im/v1/messages/${encodeURIComponent(path.message_id)}/resources/${encodeURIComponent(path.file_key)}`,
+      params: { type },
+      headers: { Range: `bytes=${offset}-${end}`, 'Accept-Encoding': 'identity' },
+      responseType: 'stream',
+      $return_headers: true,
+      decompress: false,
+      signal,
+      // The SDK strips status from successful responses, including stream responses.
+      validateStatus(value) {
+        status = value;
+        return value >= 200 && value < 300;
+      },
+    });
+    const stream = response?.data;
+    const abort = () => stream?.destroy?.(signal.reason);
+    signal?.addEventListener('abort', abort, { once: true });
+    try {
+      signal?.throwIfAborted();
+      if (!stream || typeof stream[Symbol.asyncIterator] !== 'function') {
+        throw new Error('Feishu resource download returned no readable stream');
+      }
+      const encoding = headerValue(response.headers, 'content-encoding');
+      if (encoding && encoding !== 'identity') {
+        throw new Error('Unexpected Feishu resource Content-Encoding');
+      }
+      let length = contentLength(response.headers);
+      if (status === 206) {
+        const range = contentRange(response.headers, offset, end, total);
+        total = range.size;
+        checkLimit(total, maxBytes);
+        if (length !== null && length !== range.length) {
+          throw new Error('Feishu resource Content-Length disagrees with Content-Range');
+        }
+        length = range.length;
+      } else if (status === 200 && offset === 0) {
+        // A server may ignore the first Range. Read it once as a whole file.
+        if (headerValue(response.headers, 'content-range') !== null) {
+          throw new Error('Unexpected Feishu resource Content-Range on HTTP 200');
+        }
+        checkLimit(length, maxBytes);
+      } else {
+        throw new Error(`Unexpected Feishu resource range status: ${status}`);
+      }
+      let received = 0;
+      for await (const chunk of stream) {
+        signal?.throwIfAborted();
+        const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        received += data.length;
+        checkLimit(offset + received, maxBytes);
+        if (length !== null && received > length) {
+          throw new Error('Feishu resource body exceeds the declared length');
+        }
+        yield data;
+      }
+      signal?.throwIfAborted();
+      if (length !== null && received !== length) {
+        throw new Error('Feishu resource body does not match the declared length');
+      }
+      if (status === 200) return;
+      offset += received;
+    } finally {
+      signal?.removeEventListener('abort', abort);
+      stream?.destroy?.();
+    }
+  } while (offset < total);
+}

package/src/channels/shared/harness-client.mjs

@@ -1729,9 +1729,10 @@ export class HarnessClient {
       this.#registerInteractionOwnership(sessionId, ownership);
       this.#registerControlOwnership(ownership);
     }
-    // This is resource ownership, not a feature Gate: it lets the Host retain
-    // this Turn's snapshots until the channel has polled and claimed them.
-    const closeArtifactConsumer = outboundArtifactRegistry.openConsumer(sessionId, promptRpcId);
+    // Advertise delivery only when this request can actually claim its files.
+    const closeArtifactConsumer = typeof onArtifact === 'function'
+      ? outboundArtifactRegistry.openConsumer(sessionId, promptRpcId)
+      : null;
 
     try {
       const basePrompt = prompt;
@@ -1929,7 +1930,7 @@ export class HarnessClient {
           }
         }
       }
-      closeArtifactConsumer();
+      closeArtifactConsumer?.();
       if (ownership) {
         this.#unregisterControlOwnership(ownership);
         this.#unregisterInteractionOwnership(sessionId, ownership);

package/src/channels/shared/i18n-en/feishu.mjs

@@ -143,6 +143,8 @@ export default {
   '请输入补充指令后再提交。': 'Enter an instruction before submitting.',
   '操作过于频繁，请稍后再试。': 'Too many card actions are pending. Please try again shortly.',
   '卡片操作失败，请稍后重试。': 'The card action failed. Please try again later.',
+  '新会话操作的卡片状态未能更新，请发送 /m 重新打开菜单。':
+    'Could not update the new-session card status. Send /m to reopen the menu.',
   '请先选择至少一个会话。': 'Select at least one session first.',
   '已批量关注 {count} 个会话。': 'Now watching {count} sessions.',
   '已批量关注 {count} 个会话，另有 {failed} 个未成功。':
@@ -187,6 +189,11 @@ export default {
   '🤖 切换预设': '🤖 Switch preset',
   '🧠 切换模型': '🧠 Switch model',
   '🆕 新会话': '🆕 New session',
+  '正在开启…': 'Starting…',
+  '已执行：新会话': 'Done: new session',
+  '正在开启新会话…': 'Starting a new session…',
+  '已执行：新会话。发送消息即可开始。': 'Done: new session. Send a message to start.',
+  '新会话操作失败：{message}': 'New session action failed: {message}',
   '📋 会话/关注': '📋 Sessions / watches',
   '🗂 工作区列表': '🗂 Workspace list',
   '**任务控制**': '**Task controls**',

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