dsh-session-chat 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+# dsh-session-chat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **实验性插件（MVP）**：让 DSH 里两个**独立会话**互相发纯文本消息。
+> 只对话，不碰文件；不代替 subagent / Agent Teams 做任务委派。
+>
+> 开发/验证/运维记录（安装路径、启动安全、验证证据、坑清单）见工作区文档
+> [`docs/插件-dsh-session-chat.md`](../docs/插件-dsh-session-chat.md)。
+
+## 它解决什么问题
+
+DSH 的平级会话（两个 root session）之间没有消息通道：`send_message` 只对子会话/父会话生效，
+`@` 引用只是只读快照。于是「两个会话在同一个仓库里改到了同一批文件，需要当场协商」时，
+只能靠人来回转达。
+
+这个插件在 host 进程里注册两个工具，把消息直接投进目标会话的 inbox——用宿主自己的
+`agent-message` 消息源（与 Agent Teams 内部同一套投递机制），因此历史持久化、会话回放、
+UI 渲染都天然兼容。
+
+## 两个工具
+
+### `session_peers`
+
+列出**同工作区**的 live 会话（默认不含自己）：
+
+```jsonc
+{ "count": 1, "peers": [
+  { "sessionId": "session-bbbbbbbb-...", "shortId": "22222222", "status": "idle",
+    "root": true, "self": false, "sameWorkspace": true, "canReceive": true,
+    "cwd": "D:\\code\\iwhaleCloud" }
+] }
+```
+
+### `session_send`
+
+把一个会话的文本投递到另一个会话：
+
+```jsonc
+// 参数
+{ "target": "session-bbbbbbbb-...", "message": "UserGroup.java 归你，我的分支已让开；你先合入 proc" }
+// 返回
+{ "delivered": true, "messageId": "…", "targetSessionId": "…", "targetShortId": "…", "targetStatus": "idle" }
+```
+
+目标侧看到的是普通用户消息（前缀 `Agent <发送方 session id> sent a message: `），
+source 为 `{ kind: 'agent-message', form: 'relay', senderSessionId }`：
+
+- 目标**正在运行** → 消息在它最近的 step 边界注入（steer）；
+- 目标**空闲** → 直接开始新的一轮（steer 对 idle driver 起 turn）；
+- 回消息：用 `session_send`，target 填对方 session id（从消息前缀里读）。
+
+> **主路径是"用户直接给 id"**：DSH 会话列表每行的菜单里有「复制会话 ID」，把那个 id 贴进
+> prompt 即可（带引号/反引号/空格也能识别）。`session_peers` 只是不知道 id、或需要确认
+> 对方是否 live 时的**可选发现助手**，不是必经步骤。
+
+## 边界（重要）
+
+1. **只投递文本**。插件不读写文件、不给工具、不给权限。收到消息的会话仍然按它自己的
+   permission / sandbox 行事——要「只聊不改文件」，得让它处于 plan / 只读预设。
+2. **只投递 live 会话**。不会冷启动一个没打开的会话（避免一句话偷偷唤醒会话、消耗 token）。
+3. **只允许同工作区**（双方 `cwd` 归一化后相等，Windows 大小写不敏感）。
+4. **默认只允许 root 会话**（`delegationDepth === 0` 且无 `parentSession`）；subagent / teammate
+   有各自的投递路径，不让它们走这条。可用 `allowNonRootSessions: true` 放开。
+5. **限流**：每对 (sender, target) 默认 `30 条 / 10 分钟`（进程内，重启清零）；单条默认 8 KB。
+6. **跨会话内容本质上是不可信输入**：目标模型会把它当用户消息读。只在你自己信任的会话之间使用；
+   白名单不是可选项，是给"多会话共享 profile"场景兜底的。
+
+## 配置
+
+在 profile 的 bundle patch（`cordis.patch.yml`）里：
+
+```yaml
+- insert:
+    - id: session-chat
+      name: 'dsh-session-chat'
+      config:
+        disabled: false            # true = 加载但什么都不注册（kill switch）
+        allowlist: []              # 目标会话白名单（session id 或 uuid）；空 = 同工作区 root 即可
+        maxMessageBytes: 8192
+        maxMessagesPerWindow: 30
+        windowMs: 600000
+        allowNonRootSessions: false
+```
+
+非法配置**不会**阻断加载：类型不对/越界的值回落默认值。
+
+## 构建与自测
+
+```powershell
+cd D:\code\local\dsh-session-chat
+node scripts\gen-typecheck-paths.mjs   # 生成 351 个 @deepseek-ai/* path 映射（本机沙箱不允许 junction）
+npx tsc -p tsconfig.typecheck.json     # 对真实宿主 .d.ts 做类型检查
+npx tsdown                             # 产物：lib/index.js + lib/index.d.ts
+node scripts\validate-schemas.mjs      # 用真实宿主 tools 包校验 schema（register + 参数校验）
+node scripts\probe.mjs                 # 假 ctx 探针：18 项检查（投递形状 + 全部拒绝分支）
+```
+
+三个校验脚本都不需要安装进 DSH，也不会碰真实会话。`npm run verify` 可一次跑后两个。
+
+## 安装（需要重启应用）
+
+两种方式，任选其一：
+
+**A. 从 npm 安装（推荐，发布后）**
+
+```powershell
+dsh plugin --profile desktop add dsh-session-chat
+```
+
+**B. 从本地工程装（开发期预览）**
+
+安装脚本写的是 **profile 目录**（工作区之外），请在你自己的终端里执行：
+
+```powershell
+cd D:\code\local\dsh-session-chat
+pwsh -NoProfile -File .\scripts\deploy.ps1            # 复制到 profile + 加进 bundles（自动备份 package.json）
+pwsh -NoProfile -File .\scripts\deploy.ps1 -Uninstall # 卸载
+```
+
+脚本会：
+1. 把 `lib/`、`package.json`、`cordis.patch.yml` 拷到
+   `%DSH_HOME%\profiles\desktop\node_modules\dsh-session-chat\`；
+2. 备份 profile 的 `package.json` 为 `package.json.bak-session-chat-<时间戳>`；
+3. 把 `dsh-session-chat` 追加到 `dsh.profile.bundles`。
+
+然后**手动关闭并重开应用**（host 插件必须重启才加载）。验证：
+1. 新开会话里问模型「调 session_peers 看看有哪些会话」；
+2. 用 `session_send` 给另一个会话发一句；
+3. 在目标会话里确认收到 `Agent … sent a message:`。
+
+⚠️ 装坏了导致启动失败时：对话框点「重启应用」，**不要点「禁用第三方插件」**（那会改名
+`cordis.patch.yml` 并把 bundles 重置为官方两项，见工作区 AGENTS.md）。回滚用 `-Uninstall`。
+
+> ⚠️ **已知安装侧注意事项**：
+> - profile 用 pnpm 管理依赖。`pnpm install`（含插件页里的安装/卸载操作触发的 reconcile）
+>   可能清掉手工放进 `node_modules` 的目录、并把不在 `dependencies` 里的 bundle 条目移出
+>   `dsh.profile.bundles`——**升级/装插件后重新执行 `deploy.ps1` 即可**。
+> - 后续优化会把包打成 `file:*.tgz` 依赖写进 profile `package.json`，让 bundle 条目在
+>   pnpm 操作后仍被保留（本机沙箱下 `npm pack` 写不了缓存，暂缓）。
+> - 本插件是 host 插件，装/升级都需要重启应用；客户端不需要任何东西。
+
+## 启动风险与恢复（重要）
+
+host 插件加载失败会影响应用启动。DSH 的失败分三层：
+
+| 失败点 | 后果 | 处理 |
+|---|---|---|
+| 包解析失败 / manifest 缺 `dsh.bundle` / dsh 版本不兼容 | 该 bundle 被 **skipped**，应用照常启动（只是插件不生效） | 重跑 `deploy.ps1` |
+| `apply` 抛错（工具注册冲突等） | `plugin tree failed to load` → 应用起不来 → 致命对话框 | 见下 |
+| 运行期（工具调用 / 投递 / 目标会话处理） | 只影响该次工具结果或目标会话那一轮，**不会挂进程** | 重试、等对方空闲 |
+
+本插件为"绝不拖垮启动"做了这些：
+
+- `apply` 全程 `try/catch`：失败只打一条 `[session-chat] …` warning，插件保持惰性；
+- 两个工具**分别注册**，一个失败只禁用该工具，不影响另一个；
+- 运行期零 `@deepseek-ai/*` import（只用 `node:` 内置模块），不存在宿主包解析失败；
+- 配置非法只回落默认值，不抛错；
+- `deploy.ps1` 装完会用纯 node import 一次产物做预检，失败自动**回滚并恢复** profile `package.json`。
+
+**真的起不来时**（对话框只有 退出 / 重启 / 禁用第三方插件）：
+
+1. 先点「**重启应用**」；持续失败**千万不要点「禁用第三方插件」**——它会改名
+   `cordis.patch.yml` 并把 bundles 重置为官方两项（见工作区 AGENTS.md）。
+2. 安全卸载（应用未运行时执行）：
+   ```powershell
+   pwsh -NoProfile -File .\scripts\deploy.ps1 -Uninstall
+   ```
+3. 或用 kill switch（不删包）：在 profile 的 `cordis.patch.yml` 加
+   ```yaml
+   - id: session-chat
+     config:
+       disabled: true
+   ```
+   重启后插件照常加载，但不注册任何工具。
+4. 诊断：致命对话框会给崩溃报告文件路径；插件自身的 warning 以 `[session-chat]` 开头。
+
+## 已知限制（MVP，后续优化）
+
+- 每个消息会让目标跑一个完整 turn：延迟 = 一个 step，token/上下文成本真实存在；长对话会触发 compaction。
+- 没有标题：`session_peers` 只能给 id/状态，不能给会话标题（标题在投影里，尚未接入）。
+- 限流是进程内状态，重启清零；也没有跨窗口的"沙漏"统计。
+- 不跨进程：两个会话必须在同一个 DSH host 进程（桌面端默认满足）。
+- 不跨工作区；不冷启动；不允许非 root 会话。
+- 没有消息去重/重试：投递失败就是失败，调用方自己重发。
+- 没有设置页/UI：配置走 bundle patch。
+
+## 后续优化方向
+
+- 接入会话标题（`session_peers` 显示 title，体验立刻好一大截）；
+- 冷启动开关（`allowColdResume`，需显式开启）；
+- 限流持久化 + 会话对状态（谁在等谁）；
+- 消息去重（按 `messageId`）与送达回执；
+- 跨会话消息的"未读/待回"提醒（客户端 UI）；
+- 与 Agent Teams 融合：Team 内部已能互发，这里只补"两个独立 root"的场景。

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-session-chat bundle patch（供 profile bundles 列表加载）
+# id 是插件服务名（= 包名去掉 dsh- 前缀，与 token-guard / read-source 一致）；name 是 npm 包名。
+# ⚠️ 必须是顶层数组：只有注释没有 `- ` 项 → YAML 解析成 null → 宿主启动中止。
+- insert:
+    - id: session-chat
+      name: 'dsh-session-chat'
+      config: {}

package/lib/index.d.ts

@@ -0,0 +1,252 @@
+import { Context } from "@deepseek-ai/cordis";
+import { ToolDefinition } from "@deepseek-ai/dsh-tools";
+//#region src/config.d.ts
+/**
+ * 插件配置：全部可选，非法值**不阻断加载**，回落默认值（插件配置写错不该让应用起不来）。
+ *
+ * 配置来自 profile 的 bundle patch：`cordis.patch.yml` 里 `- insert: - id: session-chat ... config: {...}`。
+ */
+/** 插件配置的原始输入（loader 注入，字段全部可选）。 */
+interface SessionChatConfig {
+  /**
+   * 紧急开关：`true` 时插件照常加载但什么都不注册（启动安全的 kill switch）。
+   * 用 profile 的 `cordis.patch.yml` 覆盖同一个 id 即可生效，不需要删包。
+   */
+  readonly disabled?: boolean;
+  /**
+   * 目标会话白名单（session id 精确匹配，或只写 uuid 部分）。留空 = 允许“同工作区的 root 会话”。
+   * 一旦填写，只有名单里的会话能收到消息。
+   */
+  readonly allowlist?: readonly string[];
+  /** 单条消息的 UTF-8 上限，默认 8192。超限拒绝，不截断。 */
+  readonly maxMessageBytes?: number;
+  /** 同一对 (sender, target) 在一个窗口内最多可发多少条，默认 30。 */
+  readonly maxMessagesPerWindow?: number;
+  /** 限流窗口，毫秒，默认 600000（10 分钟）。 */
+  readonly windowMs?: number;
+  /**
+   * 是否允许“非 root 会话”（subagent / teammate 子会话）参与：
+   * 默认 false —— 发送方和目标都必须是 root 会话。
+   */
+  readonly allowNonRootSessions?: boolean;
+}
+/** 归一化后的配置。 */
+interface ResolvedSessionChatConfig {
+  readonly disabled: boolean;
+  readonly allowlist: readonly string[];
+  readonly maxMessageBytes: number;
+  readonly maxMessagesPerWindow: number;
+  readonly windowMs: number;
+  readonly allowNonRootSessions: boolean;
+}
+/**
+ * 归一化配置：类型不对、越界、空值都回落默认值，不抛错。
+ * @param input - loader 注入的原始配置（可能为 undefined）。
+ * @returns 可直接使用的配置。
+ */
+declare function resolveSessionChatConfig(input?: unknown): ResolvedSessionChatConfig;
+//#endregion
+//#region src/message.d.ts
+/** 一条跨会话消息（满足 `UserMessage` 的运行时形状）。 */
+interface SessionChatMessage {
+  readonly id: string;
+  readonly role: 'user';
+  readonly content: readonly {
+    readonly type: 'text';
+    readonly text: string;
+  }[];
+  readonly source: {
+    readonly kind: 'agent-message';
+    readonly form: 'relay';
+    readonly senderSessionId: string;
+  };
+}
+/**
+ * 构造一条投递给目标会话的用户消息。
+ * @param senderSessionId - 发送方会话 id（写进 source 与文本前缀）。
+ * @param text - 发送方给出的正文。
+ * @returns 已深冻结的消息对象。
+ */
+declare function buildSessionChatMessage(senderSessionId: string, text: string): SessionChatMessage;
+/**
+ * 递归冻结（消息进入 inbox 前应与宿主 `createMessage` 一样不可变）。
+ * @param value - 任意对象。
+ * @returns 同一个对象。
+ */
+declare function deepFreeze<T>(value: T): T;
+/**
+ * 计算文本的 UTF-8 字节数。
+ * @param text - 任意文本。
+ * @returns 字节数。
+ */
+declare function utf8Bytes(text: string): number;
+//#endregion
+//#region src/limits.d.ts
+/**
+ * 每对 (sender, target) 的滑动窗口限流。
+ *
+ * 为什么需要：会话聊天是**互相消耗模型 turn** 的，两个模型可以无限 ping-pong。
+ * 限流把“失控对喷”变成一条可读的 SESSION_CHAT_RATE_LIMITED 错误，让模型停下来。
+ */
+/** 限流判定结果。 */
+type RateLimitVerdict = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly retryAfterMs: number;
+};
+/** 进程内滑动窗口限流器（不持久化；应用重启即清零，符合 MVP 预期）。 */
+declare class PairRateLimiter {
+  private readonly maxPerWindow;
+  private readonly windowMs;
+  private readonly stamps;
+  /**
+   * @param maxPerWindow - 窗口内允许的消息条数（>=1）。
+   * @param windowMs - 窗口长度（毫秒，>=1）。
+   */
+  constructor(maxPerWindow: number, windowMs: number);
+  /**
+   * 尝试占用一个配额。只有真正要投递时才调用（参数校验之后再调用，避免坏消息吃掉配额）。
+   * @param sender - 发送方会话 id。
+   * @param target - 目标会话 id。
+   * @param now - 当前时间戳（毫秒，测试可注入）。
+   * @returns 放行，或建议的重试等待时间。
+   */
+  check(sender: string, target: string, now: number): RateLimitVerdict;
+  /** 清空状态（测试用）。 */
+  reset(): void;
+}
+//#endregion
+//#region src/agents.d.ts
+/** `SessionHeader` 的窄视图。 */
+interface SessionHeaderLike {
+  readonly id: string;
+  readonly cwd?: string;
+  readonly parentSession?: string;
+  readonly delegationDepth?: number;
+}
+/** `Agent` 的窄视图。 */
+interface AgentLike {
+  readonly id: string;
+  readonly session: {
+    readonly header: SessionHeaderLike;
+  };
+  readonly status: string;
+  steer(message: unknown): void;
+}
+/** `ctx.agents`（AgentRegistry）的窄视图。 */
+interface AgentsLike {
+  get(id: string): AgentLike | undefined;
+  list(): readonly AgentLike[];
+}
+/**
+ * 从插件上下文取 Agent 注册表。
+ * @param ctx - 插件上下文（只用到 `get`）。
+ * @returns 注册表，未挂载时为 undefined。
+ */
+declare function agentsFrom(ctx: unknown): AgentsLike | undefined;
+/**
+ * 是否 root 会话：无父会话且委派深度为 0。
+ * @param agent - 任意 live Agent。
+ * @returns root 时为 true。
+ */
+declare function isRootSession(agent: AgentLike): boolean;
+/**
+ * 两个会话是否同一工作区（cwd 解析后按平台大小写规则比较）。
+ * @param sender - 发送方 Agent。
+ * @param target - 目标 Agent。
+ * @returns 双方都记录过 cwd 且语义相同才为 true。
+ */
+declare function sameWorkspace(sender: AgentLike, target: AgentLike): boolean;
+/**
+ * 归一化 cwd 用于比较：`path.resolve` + Windows 下大小写不敏感。
+ * @param cwd - 会话记录的绝对路径。
+ * @returns 可比较的字符串；缺失/非法时为 undefined。
+ */
+declare function normalizeCwd(cwd: string | undefined): string | undefined;
+/**
+ * 归一化用户粘贴的会话 id：去空白、去包裹的引号/反引号/尖括号/中文引号。
+ *
+ * 来源场景：GUI 会话列表的「复制会话 ID」写的是原始 id（`session-<uuid>`），
+ * 用户把它贴进 prompt 时经常带引号、反引号或首尾空格，这里容忍这些噪声。
+ * @param raw - 模型/用户给出的目标字符串。
+ * @returns 用于查找的 id（可能为空串）。
+ */
+declare function normalizeSessionIdInput(raw: string): string;
+/**
+ * 按 id 找 live Agent；先精确匹配，再按 `session-` 前缀等价匹配。
+ * @param agents - Agent 注册表。
+ * @param target - 模型给出的会话 id。
+ * @returns 匹配的 Agent，找不到时为 undefined。
+ */
+declare function resolveTargetAgent(agents: AgentsLike, target: string): AgentLike | undefined;
+/**
+ * id 的短形式，仅用于展示；完整 id 仍随结果返回。
+ * @param id - session id。
+ * @returns 最后 8 个字符（uuid 片段）。
+ */
+declare function shortSessionId(id: string): string;
+//#endregion
+//#region src/tool.d.ts
+/** `session_send` 的返回值。 */
+interface SessionSendValue {
+  readonly delivered: boolean;
+  readonly messageId: string;
+  readonly targetSessionId: string;
+  readonly targetShortId: string;
+  readonly targetStatus: string;
+}
+/** `session_peers` 的返回值。 */
+interface SessionPeersValue {
+  readonly count: number;
+  readonly peers: readonly SessionPeerValue[];
+}
+/** `session_peers` 的一行。 */
+interface SessionPeerValue {
+  readonly sessionId: string;
+  readonly shortId: string;
+  readonly status: string;
+  readonly root: boolean;
+  readonly self: boolean;
+  readonly sameWorkspace: boolean;
+  readonly canReceive: boolean;
+  readonly cwd?: string;
+}
+/**
+ * 创建 `session_send` 工具定义。
+ * @param provide - 延迟解析的 Agent 注册表。
+ * @param config - 已归一化配置。
+ * @param limiter - 每对会话的限流器。
+ * @param now - 时钟（测试可注入）。
+ * @returns 可直接交给 `ctx.tools.register` 的定义。
+ */
+declare function createSessionSendTool(provide: () => AgentsLike | undefined, config: ResolvedSessionChatConfig, limiter: PairRateLimiter, now?: () => number): ToolDefinition;
+/**
+ * 创建 `session_peers` 工具定义。
+ * @param provide - 延迟解析的 Agent 注册表。
+ * @param config - 已归一化配置。
+ * @returns 可直接交给 `ctx.tools.register` 的定义。
+ */
+declare function createSessionPeersTool(provide: () => AgentsLike | undefined, config: ResolvedSessionChatConfig): ToolDefinition;
+//#endregion
+//#region src/index.d.ts
+/** 插件服务名（cordis.patch.yml 里的 id 同此；与 dsh-token-guard / dsh-read-source 一致，用包名去掉 dsh- 前缀）。 */
+declare const name = "session-chat";
+/**
+ * 只静态依赖 `tools`（注册工具必需）。
+ * `agents` 刻意不写进静态 inject：静态 inject 在服务缺失时会让插件一直等待；
+ * 改为执行期 `ctx.get('agents')` 探测，缺失时工具给出 SESSION_CHAT_UNAVAILABLE。
+ */
+declare const inject: string[];
+/**
+ * 插件入口：注册 `session_peers` 与 `session_send`。
+ *
+ * **启动安全**：apply 全程 try/catch，任何失败只让插件保持惰性（打印一条 warning），
+ * 绝不让 `plugin tree failed to load` 把整个应用拖进致命对话框；
+ * 单个工具注册失败也只禁用该工具。`config.disabled` 是无需删包的 kill switch。
+ * @param ctx - 插件上下文。
+ * @param config - bundle patch 注入的配置（全部可选）。
+ */
+declare function apply(ctx: Context, config?: SessionChatConfig): void;
+//#endregion
+export { PairRateLimiter, type ResolvedSessionChatConfig, type SessionChatConfig, type SessionPeerValue, type SessionPeersValue, type SessionSendValue, agentsFrom, apply, buildSessionChatMessage, createSessionPeersTool, createSessionSendTool, deepFreeze, inject, isRootSession, name, normalizeCwd, normalizeSessionIdInput, resolveSessionChatConfig, resolveTargetAgent, sameWorkspace, shortSessionId, utf8Bytes };

package/lib/index.js

@@ -0,0 +1,575 @@
+import { resolve } from "node:path";
+import { platform } from "node:os";
+import { randomUUID } from "node:crypto";
+//#region src/agents.ts
+/**
+* 宿主 Agent 接缝的**窄接口**：插件运行时零 `@deepseek-ai/*` value import，
+* 只按结构化类型使用 `ctx.get('agents')` 返回的注册表。
+*
+* 这里的字段全部来自 DSH 的公开约定：
+* - `Agent.id`：会话 id（`SessionId`，运行时就是字符串）；
+* - `Agent.session.header`：`cwd` / `parentSession` / `delegationDepth`；
+* - `Agent.status`：'running' | 'idle' | …；
+* - `Agent.steer(message)`：运行中在最近 step 边界注入，空闲则开一轮。
+*/
+/**
+* 从插件上下文取 Agent 注册表。
+* @param ctx - 插件上下文（只用到 `get`）。
+* @returns 注册表，未挂载时为 undefined。
+*/
+function agentsFrom(ctx) {
+	const get = ctx?.get;
+	if (typeof get !== "function") return void 0;
+	const agents = get.call(ctx, "agents");
+	if (agents === void 0 || agents === null) return void 0;
+	const registry = agents;
+	if (typeof registry.get !== "function" || typeof registry.list !== "function") return void 0;
+	return agents;
+}
+/**
+* 是否 root 会话：无父会话且委派深度为 0。
+* @param agent - 任意 live Agent。
+* @returns root 时为 true。
+*/
+function isRootSession(agent) {
+	const header = agent.session.header;
+	return (header.delegationDepth ?? 0) === 0 && header.parentSession === void 0;
+}
+/**
+* 两个会话是否同一工作区（cwd 解析后按平台大小写规则比较）。
+* @param sender - 发送方 Agent。
+* @param target - 目标 Agent。
+* @returns 双方都记录过 cwd 且语义相同才为 true。
+*/
+function sameWorkspace(sender, target) {
+	const left = normalizeCwd(sender.session.header.cwd);
+	const right = normalizeCwd(target.session.header.cwd);
+	return left !== void 0 && right !== void 0 && left === right;
+}
+/**
+* 归一化 cwd 用于比较：`path.resolve` + Windows 下大小写不敏感。
+* @param cwd - 会话记录的绝对路径。
+* @returns 可比较的字符串；缺失/非法时为 undefined。
+*/
+function normalizeCwd(cwd) {
+	if (typeof cwd !== "string" || cwd.trim().length === 0) return void 0;
+	try {
+		const resolved = resolve(cwd);
+		return platform() === "win32" ? resolved.toLowerCase() : resolved;
+	} catch {
+		return;
+	}
+}
+/** `session-<uuid>` 与 `<uuid>` 视为同一 id。 */
+function bareSessionId(id) {
+	return id.startsWith("session-") ? id.slice(8) : id;
+}
+/**
+* 归一化用户粘贴的会话 id：去空白、去包裹的引号/反引号/尖括号/中文引号。
+*
+* 来源场景：GUI 会话列表的「复制会话 ID」写的是原始 id（`session-<uuid>`），
+* 用户把它贴进 prompt 时经常带引号、反引号或首尾空格，这里容忍这些噪声。
+* @param raw - 模型/用户给出的目标字符串。
+* @returns 用于查找的 id（可能为空串）。
+*/
+function normalizeSessionIdInput(raw) {
+	return raw.trim().replace(/^["'`<\[(（「『]+/, "").replace(/["'`>\])）」』]+$/, "").trim();
+}
+/**
+* 按 id 找 live Agent；先精确匹配，再按 `session-` 前缀等价匹配。
+* @param agents - Agent 注册表。
+* @param target - 模型给出的会话 id。
+* @returns 匹配的 Agent，找不到时为 undefined。
+*/
+function resolveTargetAgent(agents, target) {
+	const exact = agents.get(target);
+	if (exact !== void 0) return exact;
+	const wanted = bareSessionId(target);
+	for (const agent of agents.list()) if (bareSessionId(agent.id) === wanted) return agent;
+}
+/**
+* id 的短形式，仅用于展示；完整 id 仍随结果返回。
+* @param id - session id。
+* @returns 最后 8 个字符（uuid 片段）。
+*/
+function shortSessionId(id) {
+	return bareSessionId(id).slice(-8);
+}
+//#endregion
+//#region src/config.ts
+const DEFAULT_MAX_MESSAGE_BYTES = 8192;
+const DEFAULT_MAX_MESSAGES_PER_WINDOW = 30;
+const DEFAULT_WINDOW_MS = 6e5;
+const MAX_MESSAGE_BYTES_CEILING = 65536;
+const MAX_MESSAGES_CEILING = 1e3;
+const WINDOW_MS_CEILING = 864e5;
+function positiveInteger(value, fallback, ceiling) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+	const bounded = Math.min(Math.floor(value), ceiling);
+	return bounded > 0 ? bounded : fallback;
+}
+/**
+* 归一化配置：类型不对、越界、空值都回落默认值，不抛错。
+* @param input - loader 注入的原始配置（可能为 undefined）。
+* @returns 可直接使用的配置。
+*/
+function resolveSessionChatConfig(input = {}) {
+	const record = typeof input === "object" && input !== null ? input : {};
+	const allowlist = Array.isArray(record.allowlist) ? record.allowlist.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter((entry) => entry.length > 0) : [];
+	return {
+		disabled: record.disabled === true,
+		allowlist,
+		maxMessageBytes: positiveInteger(record.maxMessageBytes, DEFAULT_MAX_MESSAGE_BYTES, MAX_MESSAGE_BYTES_CEILING),
+		maxMessagesPerWindow: positiveInteger(record.maxMessagesPerWindow, DEFAULT_MAX_MESSAGES_PER_WINDOW, MAX_MESSAGES_CEILING),
+		windowMs: positiveInteger(record.windowMs, DEFAULT_WINDOW_MS, WINDOW_MS_CEILING),
+		allowNonRootSessions: record.allowNonRootSessions === true
+	};
+}
+//#endregion
+//#region src/limits.ts
+/** 进程内滑动窗口限流器（不持久化；应用重启即清零，符合 MVP 预期）。 */
+var PairRateLimiter = class {
+	maxPerWindow;
+	windowMs;
+	stamps = /* @__PURE__ */ new Map();
+	/**
+	* @param maxPerWindow - 窗口内允许的消息条数（>=1）。
+	* @param windowMs - 窗口长度（毫秒，>=1）。
+	*/
+	constructor(maxPerWindow, windowMs) {
+		this.maxPerWindow = maxPerWindow;
+		this.windowMs = windowMs;
+	}
+	/**
+	* 尝试占用一个配额。只有真正要投递时才调用（参数校验之后再调用，避免坏消息吃掉配额）。
+	* @param sender - 发送方会话 id。
+	* @param target - 目标会话 id。
+	* @param now - 当前时间戳（毫秒，测试可注入）。
+	* @returns 放行，或建议的重试等待时间。
+	*/
+	check(sender, target, now) {
+		const key = `${sender}\u0000${target}`;
+		const cutoff = now - this.windowMs;
+		const kept = (this.stamps.get(key) ?? []).filter((at) => at > cutoff);
+		if (kept.length >= this.maxPerWindow) {
+			this.stamps.set(key, kept);
+			const oldest = kept[0] ?? now;
+			return {
+				ok: false,
+				retryAfterMs: Math.max(1, oldest + this.windowMs - now)
+			};
+		}
+		kept.push(now);
+		this.stamps.set(key, kept);
+		return { ok: true };
+	}
+	/** 清空状态（测试用）。 */
+	reset() {
+		this.stamps.clear();
+	}
+};
+//#endregion
+//#region src/message.ts
+/**
+* 构造“跨会话消息”的 durable 表达。
+*
+* 形状照宿主自己的 `createAgentMessage()`（subagent 包）来，保证三处一致：
+* - `role: 'user'`：接收方按普通用户消息处理（会触发/续接它的 turn）；
+* - `source: { kind: 'agent-message', form: 'relay', senderSessionId }`：session 格式 v3
+*   已登记该来源，持久化/回放/UI 都能识别（UI 会显示 agent 图标与 “message from agent” 标题）；
+* - 首块是 `Agent <id> sent a message: ` 前缀，把发送者身份写进模型可见文本。
+*
+* 这里是**手写**而不是 import 宿主函数：插件运行时零 `@deepseek-ai/*` value import
+* （宿主包解析属于插件不该依赖的细节），字段形状与宿主实现逐字对齐即可。
+*/
+/**
+* 构造一条投递给目标会话的用户消息。
+* @param senderSessionId - 发送方会话 id（写进 source 与文本前缀）。
+* @param text - 发送方给出的正文。
+* @returns 已深冻结的消息对象。
+*/
+function buildSessionChatMessage(senderSessionId, text) {
+	return deepFreeze({
+		id: randomUUID(),
+		role: "user",
+		content: [{
+			type: "text",
+			text: `Agent ${senderSessionId} sent a message: `
+		}, {
+			type: "text",
+			text
+		}],
+		source: {
+			kind: "agent-message",
+			form: "relay",
+			senderSessionId
+		}
+	});
+}
+/**
+* 递归冻结（消息进入 inbox 前应与宿主 `createMessage` 一样不可变）。
+* @param value - 任意对象。
+* @returns 同一个对象。
+*/
+function deepFreeze(value) {
+	if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const key of Object.keys(value)) deepFreeze(value[key]);
+	}
+	return value;
+}
+/**
+* 计算文本的 UTF-8 字节数。
+* @param text - 任意文本。
+* @returns 字节数。
+*/
+function utf8Bytes(text) {
+	return Buffer.byteLength(text, "utf8");
+}
+//#endregion
+//#region src/tool.ts
+const TOOL_SEND = "session_send";
+const TOOL_PEERS = "session_peers";
+const SEND_DESCRIPTION = [
+	"Send one short plain-text message to another live session of this DeepSeek Harness host.",
+	"Prefer the exact session id the user gave you: the session list row menu has \"Copy session ID\", and that",
+	"pasted id is authoritative — pass it straight through. Call session_peers only when you must discover an id",
+	"or verify that the target is live.",
+	"Use it only for conversation/negotiation that a human would otherwise relay by hand (e.g. two sessions",
+	"editing the same repository must agree on file ownership or merge order).",
+	"Delivery is asynchronous: a running target receives the message at its next step boundary, an idle target",
+	"starts a new turn. The returned receipt means \"accepted into the target inbox\", never \"the target replied\".",
+	"This tool does not read or write any file and does not grant tools or permissions.",
+	"Targets must be live root sessions in the same working directory as you. To reply, send to the session id",
+	"shown in the incoming message prefix (\"Agent <id> sent a message\").",
+	"Keep exchanges short: every message costs the target a full model step, and repeated ping-pong is rate",
+	"limited. For structured delegation use subagents or Agent Teams instead."
+].join(" ");
+const PEERS_DESCRIPTION = [
+	"Optional discovery helper: list the live sessions of this DeepSeek Harness host that you may talk to with",
+	"session_send. Skip it when the user already pasted a session id — that id is authoritative.",
+	"Only sessions in the same working directory are listed. Each row reports its session id, run status,",
+	"whether it is a root session, and whether it can currently receive a message (canReceive).",
+	"A session that is not listed has never been opened in this host or belongs to another workspace; it cannot",
+	"be messaged, because this tool never cold-starts a session."
+].join(" ");
+const SEND_PARAMETERS = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		target: {
+			type: "string",
+			description: "Session id copied from the session list (\"session-<uuid>\" or the bare uuid). Surrounding quotes, backticks, and whitespace are tolerated."
+		},
+		message: {
+			type: "string",
+			description: "Plain UTF-8 text to deliver. Be concise; this becomes one user-role message in the target session."
+		}
+	},
+	required: ["target", "message"]
+};
+const SEND_OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		delivered: { type: "boolean" },
+		messageId: { type: "string" },
+		targetSessionId: { type: "string" },
+		targetShortId: { type: "string" },
+		targetStatus: { type: "string" }
+	},
+	required: [
+		"delivered",
+		"messageId",
+		"targetSessionId",
+		"targetShortId",
+		"targetStatus"
+	]
+};
+const PEERS_PARAMETERS = {
+	type: "object",
+	additionalProperties: false,
+	properties: { include_self: {
+		type: "boolean",
+		description: "When true, include your own session in the list (default false)."
+	} }
+};
+const PEERS_OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		count: { type: "integer" },
+		peers: {
+			type: "array",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					sessionId: { type: "string" },
+					shortId: { type: "string" },
+					status: { type: "string" },
+					root: { type: "boolean" },
+					self: { type: "boolean" },
+					sameWorkspace: { type: "boolean" },
+					canReceive: { type: "boolean" },
+					cwd: { type: "string" }
+				},
+				required: [
+					"sessionId",
+					"shortId",
+					"status",
+					"root",
+					"self",
+					"sameWorkspace",
+					"canReceive"
+				]
+			}
+		}
+	},
+	required: ["count", "peers"]
+};
+/**
+* 取 Agent 注册表，缺失时给可判读的报错。
+* @param provide - 延迟解析的注册表提供者。
+* @returns 注册表。
+*/
+function requireAgents(provide) {
+	const agents = provide();
+	if (agents === void 0) throw new Error("SESSION_CHAT_UNAVAILABLE: the agents service is not mounted; session chat needs the host Agent registry");
+	return agents;
+}
+/**
+* 取调用方 Agent，缺失时报错（工具只能在 agent turn 内调用）。
+* @param exec - 工具执行上下文。
+* @returns 调用方 Agent。
+*/
+function requireCaller(exec) {
+	const agent = exec?.agent;
+	if (agent === void 0 || agent === null) throw new Error("SESSION_CHAT_NO_CALLER: this tool must be called from inside an agent turn");
+	return agent;
+}
+/**
+* root 会话校验（默认不允许 subagent/teammate 子会话参与）。
+* @param agent - 待校验 Agent。
+* @param role - 报错文案里的角色（caller / target）。
+* @param config - 已归一化配置。
+*/
+function assertRootSession(agent, role, config) {
+	if (config.allowNonRootSessions) return;
+	if (!isRootSession(agent)) throw new Error(`SESSION_CHAT_NOT_ROOT: the ${role} session (${shortSessionId(agent.id)}) is not a root session; nested subagent/teammate sessions use their own delivery path`);
+}
+/**
+* 同工作区校验。
+* @param caller - 发送方。
+* @param target - 目标。
+*/
+function assertSameWorkspace(caller, target) {
+	if (!sameWorkspace(caller, target)) {
+		const from = caller.session.header.cwd ?? "(no cwd)";
+		const to = target.session.header.cwd ?? "(no cwd)";
+		throw new Error(`SESSION_CHAT_CROSS_WORKSPACE: cross-workspace messaging is not allowed (${from} -> ${to})`);
+	}
+}
+/**
+* 白名单校验（白名单为空 = 只限制同工作区 root）。
+* @param targetId - 目标会话 id。
+* @param config - 已归一化配置。
+*/
+function assertAllowlisted(targetId, config) {
+	if (config.allowlist.length === 0) return;
+	const bare = targetId.startsWith("session-") ? targetId.slice(8) : targetId;
+	if (!config.allowlist.some((entry) => {
+		return (entry.startsWith("session-") ? entry.slice(8) : entry) === bare;
+	})) throw new Error(`SESSION_CHAT_NOT_ALLOWED: target session ${shortSessionId(targetId)} is not in the configured allowlist`);
+}
+/**
+* 判断目标能否收消息（只做静态校验，不触发限流）。
+* @param caller - 发送方。
+* @param candidate - 候选目标。
+* @param config - 已归一化配置。
+* @returns 可收时为 true。
+*/
+function canReceiveFrom(caller, candidate, config) {
+	if (candidate.id === caller.id) return false;
+	if (!config.allowNonRootSessions && !isRootSession(candidate)) return false;
+	if (!sameWorkspace(caller, candidate)) return false;
+	try {
+		assertAllowlisted(candidate.id, config);
+	} catch {
+		return false;
+	}
+	return true;
+}
+/**
+* 创建 `session_send` 工具定义。
+* @param provide - 延迟解析的 Agent 注册表。
+* @param config - 已归一化配置。
+* @param limiter - 每对会话的限流器。
+* @param now - 时钟（测试可注入）。
+* @returns 可直接交给 `ctx.tools.register` 的定义。
+*/
+function createSessionSendTool(provide, config, limiter, now = () => Date.now()) {
+	return {
+		name: TOOL_SEND,
+		description: SEND_DESCRIPTION,
+		parameters: SEND_PARAMETERS,
+		isConcurrencySafe: () => true,
+		output: {
+			schema: SEND_OUTPUT_SCHEMA,
+			render(_args, value) {
+				const record = typeof value === "object" && value !== null ? value : {};
+				return [{
+					type: "text",
+					text: `Delivered to session ${record.targetShortId ?? "?"} (${record.targetSessionId ?? "?"}) · message ${record.messageId ?? "?"} · target status: ${record.targetStatus ?? "?"}. Delivery is not a reply.`
+				}];
+			}
+		},
+		async execute(args, exec) {
+			const caller = requireCaller(exec);
+			const agents = requireAgents(provide);
+			const request = typeof args === "object" && args !== null ? args : {};
+			const targetId = typeof request.target === "string" ? normalizeSessionIdInput(request.target) : "";
+			const text = typeof request.message === "string" ? request.message : "";
+			if (targetId.length === 0) throw new Error("SESSION_CHAT_INVALID_TARGET: target must be a non-empty session id");
+			if (text.trim().length === 0) throw new Error("SESSION_CHAT_EMPTY_MESSAGE: message must not be empty");
+			const target = resolveTargetAgent(agents, targetId);
+			if (target === void 0) throw new Error(`SESSION_CHAT_UNKNOWN_TARGET: no live session "${targetId}" in this host; call session_peers to list live sessions (a session must be open to receive messages)`);
+			if (target.id === caller.id) throw new Error("SESSION_CHAT_SELF: a session cannot message itself");
+			assertRootSession(caller, "calling", config);
+			assertRootSession(target, "target", config);
+			assertSameWorkspace(caller, target);
+			assertAllowlisted(target.id, config);
+			const bytes = utf8Bytes(text);
+			if (bytes > config.maxMessageBytes) throw new Error(`SESSION_CHAT_TOO_LARGE: message is ${bytes} UTF-8 bytes, limit is ${config.maxMessageBytes}; send a shorter summary and put long content in a file both sessions can read`);
+			const verdict = limiter.check(caller.id, target.id, now());
+			if (!verdict.ok) throw new Error(`SESSION_CHAT_RATE_LIMITED: this session pair reached ${config.maxMessagesPerWindow} messages in ${Math.round(config.windowMs / 1e3)}s; retry in ~${Math.ceil(verdict.retryAfterMs / 1e3)}s or stop the conversation and hand the conclusion to the user`);
+			const message = buildSessionChatMessage(caller.id, text);
+			try {
+				target.steer(message);
+			} catch (error) {
+				throw new Error(`SESSION_CHAT_DELIVERY_FAILED: target inbox rejected the message (${error instanceof Error ? error.message : String(error)})`);
+			}
+			return {
+				delivered: true,
+				messageId: message.id,
+				targetSessionId: target.id,
+				targetShortId: shortSessionId(target.id),
+				targetStatus: target.status
+			};
+		}
+	};
+}
+/**
+* 创建 `session_peers` 工具定义。
+* @param provide - 延迟解析的 Agent 注册表。
+* @param config - 已归一化配置。
+* @returns 可直接交给 `ctx.tools.register` 的定义。
+*/
+function createSessionPeersTool(provide, config) {
+	return {
+		name: TOOL_PEERS,
+		description: PEERS_DESCRIPTION,
+		parameters: PEERS_PARAMETERS,
+		isConcurrencySafe: () => true,
+		output: {
+			schema: PEERS_OUTPUT_SCHEMA,
+			render(_args, value) {
+				const record = typeof value === "object" && value !== null ? value : {};
+				const peers = Array.isArray(record.peers) ? record.peers : [];
+				if (peers.length === 0) return [{
+					type: "text",
+					text: "No peer sessions in this workspace can receive messages."
+				}];
+				return [{
+					type: "text",
+					text: `Live sessions you may message:\n${peers.map((peer) => {
+						const flags = [
+							peer.root ? "root" : "nested",
+							peer.self ? "self" : "",
+							peer.sameWorkspace ? "same-workspace" : "other-workspace",
+							peer.canReceive ? "can-receive" : "cannot-receive"
+						].filter((flag) => flag.length > 0).join(", ");
+						return `- ${peer.sessionId} (${peer.shortId}) · ${peer.status} · ${flags}`;
+					}).join("\n")}`
+				}];
+			}
+		},
+		async execute(args, exec) {
+			const caller = requireCaller(exec);
+			const agents = requireAgents(provide);
+			const includeSelf = (typeof args === "object" && args !== null ? args : {}).include_self === true;
+			const peers = [];
+			for (const agent of agents.list()) {
+				const self = agent.id === caller.id;
+				if (self && !includeSelf) continue;
+				if (!sameWorkspace(caller, agent)) continue;
+				const row = {
+					sessionId: agent.id,
+					shortId: shortSessionId(agent.id),
+					status: agent.status,
+					root: isRootSession(agent),
+					self,
+					sameWorkspace: true,
+					canReceive: canReceiveFrom(caller, agent, config),
+					...agent.session.header.cwd === void 0 ? {} : { cwd: agent.session.header.cwd }
+				};
+				peers.push(row);
+			}
+			return {
+				count: peers.length,
+				peers
+			};
+		}
+	};
+}
+//#endregion
+//#region src/index.ts
+/** 插件服务名（cordis.patch.yml 里的 id 同此；与 dsh-token-guard / dsh-read-source 一致，用包名去掉 dsh- 前缀）。 */
+const name = "session-chat";
+/**
+* 只静态依赖 `tools`（注册工具必需）。
+* `agents` 刻意不写进静态 inject：静态 inject 在服务缺失时会让插件一直等待；
+* 改为执行期 `ctx.get('agents')` 探测，缺失时工具给出 SESSION_CHAT_UNAVAILABLE。
+*/
+const inject = ["tools"];
+/**
+* 插件入口：注册 `session_peers` 与 `session_send`。
+*
+* **启动安全**：apply 全程 try/catch，任何失败只让插件保持惰性（打印一条 warning），
+* 绝不让 `plugin tree failed to load` 把整个应用拖进致命对话框；
+* 单个工具注册失败也只禁用该工具。`config.disabled` 是无需删包的 kill switch。
+* @param ctx - 插件上下文。
+* @param config - bundle patch 注入的配置（全部可选）。
+*/
+function apply(ctx, config = {}) {
+	try {
+		const resolved = resolveSessionChatConfig(config);
+		if (resolved.disabled) {
+			report(ctx, "disabled by config; tools not registered");
+			return;
+		}
+		const limiter = new PairRateLimiter(resolved.maxMessagesPerWindow, resolved.windowMs);
+		const provideAgents = () => agentsFrom(ctx);
+		registerSafely(ctx, createSessionPeersTool(provideAgents, resolved), "session_peers");
+		registerSafely(ctx, createSessionSendTool(provideAgents, resolved, limiter), "session_send");
+	} catch (error) {
+		report(ctx, "failed to install; plugin stays inert", error);
+	}
+}
+/** 取宿主 logger（cordis 的 ctx.logger），没有就退回 console。 */
+function report(ctx, message, error) {
+	const text = `[session-chat] ${error === void 0 ? message : `${message}: ${error instanceof Error ? error.message : String(error)}`}`;
+	const logger = ctx.logger;
+	if (typeof logger?.warn === "function") logger.warn(text);
+	else console.warn(text);
+}
+/** 注册一个工具；失败只禁用该工具（同名冲突等），不冒泡到 boot。 */
+function registerSafely(ctx, definition, name) {
+	try {
+		ctx.tools.register(definition);
+	} catch (error) {
+		report(ctx, `failed to register tool "${name}"; that tool is unavailable`, error);
+	}
+}
+//#endregion
+export { PairRateLimiter, agentsFrom, apply, buildSessionChatMessage, createSessionPeersTool, createSessionSendTool, deepFreeze, inject, isRootSession, name, normalizeCwd, normalizeSessionIdInput, resolveSessionChatConfig, resolveTargetAgent, sameWorkspace, shortSessionId, utf8Bytes };

package/package.json

@@ -1,6 +1,48 @@
-{
-  "name": "dsh-session-chat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "dsh-session-chat",
+  "version": "0.1.0",
+  "description": "[EXPERIMENTAL] Plain-text chat between two independent DSH sessions: a host tool that delivers an agent message into another live session's inbox, with same-workspace, root-only, rate-limited delivery.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "displayName": "Session Chat",
+    "description": "两个独立会话之间的纯文本对话通道（不碰文件，带同工作区/root/限流护栏）",
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "cordis",
+    "session",
+    "chat"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "probe": "node scripts/probe.mjs",
+    "verify": "node scripts/validate-schemas.mjs && node scripts/probe.mjs",
+    "gen-paths": "node scripts/gen-typecheck-paths.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.2",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3"
+  }
+}