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

package/src/domain.ts

@@ -41,8 +41,8 @@ export const routeRecordSchema = z.object({
   chatId: z.string().min(1),
   /** `p2p` or `group`. */
   chatType: z.enum(['p2p', 'group']),
-  /** Workspace owner (sender open_id). */
-  senderOpenId: z.string().min(1),
+  /** Workspace owner (sender user_id). */
+  senderUserId: z.string().min(1),
   /** Workspace root owning this route: the Session header cwd / sandbox root. */
   workspacePath: z.string().min(1),
   /**
@@ -81,15 +81,14 @@ export const expiredRouteRecordSchema = z.object({
   /** Original chat type, retained for diagnostics and future policy. */
   chatType: z.enum(['p2p', 'group']),
   /** Original route owner; never used to grant access after expiry. */
-  senderOpenId: z.string().min(1),
+  senderUserId: z.string().min(1),
   /** Epoch ms when the route was retired. */
   expiredAt: z.number().int().nonnegative(),
   /** 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). */
+   *  legacy tombstones, where `workspacePath` was the directory (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(),
@@ -202,7 +201,7 @@ export const accessGroupRecordSchema = z.object({
   name: z.string().optional(),
   /** Which authorization entry produced this grant. */
   source: z.enum(['command', 'card', 'panel']),
-  /** Administrator open_id that authorized it. */
+  /** Administrator user_id that authorized it. */
   addedBy: z.string().min(1),
   /** Epoch ms when it was authorized. */
   addedAt: z.number().int().nonnegative(),
@@ -211,18 +210,18 @@ export const accessGroupRecordSchema = z.object({
 export type AccessGroupRecord = z.infer<typeof accessGroupRecordSchema>
 
 /**
- * One authorized user (`open_id`), global across every authorized group.
+ * One authorized user (`user_id`), global across every authorized group.
  * Private chats are administrator-only, so this grant only affects group
  * conversations.
  */
 export const accessUserRecordSchema = z.object({
-  /** Feishu open id (`ou_...`) — also the table key. */
-  openId: z.string().min(1),
+  /** Feishu `user_id` — also the table key. */
+  userId: z.string().min(1),
   /** Display name captured when the user was authorized (optional). */
   name: z.string().optional(),
   /** Which authorization entry produced this grant. */
   source: z.enum(['command', 'card', 'panel']),
-  /** Administrator open_id that authorized it. */
+  /** Administrator user_id that authorized it. */
   addedBy: z.string().min(1),
   /** Epoch ms when it was authorized. */
   addedAt: z.number().int().nonnegative(),
@@ -241,14 +240,14 @@ export const accessRequestRecordSchema = z.object({
   token: z.string().min(1),
   /** What is being requested. */
   kind: z.enum(['group', 'user']),
-  /** `chat_id` for a group request; `open_id` for a user request. */
+  /** `chat_id` for a group request; `user_id` for a user request. */
   targetId: z.string().min(1),
   /** Chat the request originated from, when applicable. */
   chatId: z.string().optional(),
   /** Group name captured for the card (group requests, or the group the user was seen in). */
   groupName: z.string().optional(),
   /** User who triggered a user request. */
-  requesterOpenId: z.string().optional(),
+  requesterUserId: z.string().optional(),
   /** Display name of that user, when the event carried one. */
   requesterName: z.string().optional(),
   /** Lifecycle state; only `pending` requests accept a card action. */
@@ -283,7 +282,7 @@ export const processedRecordSchema = z.object({
 export type ProcessedRecord = z.infer<typeof processedRecordSchema>
 
 export interface FeishuDomainSpecShape {
-  name: 'channels_routes'
+  name: 'channels_routes_v2'
   version: 1
   global: {
     schema: z.ZodType<FeishuDomainGlobal>
@@ -338,7 +337,9 @@ export type FeishuDomainGlobal = z.infer<typeof feishuDomainGlobalSchema>
  * runtime import of `@deepseek-ai/dsh-storage-domain`.
  */
 export const feishuDomain: FeishuDomainSpecShape = {
-  name: 'channels_routes',
+  // v2 keys every user by `user_id`. The open_id-keyed `channels_routes` unit
+  // is neither read nor migrated; it stays on disk untouched.
+  name: 'channels_routes_v2',
   version: 1,
   global: {
     schema: feishuDomainGlobalSchema,
@@ -402,7 +403,7 @@ export interface AccessGroupsTable {
   entries(): IterableIterator<[string, AccessGroupRecord]>
 }
 
-/** Normalized table handle for authorized users (key = `open_id`). */
+/** Normalized table handle for authorized users (key = `user_id`). */
 export interface AccessUsersTable {
   get(key: string): AccessUserRecord | undefined
   put(key: string, value: AccessUserRecord): Promise<unknown> | void
@@ -451,9 +452,18 @@ export interface RawDomainHandle {
   close(): Promise<void>
 }
 
+/**
+ * Feishu tenant `user_id` (letters, digits, `_`, `-`). It doubles as a
+ * workspace path segment and as a DM target, where the SDK infers the
+ * receive id type from the prefix: `ou_`/`on_`/`oc_` would be sent as an
+ * open_id/union_id/chat_id, so those prefixes are rejected (a pasted open_id
+ * fails validation instead of matching nobody).
+ */
+export const FEISHU_USER_ID_PATTERN = /^(?!ou_|on_|oc_)[A-Za-z0-9_-]+$/u
+
 /** Build a chat-scoped fallback key for degraded (topic-less) routing. */
-export function chatRouteKey(chatType: 'p2p' | 'group', chatId: string, senderOpenId: string): string {
+export function chatRouteKey(chatType: 'p2p' | 'group', chatId: string, senderUserId: string): string {
   return chatType === 'p2p'
-    ? `chat:p2p:${chatId}:${senderOpenId}`
-    : `chat:group:${chatId}:${senderOpenId}`
+    ? `chat:p2p:${chatId}:${senderUserId}`
+    : `chat:group:${chatId}:${senderUserId}`
 }

package/src/feishu/agent-context.ts

@@ -1,22 +1,30 @@
 /**
  * Agent-scoped system-prompt guidance for Feishu attachments.
  *
- * The channel archives inbound images/files/forwarded records below
- * `<session working directory>/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.
- * It is mounted only after the Session's effective working directory is known
- * (see `SessionManager.mountGuidance`), so the absolute path is accurate even
- * when that directory is a Git worktree created after Agent creation.
+ * 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'
@@ -28,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
+/** 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 work in separate directories: never read outside this conversation's working directory, 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).`
 }
 
 /**
@@ -54,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),
     })
   })
 }