// types.d.ts — dsh-mask 类型契约（会话事件声明合并 + 配置类型）。

declare module '@deepseek-ai/dsh-session' {
  interface SessionEventMap {
    /**
     * 一次请求前脱敏的审计记录（log-only）：只记"替换了多少处 + 类型分布"，
     * 绝不携带 PII 原文或占位符映射。事实陈述：当前宿主代际
     * （KNOWN_SESSION_EVENT_TYPES，0.1.6-alpha.2 的 58 项快照）未收录 mask/*，
     * 且 append 无法盖章 ignorable 信封，因此运行时自适应门**不落盘**该事件、
     * 并在每个会话首次拒绝时打一条可见告警（审计缺失是文档化限制，不是静默失败）。
     * 宿主收录该类型后同一门自动开启落盘（见 README「会话事件」）。
     */
    'mask/applied': {
      sessionId: string
      replaced: number
      distribution: Record<string, number>
    }
  }
}

export interface Config {
  /** 总开关；false 时命令、工具与 pre-step 监听器全部卸载。 */
  enabled?: boolean
  /** 检测模式；只有 'regex' 实现，'regex+ner'（姓名/地址识别）预留并响亮失败。 */
  mode?: 'regex' | 'regex+ner'
  /** 启用的实体类型；regex 集为 phone/email/id-card/bank-card/key/ip，person/address 需 NER。 */
  entities?: string[]
  /**
   * 遮罩作用域；'messages' = agent/pre-step 入站消息，'tools' = tools/post-execute
   * 工具结果。可传单个字符串或数组（如 `['messages', 'tools']`）。默认 `['messages']`。
   */
  scope?: 'messages' | 'tools' | Array<'messages' | 'tools'>
  /** 注册 /mask 命令（默认 true）。 */
  registerCommand?: boolean
  /** tools 服务存在时注册 mask_test 工具（默认 true）。 */
  registerTools?: boolean
  /** 恢复表持久化到受控 storageDomain（false = 仅内存，重启丢失）。 */
  persistRestoreTable?: boolean
  /** 每会话恢复条目上限（超出逐出最旧）。 */
  maxRestoreEntriesPerSession?: number
  /** 内存会话脱敏器上限（LRU 逐出，映射按需从领域回载）。 */
  maxSessions?: number
  /** 浏览器半自动还原气泡开关（防御性 client slot；默认 false，未启用前对 UI 无副作用）。 */
  maskClientEnabled?: boolean
  /**
   * `/mask restore` 明文交付目录（默认空串 = `os.tmpdir()/dsh-mask-restore`）。
   * 宿主把命令结果原样写进会话日志、客户端又从同一条事件渲染用户可见输出，
   * `restore` 的明文因此绝不放进结果文本，只写进该目录下的受控文件
   * （每会话一个，mode 0600，下次还原覆盖），结果文本只回路径与占位符名。
   */
  restoreDir?: string
}

/** mask_test 工具规范结果。 */
export interface MaskTestValue {
  ok: boolean
  masked: string
  replaced: number
  distribution: { label: string; count: number }[]
  error?: string
}