@modesto_ma/dsh-channels 0.3.0 → 0.5.0-beta.1

package/src/routing/inbound.ts

@@ -10,20 +10,31 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import type { AgentHandle, HostContext, SessionId, UserMessage, Workspace } from '../dsh-types.ts'
-import type { FeishuConfig } from '../config.ts'
+import type {
+  AgentHandle, AttachmentStore, ContentBlock, HostContext, SessionId, UserMessage, Workspace,
+} from '../dsh-types.ts'
+import type { AttachmentStoreMode, FeishuConfig } from '../config.ts'
 import { buildCard, buildOnboardingCard, initialStreamingCard } from '../cards.ts'
 import { RouteOperationQueue } from '../commands.ts'
 import { chatRouteKey, sessionDirOf } from '../domain.ts'
 import type { FeishuDomainHandle, RouteRecord } from '../domain.ts'
 import type { CardDelivery } from '../feishu/delivery.ts'
 import {
-  adoptStagedAttachments, attachmentsDir, hasAttachmentPayload,
+  adoptStagedAttachments, attachmentsDir, attachmentResources, hasAttachmentPayload,
+  inboundAttachmentState, prefetchImageAttachments,
 } from '../feishu/inbound-attachments.ts'
-import { AttachmentIntake } from '../feishu/inbound-attachments.ts'
-import type { AttachmentArchiveResult, AttachmentFailure } from '../feishu/inbound-attachments.ts'
-import type { NormalizedMessage } from '../feishu-channel.ts'
+import type {
+  AttachmentFailure, InboundAttachmentState,
+} from '../feishu/inbound-attachments.ts'
+import { buildFeishuContextBlock, manifestEntriesOfKnownMessage, triggerManifestAttachments } from '../feishu/manifest.ts'
+import {
+  InboundAttachmentStore, NativeAttachmentStore, effectiveAttachmentMode,
+} from '../feishu/native-attachments.ts'
+import type { InboundAttachmentStoreResult } from '../feishu/native-attachments.ts'
+import type { KnownAttachmentMessageInput, KnownAttachmentSource } from '../feishu/tools.ts'
+import type { FeishuChannel, NormalizedMessage } from '../feishu-channel.ts'
 import type { QuestionAnswerer } from '../interactions/questions.ts'
+import type { ApprovalAnswerer, ApprovalTextResult } from '../interactions/approvals.ts'
 import type { InflightRepair } from '../session/repair.ts'
 import type { SessionManager } from '../session/manager.ts'
 import type { RouteStore } from '../session/routes.ts'
@@ -55,6 +66,45 @@ export interface InboundAccessPort {
   ownsRoute(msg: NormalizedMessage, record: RouteRecord): boolean
 }
 
+/**
+ * Read-only message access the inbound turn assembly needs: the quoted message
+ * of the triggering message and the bounded first-turn topic history.
+ *
+ * Both methods return `undefined` for "nothing to show" (no quoted message,
+ * read failed, missing permission); implementations never throw for expected
+ * failures, and a silently degraded read must never block the turn (AC6).
+ */
+export interface InboundMessageReadPort {
+  /**
+   * Resolve the message the triggering message replies to. The returned
+   * `block` is the ready-to-inject `<feishu_quote>` prompt block and `message`
+   * the quoted message's whitelist registration (merged-forward containers are
+   * registered by container id).
+   */
+  quote(input: {
+    messageId: string
+    record: RouteRecord
+  }): Promise<{ block: string; message?: KnownAttachmentMessageInput } | undefined>
+  /**
+   * Resolve the most recent topic messages for the first turn of a new
+   * Session: the ready-to-inject `<feishu_history>` block plus the per-message
+   * whitelist registrations in chronological order.
+   */
+  history(input: {
+    record: RouteRecord
+    limit: number
+    excludeMessageIds: readonly string[]
+  }): Promise<{ block: string; messages: readonly KnownAttachmentMessageInput[] } | undefined>
+}
+
+/** Live trigger-image prefetch policy (see `prefetchImages` config). */
+export interface AttachmentPrefetchPolicy {
+  readonly enabled: boolean
+  readonly maxImageBytes: number
+  readonly maxTotalBytes: number
+  readonly timeoutMs: number
+}
+
 export interface InboundDeps {
   ctx: HostContext
   config: FeishuConfig
@@ -64,16 +114,47 @@ export interface InboundDeps {
   repair: InflightRepair
   delivery: CardDelivery
   sessions: SessionManager
-  attachments: AttachmentIntake
+  /** Configured inbound attachment backend (`attachmentStore`). */
+  attachmentMode(): AttachmentStoreMode
+  /** Host-level native attachment library; undefined = not mounted. */
+  nativeAttachments(): AttachmentStore | undefined
+  /** Backend-selecting archive/fallback store (legacy workspace download). */
+  attachmentStore: InboundAttachmentStore
+  /**
+   * Pre-authorize a message's attachments for `feishu_attachment_fetch`:
+   * `trigger` (the triggering message) by default, `quote`/`history`/`recent`
+   * for the messages this turn's excerpt, history and manifest blocks name.
+   */
+  noteKnownAttachments(
+    record: RouteRecord,
+    message: KnownAttachmentMessageInput,
+    source?: KnownAttachmentSource,
+  ): void
+  /**
+   * Read-only message access: quoted-message excerpt, first-turn topic
+   * history, and recent attachment messages. Failures degrade silently to an
+   * absent value (never a throw into the turn).
+   */
+  messageRead: InboundMessageReadPort
+  /** Live image-prefetch policy for triggering messages. */
+  prefetchImages(): AttachmentPrefetchPolicy
   /** Channel-plane access control (administrator + whitelist gates). */
   access: InboundAccessPort
   /** Shared per-route FIFO admission (commands and turns must not interleave). */
   queue: RouteOperationQueue
   streamer(): TurnStreamer | undefined
   questionAnswerer(): QuestionAnswerer | undefined
+  approvalAnswerer(): ApprovalAnswerer | undefined
   commands: CommandPlanePort
 }
 
+/** Confirmation line for each keyword approval reply. */
+const APPROVAL_TEXT_REPLIES: Record<Exclude<ApprovalTextResult, 'superseded'>, string> = {
+  allowed: '已允许本次操作。',
+  remembered: '已允许，本话题内同类操作不再询问。',
+  denied: '已拒绝本次操作。',
+}
+
 /**
  * User-facing text for attachments that could not be archived. Delivered as a
  * plain reply (never a card) so the user learns why the Agent cannot read a
@@ -98,6 +179,55 @@ export function feishuUserMessage(text: string): UserMessage {
   } as unknown as UserMessage
 }
 
+/**
+ * Whitelist registration input for one triggering message.
+ *
+ * The fetch tool requires explicit per-route authorization; the trigger
+ * message is the one exception the admission layer can vouch for. Resources
+ * are copied from the same normalization the manifest uses, and merged-forward
+ * containers carry no direct resources (the tool expands them through the
+ * container id, per the P0 rule).
+ */
+export function knownAttachmentMessageOf(msg: NormalizedMessage): KnownAttachmentMessageInput {
+  const forwarded = msg.rawContentType === 'merge_forward'
+  const resources = attachmentResources(msg).map(resource => ({
+    type: resource.type,
+    fileKey: resource.fileKey,
+    ...(resource.fileName === undefined ? {} : { fileName: resource.fileName }),
+    ...(resource.folder === true ? { folder: true } : {}),
+  }))
+  return {
+    messageId: msg.messageId,
+    kind: forwarded ? 'merge_forward' : 'message',
+    resources,
+    senderUserId: msg.senderId,
+  }
+}
+
+/** Feishu message-id shape accepted for quote resolution (`om_...`). */
+const QUOTE_MESSAGE_ID = /^om_[A-Za-z0-9_-]{1,128}$/u
+
+/** Read-only prompt context assembled for one turn (quote excerpt + history). */
+interface TurnReadContext {
+  /** Ready `<feishu_quote>` text block, when the message quotes something. */
+  quoteBlock?: string
+  /** Whitelist registration of the quoted message (manifest/discoverability). */
+  quoteMessage?: KnownAttachmentMessageInput
+  /** Ready `<feishu_history>` text block, first turn only. */
+  historyBlock?: string
+}
+
+/** Per-turn inputs of the prompt assembly. */
+interface TurnDeliveryOptions {
+  /** New Session's first turn: attach the bounded topic history bootstrap. */
+  firstTurn?: boolean
+  /**
+   * Message ids never shown in the history block or listed as recent
+   * attachments (trigger + streaming card).
+   */
+  excludeMessageIds?: readonly string[]
+}
+
 export class InboundRouter {
   /**
    * In-process dedup guard: message id → accept timestamp. Set synchronously
@@ -114,6 +244,13 @@ export class InboundRouter {
    * overwrites, or the "no route, no mention" drop window.
    */
   private readonly establishing = new Map<string, Promise<RouteRecord>>()
+  /**
+   * route key → first-turn delivery gate. A new Session persists its route
+   * before the prompt is assembled (image prefetch); a message that observes
+   * the route in that window must wait for the first followup instead of
+   * racing it, otherwise the topic's turns reach the model out of order.
+   */
+  private readonly firstDeliveries = new Map<string, { promise: Promise<void>; release(): void }>()
 
   constructor(private readonly deps: InboundDeps) {}
 
@@ -124,10 +261,11 @@ export class InboundRouter {
   private get repair(): InflightRepair { return this.deps.repair }
   private get delivery(): CardDelivery { return this.deps.delivery }
   private get sessions(): SessionManager { return this.deps.sessions }
-  private get attachments(): AttachmentIntake { return this.deps.attachments }
+  private get attachmentStore(): InboundAttachmentStore { return this.deps.attachmentStore }
   private get routeOperations(): RouteOperationQueue { return this.deps.queue }
   private get streamer(): TurnStreamer | undefined { return this.deps.streamer() }
   private get questionAnswerer(): QuestionAnswerer | undefined { return this.deps.questionAnswerer() }
+  private get approvalAnswerer(): ApprovalAnswerer | undefined { return this.deps.approvalAnswerer() }
   private get domain(): FeishuDomainHandle | undefined { return this.deps.domain() }
   private get access(): InboundAccessPort { return this.deps.access }
 
@@ -138,6 +276,28 @@ export class InboundRouter {
     }
   }
 
+  /**
+   * Open the first-turn delivery gate of one route. Registered BEFORE the
+   * route record is persisted, so any message that can observe the route also
+   * observes its gate. The returned closer must be called exactly once.
+   */
+  private openDeliveryGate(key: string): () => void {
+    let settle!: () => void
+    const promise = new Promise<void>((resolve) => { settle = resolve })
+    const release = (): void => {
+      if (this.firstDeliveries.get(key)?.promise === promise) this.firstDeliveries.delete(key)
+      settle()
+    }
+    this.firstDeliveries.set(key, { promise, release })
+    return release
+  }
+
+  /** Wait for the in-flight first followup of a route, when one is pending. */
+  private async awaitFirstDelivery(key: string): Promise<void> {
+    const pending = this.firstDeliveries.get(key)
+    if (pending !== undefined) await pending.promise.catch(() => undefined)
+  }
+
 /**
    * Send the one-time onboarding card for a private chat, then remember the
    * chat in the domain global. Best-effort: a storage failure only risks a
@@ -163,12 +323,14 @@ export class InboundRouter {
   clear(): void {
     this.accepted.clear()
     this.establishing.clear()
+    // Resolve pending gates before dropping them so a message waiting on a
+    // first-turn delivery never stays suspended across a teardown.
+    for (const entry of [...this.firstDeliveries.values()]) entry.release()
+    this.firstDeliveries.clear()
   }
 
   /** Entry point: one normalized inbound message. */
   async handle(msg: NormalizedMessage): Promise<void> {
-    const botId = this.delivery.requireChannel().botOpenId()
-    if (botId !== undefined && msg.senderId === botId) return
     if (msg.chatType !== 'p2p' && msg.chatType !== 'group') return
     let content = (msg.content ?? '').trim()
     if (content === '') return
@@ -223,19 +385,44 @@ export class InboundRouter {
       return
     }
 
-    // Attachments are archived before session work: an attachment-only message
-    // produces no model turn, and a caption mixed with attachments keeps only
-    // the caption as the prompt. The Agent reads the files on demand later.
-    const archived = await this.archiveAttachments(msg)
-    if (archived !== undefined) {
-      if (archived.failures.length > 0) {
-        await this.delivery.noticeText(msg, buildAttachmentFailureNotice(archived.failures))
+    // Attachment admission. The effective backend selects between the legacy
+    // synchronous workspace download (`attachmentStore: 'archive'`, or a
+    // native deployment whose host does not mount the attachment service) and
+    // the v2 lazy pipeline: no attachment bytes are downloaded before the
+    // session/card exists, and files are never downloaded by admission at all.
+    if (this.attachmentBackend() === 'archive') {
+      // Attachments are archived before session work: an attachment-only
+      // message produces no model turn, and a caption mixed with attachments
+      // keeps only the caption as the prompt. The Agent reads the files on
+      // demand later.
+      const archived = await this.archiveAttachments(msg)
+      if (archived !== undefined) {
+        if (archived.failures.length > 0) {
+          await this.delivery.noticeText(msg, buildAttachmentFailureNotice(archived.failures))
+        }
+        if (archived.attachmentOnly) return
+        content = archived.text
+        if (content === '') return
+      }
+    } else {
+      // Native pipeline: classify without downloading. Attachment-only
+      // messages and messages that cannot start a turn stay inert (no reply,
+      // no reaction, no Session); a mixed caption becomes the prompt with its
+      // placeholders stripped.
+      const state = inboundAttachmentState(msg)
+      if (state.hasPayload) {
+        const resolution = this.resolveNativeAttachmentMessage(msg, state)
+        if (resolution.kind === 'silent') return
+        content = resolution.text
+        if (content === '') return
       }
-      if (archived.attachmentOnly) return
-      content = archived.text
-      if (content === '') return
     }
 
+    // A session blocked on an approval card reads the owner's reply as the
+    // decision; any other text rejects the card and continues below as the
+    // next instruction.
+    if (await this.tryAnswerPendingApproval(msg, content)) return
+
     // A session blocked on `ask_user_question` has no other use for an inbound
     // text message: the next reply becomes the free-text answer.
     if (await this.tryAnswerPendingQuestion(msg, content)) return
@@ -247,6 +434,9 @@ export class InboundRouter {
         // Only the topic creator may continue its Session (admission already
         // passed, but another authorized user could be in the same group).
         if (!this.access.ownsRoute(msg, record)) return
+        // The route may be durable while its first turn is still being
+        // prepared (prefetch): stay behind that turn instead of racing it.
+        await this.awaitFirstDelivery(record.key)
         await this.routeOperations.run(record.key, () => {
           if (!this.started) return
           return this.continueSession(msg, this.routes.get(record.key) ?? record, content)
@@ -260,6 +450,7 @@ export class InboundRouter {
     const chatRecord = this.routes.get(chatKey)
     if (chatRecord !== undefined) {
       if (!this.access.ownsRoute(msg, chatRecord)) return
+      await this.awaitFirstDelivery(chatRecord.key)
       await this.routeOperations.run(chatRecord.key, () => {
         if (!this.started) return
         return this.continueSession(msg, this.routes.get(chatRecord.key) ?? chatRecord, content)
@@ -292,14 +483,17 @@ export class InboundRouter {
   }
 
   /**
-   * Archive the attachment payload of one message, if any. Returns `undefined`
-   * when the message carries no archivable payload; otherwise the archive
-   * result whose `text` is the remaining prompt (possibly empty).
+   * Legacy archive path: download every resource of one message into the
+   * conversation workspace (or its pre-topic staging directory). Returns
+   * `undefined` when the message carries no archivable payload; otherwise the
+   * storage result whose `text` is the remaining prompt (possibly empty).
    *
    * Runs inside the same per-route FIFO as turns so a caption sent right after
-   * a file is queued behind the file's download instead of racing it.
+   * a file is queued behind the file's download instead of racing it. Only the
+   * `archive` effective backend calls this; the native pipeline never downloads
+   * files during admission.
    */
-  private async archiveAttachments(msg: NormalizedMessage): Promise<AttachmentArchiveResult | undefined> {
+  private async archiveAttachments(msg: NormalizedMessage): Promise<InboundAttachmentStoreResult | undefined> {
     if (!hasAttachmentPayload(msg)) return undefined
 
     const threadRecord = msg.threadId === undefined ? undefined : this.routes.get(msg.threadId)
@@ -312,20 +506,387 @@ export class InboundRouter {
     // already owns does not.
     if (record === undefined && msg.chatType === 'group'
       && this.config.requireMention && !msg.mentionedBot) {
-      return { saved: 0, failed: 0, failures: [], attachmentOnly: true, text: '' }
+      return {
+        mode: 'archive', saved: 0, failed: 0, failures: [], stored: [], attachmentOnly: true, text: '',
+      }
     }
 
     return await this.routeOperations.run(record?.key ?? chatKey, async () => {
-      if (!this.started) return { saved: 0, failed: 0, failures: [], attachmentOnly: true, text: '' }
+      if (!this.started) {
+        return {
+          mode: 'archive', saved: 0, failed: 0, failures: [], stored: [], attachmentOnly: true, text: '',
+        } satisfies InboundAttachmentStoreResult
+      }
       // An existing topic already has its own working directory; a
       // conversation without one stages files below baseDir until its first
       // Session creates the topic directory and adopts them.
       const directory = record === undefined
         ? stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId)
         : attachmentsDir(sessionDirOf(record))
-      return await this.attachments.archive(msg, directory)
+      return await this.attachmentStore.store(msg, directory)
     })
   }
+
+  /**
+   * One-time legacy migration: move files older plugin versions staged below
+   * `<baseDir>/_staging/...` into this conversation's topic directory.
+   *
+   * The v2 pipeline stores inbound attachments in the DSH native library and
+   * never writes staging, so this path only adopts files left by a pre-v2
+   * deployment. It is kept for one release cycle after attachment_pipeline_v2
+   * ships and is then removed together with `stagingPathFor` (decisions D12).
+   * A successful adoption logs one warning so operators can retire the old
+   * data instead of relying on this compatibility path indefinitely.
+   */
+  private async adoptLegacyStagedAttachments(
+    msg: NormalizedMessage,
+    sessionDir: string,
+    warn: (message: string, ...args: unknown[]) => void,
+  ): Promise<void> {
+    const adopted = await adoptStagedAttachments(
+      stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId),
+      sessionDir,
+    ).catch((error: unknown) => {
+      warn('dsh-channels: adopting staged attachments failed: %s', String(error))
+      return 0
+    })
+    if (adopted > 0) {
+      warn(
+        'dsh-channels: adopted %d legacy staged attachment(s) into %s; the one-time _staging migration is deprecated and will be removed after one release cycle (decisions D12)',
+        adopted,
+        sessionDir,
+      )
+    }
+  }
+
+  /**
+   * Effective inbound attachment backend for the live deployment.
+   *
+   * The lazy native pipeline can only deliver files through
+   * `feishu_attachment_fetch`; with that tool disabled (or without the host
+   * attachment library) the deployment falls back to the legacy archive
+   * backend, where the Agent reads the downloaded workspace copies instead of
+   * a manifest that would name an unavailable tool.
+   */
+  private attachmentBackend(): AttachmentStoreMode {
+    return effectiveAttachmentMode(
+      this.deps.attachmentMode(),
+      this.deps.nativeAttachments(),
+      this.config.feishuTools.attachmentFetch,
+      this.config.acceptAttachments,
+    )
+  }
+
+  /**
+   * Native-pipeline attachment decision for one message, without downloading.
+   *
+   * Returns `{ kind: 'silent' }` when the message must stay inert (no reply,
+   * no reaction, no Session, no download, no local state; a later turn finds
+   * it through the recent-attachment read) and `{ kind: 'prompt', text }` when
+   * a model turn starts with this text. The caller keeps the message flowing
+   * through the normal route decision tree.
+   */
+  private resolveNativeAttachmentMessage(
+    msg: NormalizedMessage,
+    state: InboundAttachmentState,
+  ): { kind: 'silent' } | { kind: 'prompt'; text: string } {
+    if (state.attachmentOnly) return { kind: 'silent' }
+    if (!this.config.acceptAttachments) return { kind: 'prompt', text: state.text }
+
+    // Group messages without an @-mention (and without an already-bound topic)
+    // never start a turn; their attachments stay discoverable from the topic a
+    // later @-mentioned message creates (Roadmap AC-4).
+    const threadRecord = msg.threadId === undefined ? undefined : this.routes.get(msg.threadId)
+    const chatKey = chatRouteKey(msg.chatType, msg.chatId, msg.senderId)
+    const chatRecord = threadRecord === undefined ? this.routes.get(chatKey) : undefined
+    const requiresMention = msg.chatType === 'group' && this.config.requireMention && !msg.mentionedBot
+    const triggers = threadRecord !== undefined || chatRecord !== undefined
+      || this.establishing.has(chatKey) || !requiresMention
+    return triggers ? { kind: 'prompt', text: state.text } : { kind: 'silent' }
+  }
+
+  /**
+   * Build the first-turn user message for the native pipeline: the caption
+   * text, the quoted-message excerpt, the prefetched trigger images, the
+   * `<feishu_context>` manifest block listing every attachment still unloaded,
+   * and (first turn only) the `<feishu_history>` topic bootstrap. Optional
+   * blocks are omitted entirely (no token cost) when empty.
+   *
+   * Runs after the session/card/route exist and before `followup`; only the
+   * triggering message's images are prefetched (bounded and short-timeout),
+   * files never are. Block order is stable: text, quote, images, manifest,
+   * history.
+   */
+  private async nativeTurnMessage(
+    msg: NormalizedMessage,
+    record: RouteRecord,
+    content: string,
+    options: TurnDeliveryOptions,
+  ): Promise<UserMessage> {
+    const message = feishuUserMessage(content)
+    const blocks: ContentBlock[] = content === '' ? [] : [{ type: 'text', text: content }]
+    const state = inboundAttachmentState(msg)
+    const attachmentPipeline = this.config.acceptAttachments
+
+    // Authorize the trigger message before any prefetch attempt so the model
+    // can fetch whatever the prefetch could not load.
+    if (state.hasPayload && attachmentPipeline) {
+      try {
+        this.deps.noteKnownAttachments(record, knownAttachmentMessageOf(msg))
+      } catch (error) {
+        this.ctx.logger?.warn?.(
+          'dsh-channels: authorizing trigger attachments of %s failed: %s',
+          msg.messageId, String(error),
+        )
+      }
+    }
+
+    // Quote excerpt + first-turn history: read only after the trigger message
+    // is durable and whitelisted (the record exists and the message is known),
+    // so a quoted/earlier attachment can reference the trigger's route. The
+    // read runs CONCURRENTLY with the bounded image prefetch below: neither
+    // waits for the other, and a failed read degrades to its absence (AC6).
+    const contextPromise = this.readTurnContext(msg, record, options)
+
+    const loadedFileKeys = new Set<string>()
+    const prefetchedBlocks: ContentBlock[] = []
+    const policy = this.deps.prefetchImages()
+    const images = state.resources.filter(resource => resource.type === 'image')
+    if (state.hasPayload && attachmentPipeline && policy.enabled && images.length > 0) {
+      const prefetched = await prefetchImageAttachments({
+        msg,
+        resources: images,
+        channel: this.liveChannel(),
+        maxImageBytes: policy.maxImageBytes,
+        maxTotalBytes: policy.maxTotalBytes,
+        timeoutMs: policy.timeoutMs,
+        saveImage: async (bytes, name) => {
+          const store = new NativeAttachmentStore({ service: () => this.deps.nativeAttachments() })
+          const saved = await store.saveImage({ bytes, ...(name === undefined ? {} : { name }) })
+          return saved.ok
+            ? { ok: true, block: saved.value.block }
+            : { ok: false, reason: saved.reason }
+        },
+        warn: (warning, ...args) => this.ctx.logger?.warn?.(warning, ...args),
+      })
+      // Spread each block into a plain object literal: the host `ContentBlock`
+      // union carries an index signature that the named `ImageBlock` interface
+      // does not declare, and the clone is structurally identical.
+      prefetchedBlocks.push(...prefetched.blocks.map(block => ({ ...block })))
+      for (const fileKey of prefetched.loadedFileKeys) loadedFileKeys.add(fileKey)
+    }
+    // Stable block order: text, quote, image blocks, manifest, history.
+    const context = await contextPromise
+    if (context.quoteBlock !== undefined) blocks.push({ type: 'text', text: context.quoteBlock })
+    blocks.push(...prefetchedBlocks)
+
+    const manifest = attachmentPipeline
+      ? buildFeishuContextBlock({
+        trigger: triggerManifestAttachments(msg, loadedFileKeys),
+        // A quoted file must be DISCOVERABLE in the manifest (AC1): the quote
+        // block names it, and this row carries the message_id/file_key the
+        // model needs for feishu_attachment_fetch.
+        ...(context.quoteMessage === undefined
+          ? {}
+          : { quote: manifestEntriesOfKnownMessage(context.quoteMessage) }),
+      })
+      : ''
+    if (manifest !== '') blocks.push({ type: 'text', text: manifest })
+    if (context.historyBlock !== undefined) blocks.push({ type: 'text', text: context.historyBlock })
+    // A trigger always carries caption text, but keep the message well-formed
+    // if a future call path ever reaches here with nothing to say.
+    if (blocks.length === 0) blocks.push({ type: 'text', text: '' })
+    message.content = blocks
+    return message
+  }
+
+  /**
+   * Deliver the prompt for one turn. The lazy native pipeline assembles the
+   * attachment blocks + manifest; every other deployment keeps the plain text
+   * prompt. Both backends still carry the quoted-message excerpt and (first
+   * turn only) the bounded topic history: those are read-only text context and
+   * remain useful without the lazy fetch tool.
+   *
+   * A failure in prompt assembly degrades to the plain text prompt (the turn
+   * must run); a failed quote/history read degrades silently to its absence.
+   */
+  private async deliverTurnMessage(
+    msg: NormalizedMessage,
+    record: RouteRecord,
+    content: string,
+    options: TurnDeliveryOptions = {},
+  ): Promise<UserMessage> {
+    try {
+      if (this.attachmentBackend() !== 'native') {
+        return await this.textTurnMessage(msg, record, content, options)
+      }
+      return await this.nativeTurnMessage(msg, record, content, options)
+    } catch (error) {
+      this.ctx.logger?.warn?.(
+        'dsh-channels: assembling the attachment manifest for %s failed: %s',
+        msg.messageId, String(error),
+      )
+      return feishuUserMessage(content)
+    }
+  }
+
+  /**
+   * Text-only turn prompt (archive/fallback deployments): the legacy single
+   * text block, extended with the quote excerpt and the first-turn history
+   * block when they exist. With nothing extra this is byte-identical to
+   * {@link feishuUserMessage}.
+   */
+  private async textTurnMessage(
+    msg: NormalizedMessage,
+    record: RouteRecord,
+    content: string,
+    options: TurnDeliveryOptions,
+  ): Promise<UserMessage> {
+    const context = await this.readTurnContext(msg, record, options)
+    if (context.quoteBlock === undefined && context.historyBlock === undefined) {
+      return feishuUserMessage(content)
+    }
+    const blocks: ContentBlock[] = content === '' ? [] : [{ type: 'text', text: content }]
+    if (context.quoteBlock !== undefined) blocks.push({ type: 'text', text: context.quoteBlock })
+    if (context.historyBlock !== undefined) blocks.push({ type: 'text', text: context.historyBlock })
+    const message = feishuUserMessage(content)
+    message.content = blocks
+    return message
+  }
+
+  /**
+   * Read the read-only prompt context of one turn: the quoted-message excerpt
+   * (every triggered message, per D3) and the bounded topic history (new
+   * Session's first turn only). Both reads run concurrently and are bounded by
+   * a short prompt budget, so a slow/stalled read can delay the turn by at
+   * most {@link PROMPT_CONTEXT_TIMEOUT} — never by a model-tool timeout (AC4:
+   * the first turn is not blocked by enrichment).
+   */
+  private async readTurnContext(
+    msg: NormalizedMessage,
+    record: RouteRecord,
+    options: TurnDeliveryOptions,
+  ): Promise<TurnReadContext> {
+    const [quote, historyBlock] = await Promise.all([
+      this.readQuoteBlock(msg, record),
+      this.readHistoryBlock(record, options),
+    ])
+    return {
+      ...(quote === undefined
+        ? {}
+        : {
+          quoteBlock: quote.block,
+          ...(quote.message === undefined ? {} : { quoteMessage: quote.message }),
+        }),
+      ...(historyBlock === undefined ? {} : { historyBlock }),
+    }
+  }
+
+  /**
+   * Resolve the quoted message into a `<feishu_quote>` block and register the
+   * quoted message (including a merged-forward container, by container id) in
+   * the route's attachment whitelist. Only messages that already triggered a
+   * turn reach this point (D3: quoting the bot without @ never triggers).
+   */
+  private async readQuoteBlock(
+    msg: NormalizedMessage,
+    record: RouteRecord,
+  ): Promise<{ block: string; message?: KnownAttachmentMessageInput } | undefined> {
+    const messageId = msg.replyToMessageId
+    if (messageId === undefined || !QUOTE_MESSAGE_ID.test(messageId)) return undefined
+    try {
+      const quote = await this.deps.messageRead.quote({ messageId, record })
+      if (quote === undefined) return undefined
+      if (quote.message !== undefined) {
+        try {
+          this.deps.noteKnownAttachments(record, quote.message, 'quote')
+        } catch (error) {
+          // Best-effort whitelist registration: the excerpt is still useful.
+          this.ctx.logger?.debug?.(
+            'dsh-channels: registering quoted attachments of %s failed: %s',
+            messageId, String(error),
+          )
+        }
+      }
+      return quote.block === '' ? undefined : quote
+    } catch (error) {
+      // Missing read scope / deleted message / channel down: no excerpt.
+      this.ctx.logger?.debug?.(
+        'dsh-channels: reading quoted message %s failed: %s', messageId, String(error),
+      )
+      return undefined
+    }
+  }
+
+  /**
+   * Resolve the first-turn topic history into a `<feishu_history>` block and
+   * register every message it shows in the route's attachment whitelist.
+   * Disabled by `historyBootstrapLimit: 0`; continuations never read history.
+   */
+  private async readHistoryBlock(
+    record: RouteRecord,
+    options: TurnDeliveryOptions,
+  ): Promise<string | undefined> {
+    if (options.firstTurn !== true) return undefined
+    const limit = this.config.historyBootstrapLimit
+    if (!Number.isFinite(limit) || limit <= 0) return undefined
+    try {
+      const history = await this.deps.messageRead.history({
+        record,
+        limit,
+        excludeMessageIds: options.excludeMessageIds ?? [],
+      })
+      if (history === undefined) return undefined
+      for (const message of history.messages) {
+        try {
+          this.deps.noteKnownAttachments(record, message, 'history')
+        } catch (error) {
+          this.ctx.logger?.debug?.(
+            'dsh-channels: registering history attachments of %s failed: %s',
+            message.messageId, String(error),
+          )
+        }
+      }
+      return history.block === '' ? undefined : history.block
+    } catch (error) {
+      this.ctx.logger?.debug?.(
+        'dsh-channels: reading topic history for %s failed: %s', record.key, String(error),
+      )
+      return undefined
+    }
+  }
+
+  /** Live channel accessor for best-effort prefetch; undefined when gone. */
+  private liveChannel(): FeishuChannel | undefined {
+    try {
+      return this.delivery.requireChannel()
+    } catch {
+      return undefined
+    }
+  }
+
+  /**
+   * Consume one plain reply as an approval decision. Only the topic owner's
+   * replies in a session with an undecided approval card are intercepted.
+   * @returns true when the reply was a keyword decision and is fully handled;
+   * false when nothing was pending or the reply rejected the pending cards and
+   * must still be delivered as the next instruction.
+   */
+  private async tryAnswerPendingApproval(msg: NormalizedMessage, content: string): Promise<boolean> {
+    const answerer = this.approvalAnswerer
+    if (answerer === undefined || answerer.pendingCount() === 0) return false
+    const route = await this.commandRoute(msg)
+    if (route === undefined || !this.access.ownsRoute(msg, route)) return false
+    if (!answerer.hasPendingFor(route.sessionId)) return false
+    const result = answerer.submitText(route.sessionId, content)
+    if (result === undefined || result === 'superseded') return false
+    await this.delivery.commandCard(msg, {
+      kind: 'success', command: 'approval', sessionId: route.sessionId,
+      text: APPROVAL_TEXT_REPLIES[result],
+    }, { createThread: false })
+    return true
+  }
+
   /**
    * Consume one plain reply as an `ask_user_question` free-text answer.
    *
@@ -467,13 +1028,9 @@ export class InboundRouter {
           warn('dsh-channels: attaching initial session %s to workspace failed: %s', sessionId, String(error))
         })
       }
-      // Files staged before this topic existed belong to this conversation.
-      await adoptStagedAttachments(
-        stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId),
-        placement.sessionDir,
-      ).catch((error: unknown) => {
-        warn('dsh-channels: adopting staged attachments failed: %s', String(error))
-      })
+      // Files staged before this topic existed by a pre-v2 deployment belong
+      // to this conversation (one-time legacy adoption, see decisions D12).
+      await this.adoptLegacyStagedAttachments(msg, placement.sessionDir, warn)
       await this.sessions.mountGuidance(handle.agent, placement.sessionDir)
     } catch (error) {
       // The card lands in a final failure state — no repair needed later. A
@@ -494,7 +1051,7 @@ export class InboundRouter {
       sessionId,
       chatId: msg.chatId,
       chatType: msg.chatType,
-      senderOpenId: msg.senderId,
+      senderUserId: msg.senderId,
       workspacePath: workspace.path,
       sessionDir: placement.sessionDir,
       ...(placement.worktreeBranch === undefined ? {} : { worktreeBranch: placement.worktreeBranch }),
@@ -503,11 +1060,28 @@ export class InboundRouter {
       lastActivityAt: createdAt,
       sessionHistory: [{ sessionId, createdAt }],
     }
-    await this.routes.put(key, record)
+    // The delivery gate is opened BEFORE the route becomes durable: a message
+    // that can see the route must also wait for this Session's first followup
+    // (the image prefetch below keeps the route-to-followup window open).
+    const closeDeliveryGate = this.openDeliveryGate(key)
+    try {
+      await this.routes.put(key, record)
 
-    // 6. Stream into the card and hand the message to the driver.
-    this.streamer?.attach(handle.agent.session, sent.messageId, msg.messageId, typingId)
-    handle.agent.followup(feishuUserMessage(content))
+      // 6. Stream into the card and hand the message to the driver. The prompt
+      //    is assembled only now (after the route is durable and tools are
+      //    mounted): images may be prefetched, files stay lazy behind the
+      //    manifest, and the (first turn only) bounded topic history plus the
+      //    quoted-message excerpt are attached as text blocks. `routes.put` and
+      //    `followup` stay synchronous with respect to other turns because
+      //    later messages wait on the delivery gate.
+      this.streamer?.attach(handle.agent.session, sent.messageId, msg.messageId, typingId)
+      handle.agent.followup(await this.deliverTurnMessage(msg, record, content, {
+        firstTurn: true,
+        excludeMessageIds: [msg.messageId, sent.messageId],
+      }))
+    } finally {
+      closeDeliveryGate()
+    }
     return record
   }
   private async continueSession(msg: NormalizedMessage, record: RouteRecord, content: string): Promise<void> {
@@ -534,14 +1108,9 @@ export class InboundRouter {
       delete current.worktreeBranch
       if (placement.worktreeBranch !== undefined) current = { ...current, worktreeBranch: placement.worktreeBranch }
     }
-    // Files staged before this conversation's topic existed follow its next
-    // turn (for example a file sent in the chat before the first prompt).
-    await adoptStagedAttachments(
-      stagingPathFor(this.config.baseDir, msg.chatType, msg.chatId, msg.senderId),
-      placement.sessionDir,
-    ).catch((error: unknown) => {
-      this.ctx.logger?.warn?.('dsh-channels: adopting staged attachments failed: %s', String(error))
-    })
+    // Files staged before this conversation's topic existed by a pre-v2
+    // deployment follow its next turn (one-time legacy adoption, D12).
+    await this.adoptLegacyStagedAttachments(msg, placement.sessionDir, warn)
 
     const sent = await this.delivery.replyFirstCard(msg, initialStreamingCard(current.sessionId))
     const typingId = await typingPromise
@@ -564,6 +1133,8 @@ export class InboundRouter {
       lastActivityAt: Date.now(),
     })
     this.streamer?.attach(live.agent.session, sent.messageId, msg.messageId, typingId)
-    live.agent.followup(feishuUserMessage(content))
+    live.agent.followup(await this.deliverTurnMessage(msg, current, content, {
+      excludeMessageIds: [msg.messageId, sent.messageId],
+    }))
   }
 }