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

package/src/feishu-channel.ts

@@ -9,6 +9,9 @@
  */
 
 import { createLarkChannel, LoggerLevel } from '@larksuiteoapi/node-sdk'
+import { SCOPE_GRANTED_STATUS } from './feishu/scopes.ts'
+import type { ScopeGrant } from './feishu/scopes.ts'
+import type { RemoteSlashCommand, SlashCommandApi, SlashCommandEntry } from './feishu/slash-commands.ts'
 import type {
   BotAddedEvent,
   ChatInfo,
@@ -21,12 +24,18 @@ import type {
 export type { BotAddedEvent, ChatInfo, NormalizedMessage, SendResult } from '@larksuiteoapi/node-sdk'
 export type FeishuConnectionStatus = WSConnectionStatus
 
-/** Outbound payloads used by this plugin, including Buffer-backed file upload. */
+/** Outbound payloads used by this plugin, including Buffer-backed image and file uploads. */
 export type FeishuSendInput =
   | { card: object }
   | { text: string }
+  | { image: { source: Buffer } }
   | { file: { source: string | Buffer; fileName: string } }
 
+/** One outbound image or file uploaded from memory. */
+export type OutboundMedia =
+  | { readonly kind: 'image'; readonly data: Buffer }
+  | { readonly kind: 'file'; readonly data: Buffer; readonly fileName: string }
+
 /**
  * One normalized card action (button click) event, as delivered by the
  * official SDK's `card.action.trigger` handler (card JSON 2.0 callback
@@ -58,18 +67,45 @@ export interface FeishuChannel {
   getChatInfo(chatId: string): Promise<ChatInfo>
   /** Bot open_id, available after `connect()` resolves. */
   botOpenId(): string | undefined
+  /**
+   * The app owner's `user_id` (`application.v6.application.get`), used as the
+   * administrator when none is configured. Resolves `undefined` when the owner
+   * is not a tenant member; rejects with an {@link AppOwnerLookupError} when
+   * the API call fails (typically a missing app-info scope). Optional so stubs
+   * and older channels can omit it; absence means no owner fallback.
+   */
+  appOwnerUserId?(): Promise<string | undefined>
+  /**
+   * Scopes the app requested from the tenant and their grant state
+   * (`application.v6.scope.list`). Rejects with a {@link FeishuApiError} when
+   * the call fails. Optional so stubs can omit it; absence skips the check.
+   */
+  grantedScopes?(): Promise<readonly ScopeGrant[]>
+  /**
+   * The app's native slash-command panel endpoints
+   * (`application/v7/app_slash_commands`). Optional so stubs can omit it;
+   * absence skips the panel sync.
+   */
+  readonly slashCommands?: SlashCommandApi
   /** Current official-SDK WebSocket lifecycle snapshot, when initialized. */
   getConnectionStatus(): FeishuConnectionStatus | undefined
   /** Start the WebSocket long connection (resolves after the handshake). */
   connect(): Promise<void>
   /** Stop the connection. */
   disconnect(): Promise<void>
-  /** Send one message (text or card) with optional reply targeting. */
+  /** Send one message (text, card, image or file) with optional reply targeting. */
   send(
     chatId: string,
     input: FeishuSendInput,
     options?: { replyTo?: string; replyInThread?: boolean },
   ): Promise<SendResult>
+  /**
+   * Upload one image or file and send it as a reply to `replyTo`. Unlike
+   * {@link FeishuChannel.send}, a recalled or deleted reply target is NOT
+   * retried as a fresh chat message: the call rejects with a
+   * {@link FeishuApiError}, so topic output never lands on the main timeline.
+   */
+  replyMedia(replyTo: string, media: OutboundMedia, options: { replyInThread: boolean }): Promise<SendResult>
   /** Full-card replacement of a previously sent card message. */
   updateCard(messageId: string, card: object): Promise<void>
   /** Add an emoji reaction; resolves with the reaction id needed for removal. */
@@ -88,6 +124,26 @@ export interface FeishuChannel {
     fileKey: string,
     type: 'image' | 'file',
   ): Promise<ResourceChunkStream>
+  /** P0 probe surface: raw `im.v1.message.get` (quoted / merged-forward container). */
+  messageGet?(messageId: string): Promise<unknown>
+  /**
+   * Batch read surface: raw `im.v1.message.mget` (≤50 message ids). The SDK
+   * 1.76 client does not expose this endpoint as a typed method, so the
+   * adapter calls it through `Client.request`; every caller must tolerate the
+   * method being absent (older channels / stubs) and fall back to `message.get`.
+   */
+  messageMget?(messageIds: readonly string[]): Promise<unknown>
+  /** P0 probe surface: raw `im.v1.message.list` (thread / chat history). */
+  messageList?(params: RawMessageListParams): Promise<unknown>
+}
+
+/** Query for the raw `im.v1.message.list` endpoint. */
+export interface RawMessageListParams {
+  container_id_type: 'chat' | 'thread'
+  container_id: string
+  page_size?: number
+  page_token?: string
+  sort_type?: 'ByCreateTimeAsc' | 'ByCreateTimeDesc'
 }
 
 /** Ordered byte chunks of one inbound resource. */
@@ -161,6 +217,136 @@ export async function* downloadResourceInRanges(
   }
 }
 
+/** Owner type `2` = tenant member; `0`/`1` are Feishu itself or an ISV partner. */
+const APP_OWNER_TYPE_TENANT_MEMBER = 2
+
+/** Failed Feishu OpenAPI call, carrying the Feishu `code`/`msg` when present. */
+export class FeishuApiError extends Error {
+  /**
+   * @param detail Feishu `code=<n> <msg>` or the transport error text.
+   * @param code Feishu API error code, when the response carried one.
+   */
+  constructor(readonly detail: string, readonly code?: number) {
+    super(`feishu api call failed: ${detail}`)
+    this.name = 'FeishuApiError'
+  }
+}
+
+/** Failed app-owner lookup, carrying the Feishu `code`/`msg` when present. */
+export class AppOwnerLookupError extends FeishuApiError {
+  /**
+   * @param detail Feishu `code=<n> <msg>` or the transport error text.
+   * @param code Feishu API error code, when the response carried one.
+   */
+  constructor(detail: string, code?: number) {
+    super(detail, code)
+    this.message = `app owner lookup failed: ${detail}`
+    this.name = 'AppOwnerLookupError'
+  }
+}
+
+/** `detail`/`code` of a thrown SDK/Axios error, preferring the Feishu error body. */
+function thrownErrorFields(error: unknown): { detail: string; code?: number } {
+  const data = (error as { response?: { data?: { code?: unknown; msg?: unknown } } } | undefined)?.response?.data
+  const code = typeof data?.code === 'number' ? data.code : undefined
+  const msg = typeof data?.msg === 'string' ? data.msg : undefined
+  if (code === undefined && msg === undefined) return { detail: error instanceof Error ? error.message : String(error) }
+  return { detail: [code === undefined ? undefined : `code=${code}`, msg].filter(Boolean).join(' '), code }
+}
+
+/** Normalize a thrown SDK/Axios error into an {@link AppOwnerLookupError}. */
+/** Throw a {@link FeishuApiError} for a non-zero Feishu `code`. */
+function assertFeishuOk(response: { code?: number; msg?: string }): void {
+  if (response.code !== undefined && response.code !== 0) {
+    throw new FeishuApiError(`code=${response.code}${response.msg === undefined ? '' : ` ${response.msg}`}`, response.code)
+  }
+}
+
+/** Run one raw request, mapping thrown and non-zero-code failures to {@link FeishuApiError}. */
+async function feishuCall<T extends { code?: number; msg?: string }>(call: () => Promise<T>): Promise<T> {
+  let response: T
+  try {
+    response = await call()
+  } catch (error) {
+    const { detail, code } = thrownErrorFields(error)
+    throw new FeishuApiError(detail, code)
+  }
+  assertFeishuOk(response)
+  return response
+}
+
+/**
+ * Run one upload. The typed upload methods return the `data` object directly
+ * (or `null`) and throw on a non-zero code, so only thrown errors need mapping.
+ */
+async function feishuUpload<T>(call: () => Promise<T>): Promise<T> {
+  try {
+    return await call()
+  } catch (error) {
+    const { detail, code } = thrownErrorFields(error)
+    throw new FeishuApiError(detail, code)
+  }
+}
+
+/** Base path of the app slash-command endpoints (absent from SDK 1.76's typed client). */
+const SLASH_COMMANDS_PATH = '/open-apis/application/v7/app_slash_commands'
+
+/** One `app_slash_commands` list response (unpaginated). */
+interface SlashCommandListResponse {
+  code?: number
+  msg?: string
+  data?: {
+    items?: Array<{ command_id?: string; command?: string; description?: { default_value?: string } }>
+  }
+}
+
+/** `rawClient.request` as the slash-command endpoints use it. */
+type RawRequest = <T>(input: { method: string; url: string; data?: object }) => Promise<T>
+
+/**
+ * Create/update body. The panel icon stays at Feishu's default; PATCH
+ * replaces the whole `description` object.
+ */
+function slashCommandDescription(entry: SlashCommandEntry): object {
+  return { default_value: entry.description, i18n: { zh_cn: entry.description } }
+}
+
+/** {@link SlashCommandApi} over the SDK's generic authenticated request. */
+function slashCommandApi(request: RawRequest): SlashCommandApi {
+  const commandUrl = (id: string) => `${SLASH_COMMANDS_PATH}/${encodeURIComponent(id)}`
+  return {
+    async list(): Promise<readonly RemoteSlashCommand[]> {
+      const response = await feishuCall(() => request<SlashCommandListResponse>({ method: 'GET', url: SLASH_COMMANDS_PATH }))
+      return (response.data?.items ?? []).flatMap(item => item.command_id === undefined || item.command === undefined
+        ? []
+        : [{ id: item.command_id, command: item.command, description: item.description?.default_value ?? '' }])
+    },
+    async create(entry: SlashCommandEntry): Promise<void> {
+      await feishuCall(() => request<{ code?: number; msg?: string }>({
+        method: 'POST',
+        url: SLASH_COMMANDS_PATH,
+        data: { command: entry.command, description: slashCommandDescription(entry) },
+      }))
+    },
+    async update(id: string, entry: SlashCommandEntry): Promise<void> {
+      await feishuCall(() => request<{ code?: number; msg?: string }>({
+        method: 'PATCH',
+        url: commandUrl(id),
+        data: { description: slashCommandDescription(entry) },
+      }))
+    },
+    async delete(id: string): Promise<void> {
+      await feishuCall(() => request<{ code?: number; msg?: string }>({ method: 'DELETE', url: commandUrl(id) }))
+    },
+  }
+}
+
+function appOwnerLookupError(error: unknown): AppOwnerLookupError {
+  if (error instanceof AppOwnerLookupError) return error
+  const { detail, code } = thrownErrorFields(error)
+  return new AppOwnerLookupError(detail, code)
+}
+
 export interface ChannelConnectOptions {
   appId: string
   appSecret: string
@@ -171,17 +357,18 @@ export interface ChannelConnectOptions {
 
 class LarkChannelAdapter implements FeishuChannel {
   private readonly channel: LarkChannel
+  private readonly appId: string
   private readonly requireMention: boolean
   private readonly dmMode: 'open' | 'disabled'
+  readonly slashCommands: SlashCommandApi
 
   constructor(options: ChannelConnectOptions) {
     this.channel = createLarkChannel({
       appId: options.appId,
       appSecret: options.appSecret,
       loggerLevel: LOGGER_LEVELS[options.loggerLevel],
-      // Keep the raw event body: rich-text messages attach files in a
-      // top-level `files` array the SDK normalizer drops, so the attachment
-      // intake recovers them from `msg.raw` instead.
+      // Keep the raw event body: the sender `user_id` and the top-level
+      // rich-text `files` array are only recoverable from `msg.raw`.
       includeRawEvent: true,
       policy: {
         // The plugin routes mentions itself (thread routing must work without
@@ -190,13 +377,38 @@ class LarkChannelAdapter implements FeishuChannel {
         dmMode: options.dmMode === 'open' ? 'open' : 'disabled',
         respondToMentionAll: false,
       },
+      safety: {
+        // The SDK debounces messages per chatId and merges a burst into one
+        // message carrying the LAST sender/thread/message id. In a group that
+        // attributes one user's text and files to another, bypassing admission
+        // and topic ownership. Flush every message on its own; per-chat
+        // serialization and dedup stay in place.
+        batch: { text: { delayMs: 0 } },
+      },
     })
+    this.appId = options.appId
     this.requireMention = options.requireMention
     this.dmMode = options.dmMode
+    const rawClient = this.channel.rawClient
+    this.slashCommands = slashCommandApi(async <T,>(input: Parameters<RawRequest>[0]) => await rawClient.request<T>(input))
   }
 
   onMessage(handler: (message: NormalizedMessage) => void | Promise<void>): () => void {
-    return this.channel.on('message', handler)
+    return this.channel.on('message', message => {
+      const userId = senderUserIdOf(message.raw)
+      if (userId === undefined) {
+        // Bots and other apps never carry a user_id; neither do external
+        // users or a tenant app without the user ID scope. None of them can
+        // be identified, so none of them may reach admission or routing.
+        console.warn(
+          '[dsh-channels] dropped message %s: sender has no user_id '
+          + '(bot/app sender, external user, or the app lacks contact:user.employee_id:readonly)',
+          message.messageId,
+        )
+        return
+      }
+      return handler({ ...message, senderId: userId })
+    })
   }
 
   onCardAction(handler: (event: CardActionEvent) => void | Promise<void>): () => void {
@@ -223,6 +435,34 @@ class LarkChannelAdapter implements FeishuChannel {
     return this.channel.getConnectionStatus()
   }
 
+  async appOwnerUserId(): Promise<string | undefined> {
+    let response
+    try {
+      response = await this.channel.rawClient.application.v6.application.get({
+        path: { app_id: this.appId },
+        params: { lang: 'zh_cn', user_id_type: 'user_id' },
+      })
+    } catch (error) {
+      throw appOwnerLookupError(error)
+    }
+    if (response.code !== undefined && response.code !== 0) {
+      throw new AppOwnerLookupError(`code=${response.code}${response.msg === undefined ? '' : ` ${response.msg}`}`, response.code)
+    }
+    const owner = response.data?.app?.owner
+    if (owner?.type !== APP_OWNER_TYPE_TENANT_MEMBER) return undefined
+    const userId = owner.owner_id?.trim()
+    return userId === undefined || userId === '' ? undefined : userId
+  }
+
+  async grantedScopes(): Promise<readonly ScopeGrant[]> {
+    const response = await feishuCall(() => this.channel.rawClient.application.v6.scope.list())
+    return (response.data?.scopes ?? []).map(scope => ({
+      name: scope.scope_name,
+      granted: scope.grant_status === SCOPE_GRANTED_STATUS,
+      ...(scope.scope_type === undefined ? {} : { type: scope.scope_type }),
+    }))
+  }
+
   async connect(): Promise<void> {
     await this.channel.connect()
   }
@@ -239,6 +479,31 @@ class LarkChannelAdapter implements FeishuChannel {
     return this.channel.send(chatId, input, options)
   }
 
+  async replyMedia(replyTo: string, media: OutboundMedia, options: { replyInThread: boolean }): Promise<SendResult> {
+    const im = this.channel.rawClient.im.v1
+    let content: string
+    if (media.kind === 'image') {
+      const uploaded = await feishuUpload(() => im.image.create({ data: { image_type: 'message', image: media.data } }))
+      const imageKey = uploaded?.image_key
+      if (imageKey === undefined) throw new FeishuApiError('image_key missing in upload response')
+      content = JSON.stringify({ image_key: imageKey })
+    } else {
+      const uploaded = await feishuUpload(() => im.file.create({
+        data: { file_type: 'stream', file_name: media.fileName, file: media.data },
+      }))
+      const fileKey = uploaded?.file_key
+      if (fileKey === undefined) throw new FeishuApiError('file_key missing in upload response')
+      content = JSON.stringify({ file_key: fileKey })
+    }
+    const sent = await feishuCall(() => im.message.reply({
+      path: { message_id: replyTo },
+      data: { msg_type: media.kind, content, reply_in_thread: options.replyInThread },
+    }))
+    const messageId = sent.data?.message_id
+    if (messageId === undefined) throw new FeishuApiError('message_id missing in reply response')
+    return { messageId }
+  }
+
   async updateCard(messageId: string, card: object): Promise<void> {
     await this.channel.updateCard(messageId, card)
   }
@@ -256,6 +521,41 @@ class LarkChannelAdapter implements FeishuChannel {
     return res?.data?.items?.[0]?.thread_id
   }
 
+  async messageGet(messageId: string): Promise<unknown> {
+    const message = this.channel.rawClient.im.v1.message as unknown as {
+      get(input: { path: { message_id: string }; params: { user_id_type: 'user_id' } }): Promise<unknown>
+    }
+    return await message.get({ path: { message_id: messageId }, params: { user_id_type: 'user_id' } })
+  }
+
+  async messageMget(messageIds: readonly string[]): Promise<unknown> {
+    // SDK 1.76 has no typed `im.v1.message.mget`; the endpoint is
+    // `GET /open-apis/im/v1/messages/mget` with *repeated* `message_ids`
+    // query params (comma-separated ids are rejected by Feishu with 99992354).
+    // Axios would serialize an array with brackets, so the query string is
+    // built explicitly inside the URL.
+    if (messageIds.length === 0 || messageIds.length > 50) {
+      throw new Error(`message.mget accepts 1-50 message ids (got ${messageIds.length})`)
+    }
+    const query = messageIds
+      .map(messageId => `message_ids=${encodeURIComponent(messageId)}`)
+      .join('&')
+    const client = this.channel.rawClient as unknown as {
+      request(input: { method: string; url: string }): Promise<unknown>
+    }
+    return await client.request({
+      method: 'GET',
+      url: `/open-apis/im/v1/messages/mget?${query}&card_msg_content_type=raw_card_content&user_id_type=user_id`,
+    })
+  }
+
+  async messageList(params: RawMessageListParams): Promise<unknown> {
+    const message = this.channel.rawClient.im.v1.message as unknown as {
+      list(input: { params: RawMessageListParams }): Promise<unknown>
+    }
+    return await message.list({ params })
+  }
+
   async downloadResource(
     messageId: string,
     fileKey: string,
@@ -326,6 +626,22 @@ export function sniffImageMediaType(data: Uint8Array): 'image/png' | 'image/jpeg
   return undefined
 }
 
+/**
+ * The sender `user_id` of one raw `im.message.receive_v1` event body. The SDK
+ * normalizer fills `senderId` with the open_id; the plugin identifies users by
+ * the tenant-wide `user_id`, which Feishu only sends to tenant-internal apps
+ * granted `contact:user.employee_id:readonly`.
+ *
+ * @param raw - `NormalizedMessage.raw` (requires `includeRawEvent`).
+ * @returns the non-empty `user_id`, or `undefined` when the event has none.
+ */
+export function senderUserIdOf(raw: unknown): string | undefined {
+  if (raw === null || typeof raw !== 'object') return undefined
+  const sender = (raw as { sender?: { sender_id?: { user_id?: unknown } } }).sender
+  const userId = sender?.sender_id?.user_id
+  return typeof userId === 'string' && userId !== '' ? userId : undefined
+}
+
 const LOGGER_LEVELS: Record<ChannelConnectOptions['loggerLevel'], LoggerLevel> = {
   debug: LoggerLevel.debug,
   info: LoggerLevel.info,

package/src/host/agent.ts

@@ -5,6 +5,7 @@
  * @module dsh-channels/host/agent
  */
 
+import type { AttachmentStore } from './attachments.ts'
 import type { CommandRuntime } from './commands.ts'
 import type { Session, SessionId, UserMessage } from './core.ts'
 
@@ -58,10 +59,64 @@ export interface SystemPromptRuntime {
   section(section: PromptSection): () => void
 }
 
+/** One model-facing content block a channel tool may project (text/image/file). */
+export interface ToolContentBlock {
+  readonly type: string
+  readonly [key: string]: unknown
+}
+
+/** One tool execution's cooperative cancellation signal. */
+export interface ToolExecution {
+  readonly signal: AbortSignal
+}
+
+/** Canonical output contract of one channel tool registration. */
+export interface ToolOutputContract {
+  readonly schema: Record<string, unknown>
+  render(args: Record<string, unknown>, value: unknown): readonly ToolContentBlock[]
+  presentationMeta?(args: Record<string, unknown>, value: unknown): unknown
+}
+
+/**
+ * One model-facing tool registration. Kept structural (no runtime import of
+ * the host's `@deepseek-ai/dsh-tools` package) so the plugin keeps its
+ * zero-host-dependency stance.
+ */
+export interface ToolDefinition {
+  readonly name: string
+  readonly description: string
+  readonly parameters: Record<string, unknown>
+  readonly output: ToolOutputContract
+  readonly timeoutMs?: number
+  execute(
+    args: Record<string, unknown>,
+    exec: ToolExecution,
+  ): Promise<unknown> | unknown
+  presentCall?(args: Record<string, unknown>): unknown
+  presentResult?(args: Record<string, unknown>, value: unknown): unknown
+  readonly isConcurrencySafe?: () => boolean
+}
+
+/** The Agent-scoped slice of the host `tools` registry. */
+export interface ToolRuntime {
+  register(definition: ToolDefinition): unknown
+}
+
 export interface AgentContext {
   commands: CommandRuntime
   /** Present inside a setup scope that injected `systemPrompt`. */
   systemPrompt?: SystemPromptRuntime
+  /** Present inside a setup scope that injected `tools`. */
+  tools?: ToolRuntime
+  /**
+   * Present inside a setup scope that injected `attachments` (the DSH native
+   * attachment store). Optional: headless or legacy hosts, and test doubles,
+   * may not mount it, so consumers resolve it through the degradation-aware
+   * helper in `src/feishu/native-attachments.ts` instead of assuming presence.
+   */
+  attachments?: AttachmentStore
+  /** Safe service lookup (returns undefined for absent services). */
+  get?(name: string): unknown
   /** Register an Agent-scoped model-call override. */
   on(
     event: 'agent/request',