@vongostev/dsh-cross-session

English | 中文

Cross-session messaging between live DSH sessions in one process: one session sends a text message to another and triggers its event processing, or appends a custom event to its durable log.

What it does

The plugin registers three model-facing tools on ctx.tools:

• cross_session_list — live sessions with id, status, and (when the title seam is composed) title.
• cross_session_send — delivers a text message into the target's inbox and wakes its agent loop. Modes: followup (default) starts or continues a turn; steer delivers at the next step boundary and also wakes the target; inject only queues the message without waking.
• cross_session_emit — appends a cross-session/event to the target's durable log. Every session/event listener on that session fires synchronously; no model turn starts.

Delivery semantics

cross_session_send reuses the agent inbox seam (Agent.followup / steer / inject from @deepseek-ai/dsh-agent): the target session durably logs agent/inbox/spliced, fires live agent/inbox/inserted and session/event dispatch, and — for followup and steer — the target loop wakes and processes the message as a turn. Delivered messages carry source: { kind: 'plugin', plugin: 'cross-session', form: 'relay' } and a [cross-session message from <sender>] text prefix, so the target transcript records who sent the message. The sender is the owning agent of the tool call, or 'unknown' outside an agent boundary.

A tool call resolves its target through ctx.agents.get(id); a session that is not live in the process (not loaded, or in another process) is rejected with ok: false plus the live session ids.

Export shape

The package exports a function plugin (name / inject / apply, no default export) and, under ./invariant, the durable cross-session/event invariant companion: it rejects any cross-session/event record whose from or kind is missing or empty, failing loud at the append boundary instead of letting a malformed record poison the durable log. The cross-session/event event type is declared in src/types.ts through SessionEventMap declaration merging.

Consumption

Install the package in a DSH deployment, then add a row to its cordis.yml:

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

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

The row composes the three cross_session_* tools. The plugin requires the standard harness seams ctx.tools and ctx.agents (already composed by every DSH deployment) and their @deepseek-ai/* peer dependencies.

The cross-session/event invariant companion is a separate module and mounts only when the deployment also composes the invariant registry:

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

From a source checkout, build and test the package standalone:

npm install
npm test          # vitest run: unit + invariant + real Loader composition
npm run typecheck
npm run build     # tsc emits lib/index.js, lib/invariant.js, lib/types/**/*.d.ts

Dependency status

Checked against the npm registry at the time of writing, every @deepseek-ai/* dependency is published, and npm install in this repository resolves the whole dependency graph from the public registry:

This package is published under npm's next dist-tag as 0.1.0-rc.8 (latest currently points at the same build); install it with @next while the 0.1.0-rc.x line is current. The @deepseek-ai/* peer dependencies are published on the same 0.1.0-rc.x line, but their latest tags lag for several packages, so align the peer ranges above rather than rely on the default latest tag.

Model Experience

Tool schemas

What the model sees

The model sees the generated cross-session tool schemas; their descriptions are pinned verbatim in src/index.ts:

cross_session_list description

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 description

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 description

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 effect

Fixed, conditional: the three tool descriptions ride the system prompt whenever the tools registry is composed. Each call contributes its arguments and its JSON result to the calling session's log; delivered text also enters the target session's log as a user/message when the target loop processes a followup/steer delivery.

KV Cache effect

Append-only: the tool descriptions are stable across requests, and each call appends new events to the calling and (for cross_session_send) target session logs, so repeated cross-session activity grows the per-session prefixes and does not invalidate previously reusable request prefixes on either side.

Known Limitations and Deferred Work

• Durable-event readability coupling — cross-session/event is a custom event type known only to harness builds that include this package's upstream. A build whose KNOWN_SESSION_EVENT_TYPES lacks the type refuses logs carrying it unless the event is marked ignorable; this package does not set that marker (matching upstream), so the event remains readable by current harness builds.
• Live sessions only — delivery and emit require a live agent in the current process (ctx.agents.get). A persisted session that is not loaded is unreachable and must be resumed before it can receive messages; sessions in other processes or deployments are never reachable.
• No processing receipt — cross_session_send confirms insertion into the target inbox, not that the target model actually processed the message. inject mode queues without waking by design.