vongostev/dsh-cross-session

@vongostev/dsh-cross-session

同一进程内多个活动 DSH 会话之间的跨会话消息传递：一个会话向另一个会话发送文本消息并触发其事件处理，或向其持久日志追加自定义事件。

功能

该插件在 ctx.tools 上注册三个面向模型的工具：

- cross_session_list — 活动会话的 id、status，以及（当标题 seam 已组合时）title。
- cross_session_send — 将文本消息投递到目标的 inbox 并唤醒其 agent loop。模式：followup（默认）开始或继续一个 turn；steer 在下一个 step 边界投递并同样唤醒目标；inject 仅排队而不唤醒。
- cross_session_emit — 向目标的持久日志追加 cross-session/event。该会话上的每个 session/event 监听器都会同步触发；不会启动模型 turn。

投递语义

cross_session_send 复用 agent inbox seam（来自 @deepseek-ai/dsh-agent 的 Agent.followup / steer / inject）：目标会话持久记录 agent/inbox/spliced，触发实时的 agent/inbox/inserted 与 session/event 分发，并且 — 对于 followup 和 steer — 目标 loop 会被唤醒并将消息作为 turn 处理。投递的消息带有 source: { kind: 'plugin', plugin: 'cross-session', form: 'relay' } 和 [cross-session message from ] 文本前缀，因此目标记录中会保留发送者信息。发送者是工具调用所属的 agent；在 agent 边界之外则为 'unknown'。

工具调用通过 ctx.agents.get(id) 解析目标；进程内不活动的会话（未加载，或位于其他进程）会被拒绝并返回 ok: false 及活动会话 id 列表。

导出形态

该包导出一个函数插件（name / inject / apply，无默认导出），并在 ./invariant 下导出 cross-session/event 持久事件不变量伴侣：它会拒绝任何 from 或 kind 缺失或为空字符串的 cross-session/event 记录，在追加边界立即失败，而不是让畸形记录污染持久日志。cross-session/event 事件类型在 src/types.ts 中通过 SessionEventMap 声明合并声明。

安装使用

在 DSH 部署中安装该包，然后向其 cordis.yml 添加一行：

npm install @vongostev/dsh-cross-session@next

- name: '@vongostev/dsh-cross-session'

该行组合三个 cross_session_ 工具。插件需要标准 harness seam ctx.tools 与 ctx.agents（任何 DSH 部署都已组合）及其 @deepseek-ai/ peer 依赖。

cross-session/event 不变量伴侣是独立模块，仅在部署同时组合不变量注册表时挂载：

- name: '@deepseek-ai/dsh-invariants'
- name: '@vongostev/dsh-cross-session/invariant'

从源码检出独立构建与测试：

npm install
npm test          # vitest run：单元 + 不变量 + 真实 Loader 组合
npm run typecheck
npm run build     # tsc 输出 lib/index.js、lib/invariant.js、lib/types/*/.d.ts

依赖状态

撰写时已对照 npm 注册表核查：所有 @deepseek-ai/ 依赖均已发布，本仓库的 npm install 可从公共注册表解析完整依赖图：

| 包 | 版本范围 |
| --- | --- |
| @deepseek-ai/cordis | ^4.0.1 |
| @deepseek-ai/cordis-plugin-loader | ^1.0.2 |
| @deepseek-ai/cordis-plugin-include | ^1.0.6 |
| @deepseek-ai/dsh-agent | ^0.1.0-rc.8 |
| @deepseek-ai/dsh-invariants | ^0.1.0-rc.8 |
| @deepseek-ai/dsh-llm | ^0.1.0-rc.8 |
| @deepseek-ai/dsh-session | ^0.1.0-rc.8 |
| @deepseek-ai/dsh-session-title | ^0.1.0-rc.8 |
| @deepseek-ai/dsh-system-prompt | ^0.1.0-rc.8 |
| @deepseek-ai/dsh-tools | ^0.1.0-rc.8 |

本包已以 0.1.0-rc.8 发布在 npm 的 next dist-tag 下（latest 目前指向同一构建）；在 0.1.0-rc.x 系列为当前版本期间，请显式使用 @next 安装。@deepseek-ai/ peer 依赖发布在同一 0.1.0-rc.x 系列，但部分包的 latest tag 滞后，因此请对齐上述 peer 范围，而不是依赖默认的 latest tag。

Model Experience

工具 schema

模型看到的内容

模型看到生成的跨会话工具 schema；描述在 src/index.ts 中原样固定：

cross_session_list 描述

List the live DSH sessions in this process (id, status, title). Use the returned ids with cross_session_send and cross_session_emit.

cross_session_send 描述

Deliver a text message from the current session to another live DSH session and wake its event processing: the message enters the target inbox (durable agent/inbox/spliced event, live agent/inbox/inserted and session/event dispatch) and the target agent loop starts a turn that claims and processes it. mode=followup (default) starts or continues a turn; mode=steer delivers at the next step boundary and also wakes the target; mode=inject only queues the message without waking.

cross_session_emit 描述

Append a custom cross-session/event to another live DSH session's durable log. Every session/event listener on that session fires synchronously for the append; no model turn is started. Use it to trigger plugin-side event processing in the target session without delivering a model-visible message.

Token 影响

固定且有条件：只要工具注册表已组合，三个工具描述就会出现在 system prompt 中。每次调用都会将参数和 JSON 结果追加到调用方会话的日志；当目标 loop 处理 followup/steer 投递时，投递的文本也会作为 user/message 进入目标会话的日志。

KV Cache 影响

仅追加：工具描述在请求间保持稳定；每次调用都会向调用方会话日志（cross_session_send 还会向目标会话日志）追加新事件，因此反复的跨会话活动会增长各会话的前缀，不会使两侧此前可复用的请求前缀失效。

Known Limitations and Deferred Work

- 持久事件可读性耦合 — cross-session/event 是仅含此包上游的 harness 构建才认识的自定义事件类型。KNOWN_SESSION_EVENT_TYPES 中缺少该类型的构建会拒绝包含它的日志，除非事件标记为 ignorable；本包未设置该标记（与上游一致），因此当前 harness 构建仍可读取该事件。
- 仅限活动会话 — 投递和 emit 要求目标是在当前进程中活动的 agent（ctx.agents.get）。未加载的持久化会话不可达，必须先恢复才能接收消息；其他进程或部署中的会话永远不可达。
- 无处理回执 — cross_session_send 只确认消息已插入 inbox，不确认目标模型实际处理了消息。inject 模式按设计仅排队而不唤醒。