dsh-session-collaboration

Readme

# dsh-session-collaboration

English | [中文](README.zh.md)

An installable [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) bundle for explicit, bidirectional collaboration between sessions. It adds a `session_delegate` model tool, a host runtime that uses `Agent.steer()` to insert relay context into the target's next step, and a Web card that records the target session and opens it in the current view.

## Install

With a published package:

```sh
dsh plugin --profile web add dsh-session-collaboration
```

From GitHub, pin a commit when installing source:

```sh
dsh plugin --profile web add github:w210548735-art/dsh-session-collaboration#<commit>
```

GitHub installs run the package's `prepare` build. pnpm may require an explicit build permission in the profile's `pnpm-workspace.yaml`:

```yaml
allowBuilds:
  dsh-session-collaboration: true
```

Allowing a GitHub package to build executes its source during installation. Use a pinned commit and allow only source you trust. Published npm packages and local tarballs contain `lib/` and do not require this build permission.

The bundle adds its own patch layer. It does not require edits to the profile's `cordis.patch.yml`; user patches can override `allowCrossWorkspace` and `waitTimeoutMs` because the bundle patch is applied before the profile patch.

## Behavior

The model can call `session_delegate` only with an explicit `session_id` supplied by the user or synchronized by a previous collaboration relay. The relay records both the sender and target session ids, so the target can send a reverse relay without guessing the caller.

`session_delegate` uses `Agent.steer()` for delivery. The message is admitted through the target's next-step steering path and does not enter the ordinary FIFO queue. The target sees the relay as model context, not as a new human input, so the sender does not need to type the task again in another input box.

`wait` defaults to `true`. When it is enabled, the tool waits for the target turn, extracts its assistant text, injects a reply relay into the caller session, and returns a receipt. Set `wait: false` for a one-way or reverse message when the other session is already waiting; a cold target must use `wait: true` so the resumed Agent can be released safely.

The Web card shows the target id and task, uses the label “Jump to target session”, and switches the current view through the existing session service. The durable tool-call record remains in the caller's conversation, and the target reply is logged as a collaboration relay.

## Configuration

The bundle patch defaults to:

```yaml
allowCrossWorkspace: false
waitTimeoutMs: 120000
```

`allowCrossWorkspace` permits a target in another working directory only when the target id was explicitly provided by a user message or a trusted reverse relay. `waitTimeoutMs` bounds one awaited target turn and must be a positive safe integer.

## Failures and limitations

- A session cannot delegate to itself, and an unknown or unavailable target returns a typed collaboration error.
- Only one reply-waiting collaboration may target a given session at a time; use `wait: false` for the reverse leg of a two-sided exchange.
- A target reply is collected from assistant text blocks. A turn that produces no text reply is reported as `TARGET_REPLY_MISSING`.
- Cross-workspace delivery is disabled by default and requires both the deployment setting and explicit target authorization.
- The bundle does not discover sessions by content or title. The caller must supply an opaque session id.
- The card is available in the Web profile; the Host service and model tool also work in headless compositions that provide the required DSH services.

## Model Experience

### `session_delegate` request context and condition

#### What the model sees

The tool schema exposes `session_id`, `prompt`, and optional `wait`. The system instruction explains that the target receives inserted model context, that both session ids are synchronized, and that a waited reply returns through the caller's context.

#### Token effect

The tool instruction adds a fixed prompt section when the tool is enabled. Each tool call adds its serialized arguments and receipt to the normal tool transcript; an awaited reply adds the target's assistant text as a logged collaboration relay.

#### KV Cache effect

The fixed instruction is prefix-stable after the collaboration tool is mounted. Individual calls and returned replies append after the existing conversation prefix, so they do not replace earlier request tokens; a newly mounted or disabled tool changes the prompt prefix and can invalidate reuse.

## Development

```sh
pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm pack --dry-run
```

The package follows the DSH [plugin publishing guide](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md): the root manifest declares `dsh.bundle`, the patch references package entry points, `prepare` builds GitHub checkouts, and `files` contains only runnable artifacts and documentation.

## License

[MIT](LICENSE)