@modesto_ma/dsh-channels 0.2.0 → 0.4.0

package/src/config.ts

@@ -34,6 +34,54 @@ export const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60 * 1000
 /** Default structured-question window: 5 minutes per `ask_user_question` call. */
 export const DEFAULT_QUESTION_TIMEOUT_MS = 5 * 60 * 1000
 
+/** Backends for inbound attachment storage, selected by `attachmentStore`. */
+export const ATTACHMENT_STORE_MODES = ['native', 'archive'] as const
+export type AttachmentStoreMode = (typeof ATTACHMENT_STORE_MODES)[number]
+
+/** Default retention of silently registered attachment metadata: 7 days. */
+export const DEFAULT_PENDING_ATTACHMENT_TTL_MS = 7 * 24 * 60 * 60 * 1000
+
+/** Default per-`(chat, thread, sender)` cap of pending attachment rows. */
+export const DEFAULT_PENDING_ATTACHMENT_LIMIT = 10
+
+/** Default per-call attachment count of `feishu_attachment_fetch`. */
+export const DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES = 10
+
+/** Default per-call total download budget of `feishu_attachment_fetch` (100 MiB). */
+export const DEFAULT_ATTACHMENT_FETCH_MAX_BYTES = 100 * 1024 * 1024
+
+/** Default whole-call timeout of `feishu_attachment_fetch` (120 s). */
+export const DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS = 120_000
+
+/** Default per-image byte cap for trigger-message prefetch (20 MiB). */
+export const DEFAULT_PREFETCH_IMAGE_MAX_BYTES = 20 * 1024 * 1024
+
+/** Default total byte budget for one trigger-message image prefetch (50 MiB). */
+export const DEFAULT_PREFETCH_TOTAL_MAX_BYTES = 50 * 1024 * 1024
+
+/** Default short timeout for one trigger-message image prefetch (10 s). */
+export const DEFAULT_PREFETCH_TIMEOUT_MS = 10_000
+
+/**
+ * Default number of recent topic messages attached to a new Session's first
+ * turn (0 disables the history bootstrap). Mirrors
+ * `HISTORY_BOOTSTRAP_DEFAULT` in `feishu/message-read.ts`.
+ */
+export const DEFAULT_HISTORY_BOOTSTRAP_LIMIT = 10
+
+/** Hard cap of the first-turn history bootstrap. */
+export const MAX_HISTORY_BOOTSTRAP_LIMIT = 20
+
+/** Default whole-call timeout of `feishu_topic_messages` (20 s). */
+export const DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS = 20_000
+
+/**
+ * Default budget of one passive prompt-enrichment message read (quoted excerpt
+ * / first-turn topic history). Kept short: the turn must not wait long for an
+ * optional context block.
+ */
+export const DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS = 3_000
+
 /** A credential reference: `FEISHU_APP_ID`-style name resolved through ctx.credentials. */
 const credentialRefSchema = z.string().regex(
   CREDENTIAL_REF_PATTERN,
@@ -103,6 +151,23 @@ export const configSchema = z.object({
    * `strict` fails the reply instead.
    */
   threadFallback: z.enum(['degrade', 'strict']).default('degrade'),
+  /**
+   * Per-topic working-directory isolation inside one user workspace.
+   *
+   * - `auto` (default): use a Git worktree per topic when the user workspace
+   *   is a Git repository (the workspace directory contains `.git`), otherwise
+   *   a plain subdirectory.
+   * - `subdir`: always a plain subdirectory (no Git requirement, no duplicated
+   *   checkouts).
+   * - `worktree`: always try a Git worktree; when the workspace is not a Git
+   *   repository, the `worktrees` service is unavailable, or creation is
+   *   denied, log a warning and fall back to a subdirectory.
+   *
+   * The workspace itself stays the Session header cwd either way, so Sessions
+   * remain grouped under the user's project; only the effective working
+   * directory changes. See `docs/workspace-isolation-design.md`.
+   */
+  topicIsolation: z.enum(['auto', 'subdir', 'worktree']).default('auto'),
   /**
    * Route-table GC threshold. Route records (and stale in-flight repair
    * snapshots) whose last activity is older than this many milliseconds are
@@ -121,25 +186,168 @@ export const configSchema = z.object({
    */
   approvalTimeoutMs: z.number().int().min(10_000).max(3_600_000).default(DEFAULT_APPROVAL_TIMEOUT_MS),
   /**
-   * Accept inbound Feishu images, files, and merged-forward chat records and
-   * save them below `<workspace>/attachments/`. Nothing is forwarded to the
-   * model automatically: the Agent reads whichever attachment the
-   * conversation needs with its ordinary filesystem tools. Disabled keeps
-   * attachment messages inert (no save, no turn).
+   * Accept inbound Feishu images, files, and merged-forward chat records.
+   *
+   * With the native backend (default) images of the triggering message are
+   * prefetched into the DSH native attachment library and files stay lazy
+   * behind a prompt manifest; with the archive backend the resources are saved
+   * below `<workspace>/attachments/` before the turn, exactly like the legacy
+   * pipeline. Disabled keeps attachment messages inert (no save, no turn, no
+   * pending metadata registration).
    */
   acceptAttachments: z.boolean().default(true),
   /**
-   * Delete the workspace directories of stale conversations. `off` (default)
-   * never deletes; `7d`/`30d`/`90d`/`180d` remove plugin-created workspaces
-   * whose last activity is older than the threshold. The managed Web panel
-   * exposes this as a select, previews the candidates, and can run one
-   * cleanup manually. DSH Session logs are never deleted.
+   * Backend for inbound Feishu images and files.
+   *
+   * - `native` (default): store into the DSH native attachment library
+   *   (`ctx.attachments`) as durable `ImageBlock`/`FileBlock` references; if
+   *   the host does not mount that service, the storage layer falls back to
+   *   `archive` for that deployment.
+   * - `archive`: legacy behavior — write the resources into the topic
+   *   workspace `attachments/` directory through the existing intake.
+   *
+   * Admission consumes this switch through the backend-selecting inbound
+   * store: an explicit `archive` always uses the legacy download path, and a
+   * `native` deployment without the mounted host service degrades to the same
+   * legacy path (see `effectiveAttachmentMode`).
+   */
+  attachmentStore: z.enum(ATTACHMENT_STORE_MODES).default('native'),
+  /**
+   * Prefetch images attached to the triggering message into the first model
+   * turn (native attachment backend only). The session, topic, and streaming
+   * card are already visible before the prefetch starts; the turn only waits
+   * for the (short, bounded) image download, never for file bytes. Failed,
+   * oversized, or timed-out images degrade to a manifest row that the model
+   * can fetch with `feishu_attachment_fetch`. Set `false` to keep every
+   * attachment lazy (images then need the tool as well).
+   */
+  prefetchImages: z.boolean().default(true),
+  /**
+   * Largest single image the trigger-message prefetch buffers in memory before
+   * refusing it (default 20 MiB). A refused image stays in the manifest and
+   * is fetched on demand.
+   */
+  prefetchImageMaxBytes: z.number().int().min(1).max(200 * 1024 * 1024)
+    .default(DEFAULT_PREFETCH_IMAGE_MAX_BYTES),
+  /**
+   * Total byte budget of one trigger-message image prefetch (default 50 MiB).
+   * Once exhausted, the remaining images degrade to the manifest.
+   */
+  prefetchTotalMaxBytes: z.number().int().min(1).max(1024 * 1024 * 1024)
+    .default(DEFAULT_PREFETCH_TOTAL_MAX_BYTES),
+  /**
+   * Short whole-prefetch timeout (default 10 s). On expiry the already-loaded
+   * images stay in the prompt and the rest degrade to the manifest, so a slow
+   * image download never blocks the turn for long.
+   */
+  prefetchTimeoutMs: z.number().int().min(100).max(120_000).default(DEFAULT_PREFETCH_TIMEOUT_MS),
+  /**
+   * Number of recent messages of the current topic automatically attached to
+   * the FIRST turn of a new Session (decision D1: the model should see the
+   * discussion before @ without asking). The `<feishu_history>` block is
+   * bounded and truncated with an explicit marker and each line carries the
+   * message_id needed to fetch a named attachment; older messages remain
+   * reachable through the `feishu_topic_messages` tool. `0` disables the
+   * bootstrap entirely. Reads use a short (~3 s) prompt-enrichment budget and a
+   * failure (missing scope, p2p history unavailable, channel down) degrades
+   * silently: the turn still runs.
+   */
+  historyBootstrapLimit: z.number().int().min(0).max(MAX_HISTORY_BOOTSTRAP_LIMIT)
+    .default(DEFAULT_HISTORY_BOOTSTRAP_LIMIT),
+  /**
+   * Whole-read budget (milliseconds) of the passive prompt enrichment: the
+   * quoted-message excerpt and the first-turn topic history. Deliberately short
+   * (default 3 s) and independent from `feishuTools.topicMessagesTimeoutMs`:
+   * on expiry the block is omitted and the turn runs. Model-initiated reads
+   * through `feishu_topic_messages` use the tool timeout instead.
+   */
+  promptContextTimeoutMs: z.number().int().min(100).max(10_000)
+    .default(DEFAULT_PROMPT_CONTEXT_TIMEOUT_MS),
+  /**
+   * Retention of silently registered attachment metadata (the
+   * `pending_attachments` table). A message that does not trigger a model turn
+   * (attachment-only p2p message, un-mentioned group message, attachment-only
+   * message inside a bound topic) is recorded as metadata only; a later
+   * triggered message in the same `(chat, thread, sender)` scope may list and
+   * fetch it. Rows older than this window are removed by the periodic record
+   * GC. `0` disables age pruning (the per-scope cap still bounds each scope).
+   * Default 7 days.
+   */
+  pendingAttachmentTtlMs: z.number().int().min(0).default(DEFAULT_PENDING_ATTACHMENT_TTL_MS),
+  /**
+   * Maximum silently registered attachment rows kept per `(chat, thread,
+   * sender)` scope. Registering beyond the cap evicts the oldest row of that
+   * scope; the prompt manifest only ever shows the most recent 5 unconsumed
+   * rows. Default 10.
+   */
+  pendingAttachmentLimit: z.number().int().min(1).max(100).default(DEFAULT_PENDING_ATTACHMENT_LIMIT),
+  /**
+   * Model-facing Feishu tools.
+   *
+   * - `attachmentFetch` (default on): register `feishu_attachment_fetch` in
+   *   channel sessions so the model can fetch images/files of a known message
+   *   on demand. Registration is skipped (with one warning) on deployments
+   *   without the host `tools` / `attachments` services. Turning it off also
+   *   keeps inbound attachments on the archive backend: lazy native files
+   *   would be unreachable without the tool, so admission downloads them to
+   *   the workspace instead (see `effectiveAttachmentMode`).
+   * - `attachmentFetchMaxResources`: maximum attachments one tool call may
+   *   fetch (1–50). A message with more attachments is refused with a readable
+   *   reason so the model can retry per `file_key`.
+   * - `attachmentFetchMaxBytes`: total download budget of one tool call
+   *   (default 100 MiB). Files stream to the native attachment library, so the
+   *   limit is enforced while streaming rather than buffered first.
+   * - `attachmentFetchTimeoutMs`: whole-call timeout (default 120 s). On expiry
+   *   the in-flight download is cancelled and reported per attachment.
+   * - `topicMessages` (default on): register `feishu_topic_messages` in
+   *   channel sessions so the model can read the quoted message / earlier
+   *   topic messages on demand and authorize their attachments for fetch.
+   *   Reads require the Feishu message-read scopes; a missing scope degrades to
+   *   a readable tool failure and never fails the turn. This switch only
+   *   controls the model-facing tool: the passive `<feishu_quote>` /
+   *   `<feishu_history>` prompt excerpts stay enabled (they are bounded and
+   *   degrade silently) and are configured by `historyBootstrapLimit`. On the
+   *   archive backend the tool is still mounted for history text, while its
+   *   description states that `feishu_attachment_fetch` is unavailable.
+   * - `topicMessagesTimeoutMs`: whole-call timeout of one model-initiated
+   *   topic read (default 20 s). Passive prompt excerpts use a separate short
+   *   (~3 s) budget and never wait this long.
+   *
+   * The Web panel/metrics ship with `panel_docs_release`.
+   */
+  feishuTools: z.object({
+    attachmentFetch: z.boolean().default(true),
+    attachmentFetchMaxResources: z.number().int().min(1).max(50)
+      .default(DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES),
+    attachmentFetchMaxBytes: z.number().int().min(1).max(1024 * 1024 * 1024)
+      .default(DEFAULT_ATTACHMENT_FETCH_MAX_BYTES),
+    attachmentFetchTimeoutMs: z.number().int().min(1_000).max(600_000)
+      .default(DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS),
+    topicMessages: z.boolean().default(true),
+    topicMessagesTimeoutMs: z.number().int().min(1_000).max(120_000)
+      .default(DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS),
+  }).default({
+    attachmentFetch: true,
+    attachmentFetchMaxResources: DEFAULT_ATTACHMENT_FETCH_MAX_RESOURCES,
+    attachmentFetchMaxBytes: DEFAULT_ATTACHMENT_FETCH_MAX_BYTES,
+    attachmentFetchTimeoutMs: DEFAULT_ATTACHMENT_FETCH_TIMEOUT_MS,
+    topicMessages: true,
+    topicMessagesTimeoutMs: DEFAULT_TOPIC_MESSAGES_TIMEOUT_MS,
+  }),
+  /**
+   * Delete the topic directories of stale conversations, plus legacy
+   * one-workspace-per-topic directories written by older plugin versions.
+   * `off` (default) never deletes; `7d`/`30d`/`90d`/`180d` remove those
+   * directories when their last activity is older than the threshold. User
+   * workspaces themselves are never deleted. The managed Web panel exposes
+   * this as a select, previews the candidates, and can run one cleanup
+   * manually. DSH Session logs are never deleted.
    */
   workspaceRetention: z.enum(WORKSPACE_RETENTION_VALUES).default('off'),
   /**
-   * Run the workspace-retention cleanup at startup and once per day. Off by
-   * default: deletion is irreversible, so it stays an explicit opt-in even
-   * when a retention threshold is configured.
+   * Run the retention cleanup at startup and once per day. Off by default:
+   * deletion is irreversible, so it stays an explicit opt-in even when a
+   * retention threshold is configured.
    */
   workspaceRetentionAuto: z.boolean().default(false),
   /**

package/src/domain.ts

@@ -10,8 +10,16 @@
 
 import { z } from 'zod'
 
-/** Route key kinds. `thread` = real Feishu topic; `chat` = degraded chat-scoped fallback. */
-export const ROUTE_RECORD_VERSION = 1
+/**
+ * Route key kinds. `thread` = real Feishu topic; `chat` = degraded chat-scoped
+ * fallback.
+ *
+ * Version 2 adds the optional `sessionDir` / `worktreeBranch` fields (the
+ * Session's effective working directory). Version-1 records stay readable: an
+ * absent `sessionDir` means the workspace path itself is the working directory
+ * (the pre-v2 model).
+ */
+export const ROUTE_RECORD_VERSION = 2
 
 export const sessionHistoryEntrySchema = z.object({
   /** One Session that has been bound to this route. */
@@ -35,8 +43,16 @@ export const routeRecordSchema = z.object({
   chatType: z.enum(['p2p', 'group']),
   /** Workspace owner (sender open_id). */
   senderOpenId: z.string().min(1),
-  /** Workspace directory for this (chat, user) pair. */
+  /** Workspace root owning this route: the Session header cwd / sandbox root. */
   workspacePath: z.string().min(1),
+  /**
+   * Effective working directory of the bound Session (the per-topic directory
+   * or Git worktree checkout). Absent on records written before per-topic
+   * directories existed: `workspacePath` is then the working directory too.
+   */
+  sessionDir: z.string().min(1).optional(),
+  /** Git branch owning `sessionDir` when it is a worktree checkout. */
+  worktreeBranch: z.string().min(1).optional(),
   /** Message id of the latest streaming card (updated per turn). */
   cardMessageId: z.string().min(1),
   /** Epoch ms when the record was created. */
@@ -71,6 +87,12 @@ export const expiredRouteRecordSchema = z.object({
   /** Workspace the retired route belonged to; absent in tombstones written by
    *  older plugin versions, so the field must stay optional. */
   workspacePath: z.string().min(1).optional(),
+  /** Effective working directory the retired route's Session used; absent in
+   *  legacy tombstones (retention cleanup then treats `workspacePath` as the
+   *  directory, matching pre-v2 routes). */
+  sessionDir: z.string().min(1).optional(),
+  /** Git branch of that directory when it was a worktree checkout. */
+  worktreeBranch: z.string().min(1).optional(),
   /** Epoch ms of the last activity through the route before retirement.
    *  Optional for the same legacy-compatibility reason; consumers fall back to
    *  `expiredAt` when it is absent. */
@@ -116,6 +138,15 @@ export function appendSessionHistory(
   })
 }
 
+/**
+ * Effective working directory of one route's Session. Records written before
+ * per-topic directories have no `sessionDir`; their workspace path is the
+ * directory the Session really works in.
+ */
+export function sessionDirOf(record: Pick<RouteRecord, 'workspacePath' | 'sessionDir'>): string {
+  return record.sessionDir ?? record.workspacePath
+}
+
 /**
  * In-flight turn snapshot: everything needed to repair a streaming card that a
  * restart left mid-flight (stuck panel, leftover Typing reaction, never-patched
@@ -251,6 +282,89 @@ export const processedRecordSchema = z.object({
 
 export type ProcessedRecord = z.infer<typeof processedRecordSchema>
 
+/**
+ * Silently registered inbound attachment metadata ("pending attachments").
+ *
+ * A message that does not trigger a model turn — a p2p attachment-only
+ * message, an un-mentioned group message, an attachment-only message inside an
+ * already-bound topic — is recorded here without downloading bytes, replying,
+ * or reacting. A later triggered message in the same `(chat, thread?, sender)`
+ * scope can list these entries in its prompt manifest and fetch them on demand
+ * through the attachment tool. The table stores metadata only (Feishu resource
+ * keys), never bytes.
+ *
+ * Added without a storage-domain version bump: the host's JSON backend loads a
+ * declared table that is missing from the stored document as empty and keeps
+ * the stored `unit.version` (1), so existing deployments gain the table with no
+ * migration. Downgrading to a plugin build without this table would drop it on
+ * the next write — acceptable because plugin builds are replaced in place.
+ */
+export const PENDING_ATTACHMENT_KINDS = ['image', 'file', 'post', 'merge_forward'] as const
+
+/** Kind of message that carried the attachment payload. */
+export type PendingAttachmentKind = (typeof PENDING_ATTACHMENT_KINDS)[number]
+
+/**
+ * One attachment resource inside a pending record. Feishu downloads resources
+ * by `(message id, file key)`; `containerMessageId` is set when only a
+ * top-level container id works (merged-forward children).
+ */
+export const pendingAttachmentResourceSchema = z.object({
+  /** Resource kind delivered by Feishu. */
+  type: z.enum(['image', 'file']),
+  /** Feishu resource key (`img_v3_...` / `file_v3_...`). */
+  fileKey: z.string().min(1),
+  /** Original file name, when Feishu reports one. */
+  fileName: z.string().min(1).optional(),
+  /** Feishu folder entries cannot be downloaded; recorded so the fetch tool can
+   *  answer with a structured "folder unsupported" instead of a raw API error. */
+  folder: z.boolean().optional(),
+  /** Top-level container message id to download through, when different from
+   *  this record's own `messageId` (merged-forward child resources). */
+  containerMessageId: z.string().min(1).optional(),
+})
+
+export type PendingAttachmentResource = z.infer<typeof pendingAttachmentResourceSchema>
+
+/**
+ * One silently registered attachment message. Keyed by its Feishu message id so
+ * a redelivered event can never register twice. `scopeKey` is the
+ * `(chat, thread?, sender)` isolation unit; `consumed` marks metadata the
+ * agent already fetched, which then drops out of the prompt manifest (the
+ * record stays as an authorization fact until its TTL).
+ */
+export const pendingAttachmentRecordSchema = z.object({
+  /** Key the record is stored under (= `messageId`). */
+  key: z.string().min(1),
+  /** `(chat, thread?, sender)` isolation key; see `pendingAttachmentScopeKey`. */
+  scopeKey: z.string().min(1),
+  /** Feishu message id of the attachment message (the container id for
+   *  merged-forward records). */
+  messageId: z.string().min(1),
+  /** Feishu chat the message arrived in. */
+  chatId: z.string().min(1),
+  /** `p2p` or `group`. */
+  chatType: z.enum(['p2p', 'group']),
+  /** Feishu topic the message belongs to, when it has one. */
+  threadId: z.string().min(1).optional(),
+  /** Normalized sender id (open_id) that the scope is bound to. */
+  senderOpenId: z.string().min(1),
+  /** Epoch ms when the metadata was registered (clock seam for tests). */
+  receivedAt: z.number().int().nonnegative(),
+  /** Kind of message that carried the payload. */
+  kind: z.enum(PENDING_ATTACHMENT_KINDS),
+  /** Attachment payloads; empty for merged-forward containers (children are
+   *  listed through the container's own message id on fetch). */
+  resources: z.array(pendingAttachmentResourceSchema),
+  /** Remaining caption text after attachment placeholders, truncated. */
+  textExcerpt: z.string().min(1).optional(),
+  /** Set once the agent fetched the attachment; consumed rows leave the
+   *  manifest but stay queryable by message id until the TTL sweep. */
+  consumed: z.boolean().optional(),
+})
+
+export type PendingAttachmentRecord = z.infer<typeof pendingAttachmentRecordSchema>
+
 export interface FeishuDomainSpecShape {
   name: 'channels_routes'
   version: 1
@@ -287,6 +401,10 @@ export interface FeishuDomainSpecShape {
       valueSchema: typeof accessRequestRecordSchema
       __key?: string
     }
+    pending_attachments: {
+      valueSchema: typeof pendingAttachmentRecordSchema
+      __key?: string
+    }
   }
 }
 
@@ -321,6 +439,7 @@ export const feishuDomain: FeishuDomainSpecShape = {
     access_groups: { valueSchema: accessGroupRecordSchema },
     access_users: { valueSchema: accessUserRecordSchema },
     access_requests: { valueSchema: accessRequestRecordSchema },
+    pending_attachments: { valueSchema: pendingAttachmentRecordSchema },
   },
 }
 
@@ -387,6 +506,19 @@ export interface AccessRequestsTable {
   entries(): IterableIterator<[string, AccessRequestRecord]>
 }
 
+/**
+ * Normalized table handle for silently registered attachment metadata
+ * (key = Feishu message id).
+ */
+export interface PendingAttachmentsTable {
+  get(key: string): PendingAttachmentRecord | undefined
+  put(key: string, value: PendingAttachmentRecord): Promise<unknown> | void
+  /** Atomic read-modify-write on the host's write chain (`missing-key` when gone). */
+  update(key: string, fn: (current: PendingAttachmentRecord) => PendingAttachmentRecord): Promise<unknown>
+  delete(key: string): Promise<unknown> | void
+  entries(): IterableIterator<[string, PendingAttachmentRecord]>
+}
+
 /** Normalized domain handle. */
 export interface FeishuDomainHandle {
   routes: RoutesTable
@@ -396,6 +528,12 @@ export interface FeishuDomainHandle {
   accessGroups: AccessGroupsTable
   accessUsers: AccessUsersTable
   accessRequests: AccessRequestsTable
+  /**
+   * Pending attachment metadata. Optional on purpose: an embedded host whose
+   * storage domain refuses the added table leaves this undefined and the
+   * registry degrades to a process-memory TTL store (records lost on restart).
+   */
+  pendingAttachments?: PendingAttachmentsTable
   getGlobal(): FeishuDomainGlobal
   setGlobal(value: FeishuDomainGlobal): Promise<unknown> | void
   close(): Promise<void>

package/src/feishu/agent-context.ts

@@ -1,18 +1,30 @@
 /**
  * Agent-scoped system-prompt guidance for Feishu attachments.
  *
- * The channel archives inbound images/files/forwarded records below
- * `<workspace>/attachments/` without any model turn. This section is what
- * makes that convention discoverable: it tells the Agent where attachments
- * live, how to read them, and that reading is opt-in per user request.
+ * Which guidance is mounted follows the *effective* attachment backend
+ * (`attachmentStore`, decisions D6/D2):
+ * - `native` (the default): inbound images/files live in the DSH native
+ *   attachment library. Trigger-message images are prefetched and already
+ *   visible; files stay unloaded and the prompt carries a stable
+ *   `<feishu_context>` manifest (see `manifest.ts`) that the Agent uses with the
+ *   `feishu_attachment_fetch` tool on demand.
+ * - `archive` (legacy / fallback): inbound images/files are archived below
+ *   `<session working directory>/attachments/` and read with filesystem tools.
+ *   Kept for explicit `attachmentStore: 'archive'` deployments and for native
+ *   deployments whose host does not mount `ctx.attachments`.
  *
- * Registered inside the Agent scope (through `inject(['systemPrompt'])`), so
- * it is disposed with the Agent and does not leak into other compositions.
+ * Registered inside the Agent scope (through `inject(['systemPrompt'])`), so it
+ * is disposed with the Agent and does not leak into other compositions. The
+ * archive flavor is mounted only after the Session's effective working
+ * directory is known (see `SessionManager.mountGuidance`), so its absolute path
+ * is accurate even when that directory is a Git worktree created after Agent
+ * creation.
  *
  * @module dsh-channels/feishu/agent-context
  */
 
 import type { AgentContext } from '../host/agent.ts'
+import { FEISHU_CONTEXT_TAG } from './manifest.ts'
 
 /** Stable prompt-section name; one registration per Agent scope. */
 export const FEISHU_ATTACHMENTS_SECTION = 'dsh-channels:feishu-attachments'
@@ -24,24 +36,61 @@ export const FEISHU_ATTACHMENTS_SECTION = 'dsh-channels:feishu-attachments'
  */
 const FEISHU_ATTACHMENTS_ORDER = 950
 
-/** Model-facing text. Kept stable so unchanged sessions keep their KV cache. */
-export const FEISHU_ATTACHMENTS_GUIDANCE = `## Feishu attachments
-Every Feishu conversation (topic) has its own workspace and its own attachments directory. Images, files, and forwarded chat records sent through Feishu are archived verbatim in this conversation's \`attachments/\` directory. Each file name starts with its receipt time (\`YYYYMMDD-HHmmss-\`), so newer attachments sort later and \`ls -lt <dir>\` lists the newest first.
+/** Attachment backend whose guidance to mount; mirrors `attachmentStore`. */
+export type AttachmentGuidanceMode = 'native' | 'archive'
+
+/**
+ * Native-library guidance (new default). Model-facing text kept stable so
+ * unchanged sessions keep their KV cache.
+ */
+export const FEISHU_ATTACHMENTS_NATIVE_GUIDANCE = `## Feishu attachments
+Inbound Feishu images and files are stored in the DSH native attachment library and are tied to this conversation's session; they are not copied into the working directory automatically.
+
+- Images that arrived in the message which triggered this turn are already visible to you as image blocks. Never load them again.
+- Files are not loaded by default: the conversation only carries their metadata, not their bytes.
+- The user message may carry a manifest in a \`<${FEISHU_CONTEXT_TAG}>\` block. It lists attachments that are not loaded yet, each with its message_id, type, and, when known, file_key and file name. A line with type=merge_forward is a forwarded-chat container: use its message_id without file_key. An image that could not be prefetched is listed the same way as a file.
+- The user message may also carry \`<feishu_quote>\` (the message this one replies to) and, on a new session's first turn, \`<feishu_history>\` (bounded recent topic messages). Attachments named there are not loaded; fetch one with \`feishu_attachment_fetch\` using the message_id shown on its line.
+- Use the \`feishu_topic_messages\` tool to read a quoted message in full, or to page through earlier messages of this topic (newest first, limit/cursor). Messages and attachments it returns are authorized for \`feishu_attachment_fetch\`.
+
+When the user's request genuinely needs an attachment, fetch it with the \`feishu_attachment_fetch\` tool: pass message_id, and add file_key to fetch one specific file of that message. Fetch nothing when the request can be answered without the bytes, and do not proactively enumerate or fetch attachments the user did not mention.
+
+Never read, copy, or print Feishu app credentials (for example files under the DSH home directory) and never call the Feishu OpenAPI directly with them; use only the Feishu tools provided in this conversation.
+
+A fetched file is an immutable, read-only copy in the native attachment library. Before changing it, copy it into the working directory and modify the copy. Only access attachments of this conversation; never read or mention another conversation's attachments.`
+
+/**
+ * Legacy archive guidance: attachments are archived under the conversation
+ * workspace's `attachments/` directory and read through filesystem tools.
+ * Model-facing text kept stable so unchanged sessions keep their KV cache.
+ */
+export const FEISHU_ATTACHMENTS_ARCHIVE_GUIDANCE = `## Feishu attachments
+Every Feishu conversation (topic) has its own working directory inside its user's workspace, and every working directory has its own \`attachments/\` directory. Images, files, and forwarded chat records sent through Feishu are archived verbatim in this conversation's \`attachments/\` directory. Each file name starts with its receipt time (\`YYYYMMDD-HHmmss-\`), so newer attachments sort later and \`ls -lt <dir>\` lists the newest first.
 
 Attachments are never inserted into the conversation automatically. Read them only when the user's request needs them, and do not read attachments the user did not mention:
 - images: use \`read_image\` with the file path;
 - text and code: use \`read\` when the session mounts that tool, otherwise \`bash\` (for example \`sed -n '1,200p' <file>\`);
 - other formats (PDF, Office, archives, ...): inspect or convert them with \`bash\`.
-If the user refers to "the file/image I just sent" without a name, list this conversation's attachments directory and pick the most recent matching attachment. Other Feishu conversations have separate workspaces: never read outside this workspace, and never mention files from another conversation.`
+If the user refers to "the file/image I just sent" without a name, list this conversation's attachments directory and pick the most recent matching attachment. Other Feishu conversations work in separate directories: never read outside this conversation's working directory, and never mention files from another conversation.
+
+Never read, copy, or print Feishu app credentials (for example files under the DSH home directory) and never call the Feishu OpenAPI directly with them; use only the Feishu tools provided in this conversation.
+
+A message may also carry \`<feishu_quote>\` / \`<feishu_history>\` text excerpts. Attachments named there arrive lazily and are not in this directory in this deployment; describe what the excerpt says instead of claiming to have read the file.`
 
 /**
- * Full guidance for one Session. The absolute per-session directory is
- * appended when known so the convention still resolves after the Agent changes
+ * Full guidance text for one Session.
+ *
+ * The native flavor ignores `attachmentsDir` (there is no per-conversation
+ * directory to name). The archive flavor appends the absolute per-session
+ * directory when known so the convention still resolves after the Agent changes
  * its working directory with the `working_directory` tool.
  */
-export function attachmentsGuidance(attachmentsDir?: string): string {
-  if (attachmentsDir === undefined || attachmentsDir === '') return FEISHU_ATTACHMENTS_GUIDANCE
-  return `${FEISHU_ATTACHMENTS_GUIDANCE}\n\nThis conversation's attachment directory is \`${attachmentsDir.replace(/`/gu, "'")}\` (absolute).`
+export function attachmentsGuidance(
+  mode: AttachmentGuidanceMode = 'native',
+  attachmentsDir?: string,
+): string {
+  if (mode !== 'archive') return FEISHU_ATTACHMENTS_NATIVE_GUIDANCE
+  if (attachmentsDir === undefined || attachmentsDir === '') return FEISHU_ATTACHMENTS_ARCHIVE_GUIDANCE
+  return `${FEISHU_ATTACHMENTS_ARCHIVE_GUIDANCE}\n\nThis conversation's attachment directory is \`${attachmentsDir.replace(/`/gu, "'")}\` (absolute).`
 }
 
 /**
@@ -50,13 +99,14 @@ export function attachmentsGuidance(attachmentsDir?: string): string {
  */
 export async function mountChannelGuidance(
   agentCtx: AgentContext,
+  mode: AttachmentGuidanceMode = 'native',
   attachmentsDir?: string,
 ): Promise<void> {
   await agentCtx.inject(['systemPrompt'], (ctx) => {
     ctx.systemPrompt?.section({
       name: FEISHU_ATTACHMENTS_SECTION,
       order: FEISHU_ATTACHMENTS_ORDER,
-      text: attachmentsGuidance(attachmentsDir),
+      text: attachmentsGuidance(mode, attachmentsDir),
     })
   })
 }