@modesto_ma/dsh-channels 0.2.0 → 0.4.0

package/src/feishu-channel.ts

@@ -88,6 +88,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. */
@@ -256,6 +276,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 } }): Promise<unknown>
+    }
+    return await message.get({ path: { message_id: messageId } })
+  }
+
+  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`,
+    })
+  }
+
+  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,

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',

package/src/host/attachments.ts

@@ -0,0 +1,210 @@
+/**
+ * Host bridge, attachment surface: the minimal `ctx.attachments` face this
+ * plugin consumes (durable image/file storage) plus the content-block and
+ * prompt-part shapes it produces.
+ *
+ * Everything here is declared locally and structurally. The DSH attachment
+ * packages are never imported at runtime and are not runtime dependencies of
+ * this plugin, so these types mirror their published shapes by convention:
+ * only the members this plugin actually reads or calls are modeled, and every
+ * service lookup tolerates a deployment without the service. The exact
+ * upstream package (`@deepseek-ai/dsh-attachment`, DSH 0.2.1-rc.2) has more
+ * operations (batches, request projection, encoded uploads); add them here
+ * only when a task needs them.
+ *
+ * @module dsh-channels/host/attachments
+ */
+
+// ---- Durable attachment vocabulary --------------------------------------
+
+/** Opaque content-addressed attachment identifier (never a filesystem path). */
+export type AttachmentId = string
+
+/** Raster image formats accepted by the version-one attachment path. */
+export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif'
+
+/** Durable, serializable reference to one immutable normalized image. */
+export interface ImageAttachmentRef {
+  /** Opaque storage identifier; never a filesystem path or bearer URL. */
+  attachmentId: AttachmentId
+  /** Media type verified from the stored bytes. */
+  mediaType: ImageMediaType
+  /** Exact encoded byte length. */
+  bytes: number
+  /** Intrinsic encoded width in pixels. */
+  width: number
+  /** Intrinsic encoded height in pixels. */
+  height: number
+  /** Optional display name stripped of local path information. */
+  name?: string
+  /**
+   * Input dimensions after applying EXIF orientation and before normalization
+   * scaling. Present only when normalization reduced the image.
+   */
+  originalDimensions?: {
+    width: number
+    height: number
+  }
+}
+
+/**
+ * Durable, serializable reference to one verbatim stored file. Files are
+ * stored byte-for-byte with no normalization; `attachmentId` is the sha256
+ * digest of exactly those bytes.
+ */
+export interface FileAttachmentRef {
+  /** Opaque content-addressed storage identifier; never a filesystem path. */
+  attachmentId: AttachmentId
+  /** Sanitized display filename, also the stored object's leaf name. */
+  name: string
+  /** Exact byte length. */
+  bytes: number
+}
+
+/** Deployment-resolved image limits used by upload admission. */
+export interface ImageAttachmentLimits {
+  maxImageBytes: number
+  maxImagesPerMessage: number
+  maxMessageImageBytes: number
+  maxImagePixels: number
+  /** Maximum intrinsic width and maximum intrinsic height in pixels for one image. */
+  maxImageDimension: number
+  mediaTypes: readonly ImageMediaType[]
+}
+
+/** Request to validate and durably commit one image. */
+export interface SaveImageAttachment {
+  /** Encoded bytes, checked against the declared media type by the service. */
+  data: Uint8Array
+  /** Caller-declared media type, checked against fully decoded bytes. */
+  mediaType: ImageMediaType
+  /** Optional display name; never interpreted as a path. */
+  name?: string
+}
+
+/** Request to durably commit one file from bounded byte chunks. */
+export interface SaveFileStreamAttachment {
+  /** Exact file bytes in order; providers must not retain the whole sequence. */
+  data: AsyncIterable<Uint8Array>
+  /** Optional cancellation for source reads and storage writes. */
+  signal?: AbortSignal
+  /** Optional display name; never interpreted as a path. */
+  name?: string
+}
+
+/** One text/image part of host prompt content whose images still need admission. */
+export type PromptContentPart = {
+  readonly type: 'text'
+  readonly text: string
+} | {
+  readonly type: 'image'
+  readonly mediaType: ImageMediaType
+  readonly data: string
+  readonly name?: string
+}
+
+/** Host prompt content whose file receipts are resolved and whose image bytes await admission. */
+export type AttachmentAdmissionPart = PromptContentPart | {
+  readonly type: 'file'
+  readonly attachment: FileAttachmentRef
+}
+
+/** Host-admitted prompt content with every attachment represented by its durable reference. */
+export type AdmittedPromptContentPart = {
+  readonly type: 'text'
+  readonly text: string
+} | {
+  readonly type: 'image'
+  readonly attachment: ImageAttachmentRef
+} | {
+  readonly type: 'file'
+  readonly attachment: FileAttachmentRef
+}
+
+// ---- Content blocks -----------------------------------------------------
+
+/**
+ * A durable raster image reference as it appears in model content
+ * (`ImageBlock` in `@deepseek-ai/dsh-llm`). The block is role-neutral; this
+ * plugin only produces it for user content.
+ */
+export interface ImageBlock {
+  type: 'image'
+  /** Immutable bytes and intrinsic display metadata owned by the service. */
+  attachment: ImageAttachmentRef
+}
+
+/**
+ * A durable verbatim file reference as it appears in model content
+ * (`FileBlock` in `@deepseek-ai/dsh-llm`). Files never reach a provider as
+ * bytes: request assembly projects them to handle text, so a channel tool that
+ * cannot deliver this block must fall back to {@link formatFileHandle}-style
+ * text instead.
+ */
+export interface FileBlock {
+  type: 'file'
+  /** Immutable verbatim bytes and display metadata owned by the service. */
+  attachment: FileAttachmentRef
+}
+
+// ---- Failure vocabulary -------------------------------------------------
+
+/**
+ * Stable attachment failure codes the host routes on
+ * (`AttachmentErrorCode` in `@deepseek-ai/dsh-attachment`). Kept as a
+ * type-only union; the runtime classifier lives in the Feishu storage module.
+ */
+export type AttachmentErrorCode =
+  | 'TOO_MANY_IMAGES'
+  | 'IMAGES_TOO_LARGE'
+  | 'UNSUPPORTED_IMAGE_TYPE'
+  | 'INVALID_IMAGE_BASE64'
+  | 'INVALID_IMAGE'
+  | 'IMAGE_TYPE_MISMATCH'
+  | 'IMAGE_TOO_LARGE'
+  | 'IMAGE_TOO_MANY_PIXELS'
+  | 'IMAGE_DIMENSION_TOO_LARGE'
+  | 'INVALID_FILE_BASE64'
+  | 'INVALID_ATTACHMENT_REF'
+  | 'ATTACHMENT_CORRUPT'
+  | 'ATTACHMENT_WRITE_FAILED'
+  | 'ATTACHMENT_NOT_FOUND'
+  | 'ATTACHMENT_READ_FAILED'
+  | 'ATTACHMENT_PROJECTION_UNSUPPORTED'
+  | 'ATTACHMENT_FILES_UNSUPPORTED'
+
+// ---- Service surface ----------------------------------------------------
+
+/**
+ * The narrow `ctx.attachments` service face. Every method mirrors the
+ * upstream contract; callers must go through a module that tolerates absence
+ * (for example `src/feishu/native-attachments.ts`) rather than branching on
+ * this type themselves, so the degradation path exists in exactly one place.
+ */
+export interface AttachmentStore {
+  /** Deployment-resolved image policy; absent on minimal embedding hosts. */
+  readonly imageLimits?: ImageAttachmentLimits
+  /** Validate, normalize, and durably commit one image. */
+  saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>
+  /** Durably commit one verbatim file from bounded chunks (backpressure, no full buffering). */
+  saveFileStream(input: SaveFileStreamAttachment): Promise<FileAttachmentRef>
+  /**
+   * Locate the verbatim stored file object in the harness host filesystem.
+   * @returns an absolute host path, or undefined when this backend is not
+   *   host-file-backed.
+   * @throws an attachment error when the durable reference is invalid.
+   */
+  fileHostPath(ref: FileAttachmentRef): string | undefined
+  /**
+   * Locate the provider-owned normalized image object in the harness host
+   * filesystem.
+   * @returns an absolute host path, or undefined when this backend is not
+   *   host-file-backed.
+   * @throws an attachment error when the durable reference is invalid.
+   */
+  imageHostPath(ref: ImageAttachmentRef): string | undefined
+  /** Replace every uploaded image in one host prompt with its durable reference. */
+  admitPromptContent(content: readonly AttachmentAdmissionPart[]): Promise<AdmittedPromptContentPart[]>
+  /** Optional host-provided classifier for attachment failures (cross-install safe). */
+  isAttachmentError?(error: unknown): boolean
+}

package/src/host/index.ts

@@ -7,6 +7,7 @@
 
 export * from './core.ts'
 export * from './agent.ts'
+export * from './attachments.ts'
 export * from './commands.ts'
 export * from './interaction.ts'
 export * from './services.ts'

package/src/index.ts

@@ -3,12 +3,14 @@
  *
  * 一个 dsh 实例对应一个飞书机器人；用户通过私聊、群聊 @、话题群 @ 三种方式
  * 发起会话。每条触发消息：立即加 “Typing” 表情 → 以话题形式回复（创建话题）
- * → 绑定 DSH session → 卡片 2.0 流式回复（推理折叠面板 + 富文本正文 + 两行
- * session 信息，默认 500ms 刷新）→ 流式结束移除 Typing，成功更新为
+ * → 绑定 DSH session → 卡片 2.0 流式回复（推理折叠面板 + 临时活动行 +
+ * 富文本正文 + 结算页脚，默认 500ms 刷新）→ 流式结束移除 Typing，成功更新为
  * “DONE”，失败显示结构化错误并更新为 “No”。
  *
  * 工作区归属：私聊一人一工作区；群聊中每个用户在该群拥有独立工作区
- * （目录即工作区，会话以 cwd 落盘）。
+ * （工作区是会话 header cwd，保证 GUI 归属与沙箱边界）。每个话题在该工作区
+ * 内拥有独立的工作目录（`topics/<话题>`，Git 仓库工作区可自动改用 worktree），
+ * 因此话题之间的文件互不干扰，而工作区数量只随用户增长。
  *
  * @module dsh-channels
  */
@@ -51,7 +53,7 @@ export type { HostDirectoryPickerService, SettingsDirectoryPicker } from './sett
 export { isSameOriginRequest, mountSettingsRoutes, registerSettingsRoutes } from './settings/routes.ts'
 export type { HostWebServer } from './settings/routes.ts'
 export type { ApprovalOutcome, ApprovalRequest, ApprovalAnswererListener, AssistantStreamFrame, AskUserQuestionAnswer, AskUserQuestionAnswerItem, AskUserQuestionItem, AskUserQuestionRequestEvent, UserQuestionAnswererListener, AgentCancelCause, SessionStatsView, TokenUsageView, ContextPressureView, SessionProjections } from './dsh-types.ts'
-export { buildCard, buildInterruptionCard, cardJsonBytes, CARD_MAX_BYTES, CARD_TARGET_BYTES, CARD_PANEL_RESERVE_BYTES, REASONING_MAX_BYTES, INTERRUPTION_NOTICE, MAX_TABLES_PER_CARD, PANEL_TITLES, PANEL_CHEVRON_TOKEN, segmentCardContent, splitBodyForCard, stripTables, tableBlocks, TRUNCATION_SUFFIX, buildApprovalCard, buildApprovalSettledCard, buildQuestionCard, buildQuestionSettledCard, MAX_QUESTION_OPTIONS } from './cards.ts'
+export { buildCard, buildInterruptionCard, cardJsonBytes, CARD_MAX_BYTES, CARD_TARGET_BYTES, REASONING_MAX_BYTES, INTERRUPTION_NOTICE, MAX_TABLES_PER_CARD, PANEL_TITLES, PANEL_CHEVRON_TOKEN, segmentCardContent, splitBodyForCard, stripTables, tableBlocks, TRUNCATION_SUFFIX, buildApprovalCard, buildApprovalSettledCard, buildQuestionCard, buildQuestionSettledCard, MAX_QUESTION_OPTIONS } from './cards.ts'
 export { ApprovalAnswerer } from './approvals.ts'
 export { QuestionAnswerer } from './questions.ts'
 export { armModelCommand, buildCommandResultCard, CHANNEL_COMMAND_NAMES, commandResultCardKind, isSupportedCommand, parseSlashCommand, registerChannelCommands, registerModelCommand, RouteOperationQueue, SUPPORTED_COMMAND_NAMES, supportedCommandHelp, supportedCommandList } from './commands.ts'
@@ -61,8 +63,8 @@ export { createLogicalSessionExport, DSH_CHANNELS_VERSION, LOGICAL_EXPORT_FORMAT
 export { addUsage, applyProjectionViews, averageDecodeTokensPerSecond, averageTtftMs, cacheHitPct, EMPTY_TOTALS, foldAll, foldEvent, foldSessionStats, measureSessionContext, readProjectionViews, usageFromBuckets } from './stats.ts'
 export { FeishuService } from './service.ts'
 export { TurnStreamer } from './streamer.ts'
-export { ensureWorkspace, stagingPathFor, topicTokenFor, workspacePathFor, workspaceTitleFor } from './workspaces.ts'
-export { accessGroupRecordSchema, accessRequestRecordSchema, accessUserRecordSchema, appendSessionHistory, chatRouteKey, expiredRouteRecordSchema, feishuDomain, normalizeRouteRecord, normalizeSessionHistory, routeRecordSchema, sessionHistoryEntrySchema, inflightSnapshotSchema, processedRecordSchema } from './domain.ts'
+export { ensureWorkspace, legacyTopicWorkspaceRoot, stagingPathFor, stagingRoot, topicDirFor, topicTokenFor, workspacePathFor, workspaceTitleFor, worktreeBranchFor } from './workspaces.ts'
+export { accessGroupRecordSchema, accessRequestRecordSchema, accessUserRecordSchema, appendSessionHistory, chatRouteKey, expiredRouteRecordSchema, feishuDomain, normalizeRouteRecord, normalizeSessionHistory, routeRecordSchema, sessionDirOf, sessionHistoryEntrySchema, inflightSnapshotSchema, processedRecordSchema } from './domain.ts'
 
 /** Cordis function-plugin name. */
 export const name = 'channels'