dsh-session-bridge 0.2.0

package/README.md

@@ -0,0 +1,219 @@
+# dsh-session-bridge — 会话桥 (Session bridge)
+
+A [DSH](https://www.deepseek.com) plugin that lets the current agent drive
+other real DSH sessions directly from a prompt — create sessions, send
+messages to any session, wait for and read replies, resume offline sessions,
+and find sessions across workspaces. On top of that it can **monitor and
+schedule** a main task (watch its progress, nudge or correct its direction,
+and stop it), and **archive** sessions the same way the DSH sidebar's Archive
+action does.
+
+> 中文文档见 [README.zh.md](./README.zh.md).
+
+## What it does
+
+- **Create real DSH sessions.** `session_bridge_create` makes a new main
+  session (top-level UI session) in the current workspace, or in another
+  workspace when you pass `workspaceId` / `cwd`. It can send one first prompt
+  and optionally block until the first reply. Provider / model / reasoning
+  effort are inherited from the calling session by default.
+- **Send messages to any session.** `session_bridge_send` appends a turn
+  (`mode=queue`) or injects steering into the running step (`mode=steer`), and
+  can optionally wait for the next reply.
+- **Wait for a reply.** `session_bridge_wait` blocks until a new text assistant
+  reply appears after a given seq; with `requireTurnEnd` it also waits for the
+  turn to settle. Timeout / abort return the partial result rather than
+  throwing.
+- **Read any session.** `session_bridge_read` folds a session's event log into
+  readable rows — live or offline (from persistence) — with `sinceSeq` paging,
+  role filtering, and a `limit` (default 20, max 100).
+- **Resume offline sessions.** `session_bridge_resume` brings a persisted
+  session back online (idempotent); it can also override provider / model.
+- **Find sessions.** `session_bridge_find` matches by title, id, workspace, or
+  directory across all workspaces, returning live/running state, title, and
+  working directory. Bridge-registered titles act as aliases.
+- **Monitor and schedule a main task.** `session_bridge_status` reads a
+  session's real-time progress (running/idle, open turn, time since the last
+  event for stall detection, pending work, latest reply). `session_bridge_cancel`
+  stops a running session. `session_bridge_monitor_start` runs a **background
+  watchdog loop** that polls the task, nudges it when it stalls, corrects it
+  when it drifts, terminates it after it stays stuck, and wraps up when it
+  finishes.
+- **Archive sessions.** `session_bridge_archive` adds a session to the DSH
+  workspace archive set (hidden from every grouping surface, history and
+  workspace position preserved). `session_bridge_archived` lists the archive
+  set, optionally resolving titles.
+
+## Monitoring worker
+
+`session_bridge_monitor_start` installs a timer-driven loop. Every poll it
+**observes → judges → schedules → logs** the target session:
+
+| Observation | Action |
+|---|---|
+| A `doneKeywords` string appears in the reply and the session is idle | Wrap up and stop the watchdog (log `DONE`) |
+| Idle with no pending work | Wrap up (settled) — no pointless nudging / cancelling |
+| `running` and no event for more than `stalledMs` | Record a stall → `steer` a nudge (with `useLlm`, judge `offtrack`/`stuck` first) |
+| Stall repeats ≥ `maxStuckCycles` | `cancel` the session |
+| Making progress | Reset the stall counter (steady) |
+
+The watchdog only treats **running** sessions as stalled, so a finished or idle
+task is wrapped up rather than nudged forever. Logs go to
+`~/.dsh/super-injector/dsh-session-bridge-monitor.log` (overridable).
+
+Control it with `session_bridge_monitor_start` / `_stop` / `_list`.
+
+## Requirements
+
+- [Node.js](https://nodejs.org) ≥ 20
+- [pnpm](https://pnpm.io)
+- DSH ≥ `0.1.0-rc.6`
+
+## Build
+
+```bash
+# type-check + bundle the host build + pack a tgz (DSH_CHECKOUT points at the dsh source checkout)
+bash scripts/build.sh && npm run build:client
+
+# via the injector toolchain
+dev_build_plugin dsh-session-bridge
+```
+
+`build.sh` type-links against a local DSH checkout and is only for local dev.
+The GitHub Actions CI (`ci.yml`) instead resolves the `@deepseek-ai/dsh-*`
+prereleases from the registry — pinned to the `0.1.2-alpha.2` line, which is
+the DSH API surface this code targets — then runs `pnpm typecheck` and
+`pnpm build:client` (the self-contained `tsdown` bundle). Bump that pin
+together with the code when you migrate to a newer DSH API.
+
+## Deploy
+
+DSH web loads external plugins from the active profile. This package is a
+**bundle**: its `package.json` declares `dsh.bundle.patch` →
+[`cordis.patch.yml`](./cordis.patch.yml), whose `insert` row mounts the plugin.
+That declaration is what lets `dsh plugin add` install the package *and*
+activate it in one step.
+
+### Install from npm
+
+The package is published to [npmjs.com](https://www.npmjs.com/package/dsh-session-bridge).
+Releases are cut on a `v*` git tag by the `publish.yml` GitHub Actions workflow;
+`package.json` and `dsh.plugin.json` versions are synced to that tag before
+publishing.
+
+```bash
+npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-session-bridge
+```
+
+pnpm installs the published tarball and runs its `prepare` script (`tsdown`) to
+ensure `lib/` is present, then `dsh` activates the bundle.
+
+### Install from GitHub
+
+```bash
+npx -p @deepseek-ai/dsh dsh plugin --profile web add github:heartmove/dsh-session-bridge
+```
+
+`dsh plugin` forwards to pnpm inside `~/.dsh/profiles/web/`, then reconciles the
+bundle into the profile's `dsh.profile.bundles` layer list. A git install
+fetches sources, so pnpm runs the package's `prepare` script (`tsdown`) to build
+`lib/` from `src/` after checkout.
+
+pnpm ≥ 10 refuses to run a git dependency's `prepare` script until it is
+allowlisted, so the first `add` fails with an "Ignored build scripts" hint. Copy
+the exact package key pnpm printed into the profile's `pnpm-workspace.yaml`
+(`~/.dsh/profiles/web/pnpm-workspace.yaml`):
+
+```yaml
+allowBuilds:
+  dsh-session-bridge: true
+```
+
+then re-run the `add`. That allowance means "run this package's code on my
+machine at install time" — only allow packages whose source you trust, and pin a
+commit (`github:heartmove/dsh-session-bridge#<sha>`) so a later push cannot
+silently change what runs.
+
+Restart `dsh web`, then hard-refresh the page (Ctrl/Cmd+Shift+R).
+
+### Install from a local checkout
+
+From the directory that contains this checkout:
+
+```bash
+npx -p @deepseek-ai/dsh dsh plugin --profile web add ./dsh-session-bridge
+```
+
+pnpm links the checkout and `dsh` activates the bundle the same way.
+
+### Manual link
+
+To manage the profile by hand, link the package and list it as a bundle in
+`~/.dsh/profiles/web/package.json` (the bundle's own `cordis.patch.yml` supplies
+the loader row, so no `insert` entry is needed):
+
+```json
+{
+  "dependencies": {
+    "dsh-session-bridge": "link:D:\\path\\to\\dsh-session-bridge"
+  },
+  "dsh": {
+    "profile": {
+      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-session-bridge"]
+    }
+  }
+}
+```
+
+(On POSIX systems use `link:/path/to/dsh-session-bridge`.) Then run `pnpm install`
+in the profile directory and restart `dsh web`.
+
+### Inject directly (dev)
+
+For fast iteration while developing the plugin, you can also load it directly
+through the injector toolchain (no bundle entry required):
+
+```bash
+dev_inject_plugin D:\code\dsh-session-bridge
+```
+
+Remove it with `dev_uninject_plugin dsh-session-bridge` (clears the injector
+registration and junction; not re-assembled on restart).
+
+## Usage
+
+| Tool | What it does |
+|---|---|
+| `session_bridge_create` | Create a main session (current or another workspace via `workspaceId` / `cwd`); optional first prompt + `waitForReply`. |
+| `session_bridge_send` | Send a message (`mode=queue`/`steer`); optional wait-for-reply. |
+| `session_bridge_wait` | Wait for a new text assistant reply after `sinceSeq`; optional `requireTurnEnd`. |
+| `session_bridge_read` | Read messages — live or offline; `sinceSeq` paging, `role` filter, `limit`. |
+| `session_bridge_resume` | Bring a persisted session back online (idempotent). |
+| `session_bridge_find` | Find sessions by title / id / workspace / directory across workspaces. |
+| `session_bridge_status` | Read a session's live progress (running, open turn, stall detection, pending work, latest reply). |
+| `session_bridge_cancel` | Stop a running session (abort active turn; clear queued/steering work unless `keepInbox`). |
+| `session_bridge_monitor_start` | Start a background watchdog on a main session (poll, nudge, correct, cancel, wrap up). |
+| `session_bridge_monitor_stop` | Stop a watchdog (keep the session itself running). |
+| `session_bridge_monitor_list` | List active watchdogs and their state. |
+| `session_bridge_archive` | Archive a session (hidden from groupings; history and position preserved). |
+| `session_bridge_archived` | List the archive set, optionally resolving titles. |
+
+All tools return lossless JSON; wait-style tools never throw on timeout — they
+return a `timedOut` / `aborted` flag.
+
+## Project layout
+
+```
+src/
+  index.ts    host plugin entry (registers the tools; mounts the monitor)
+  core.ts     shared host logic (create/send/wait/read/find, status snapshot, archive attach)
+  tools.ts    tool registrations (bridge + status/cancel + monitor + archive)
+  monitor.ts  the background watchdog loop (statusSnapshot + rules + optional LLM judge)
+  registry.ts bridge-side title/workspace registry (~/.dsh/session-bridge-registry.json)
+scripts/
+  build.sh    type-check + link types against the DSH checkout
+```
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,183 @@
+# dsh-session-bridge — 会话桥（Session bridge）
+
+一个 [DSH](https://www.deepseek.com) 插件：让当前 agent 能通过提示词驱动其它真实的 DSH 会话——
+创建主会话、向任意会话发消息、等待并读取回复、恢复离线会话、跨工作区按名称或 id 查找会话。
+在此之上，它还能**监控并调度**一个主任务（观察进度、卡住时催办、偏离时纠偏、必要时终止），
+以及像 DSH 侧边栏的 Archive 一样**归档**会话。
+
+> English docs: [README.md](./README.md).
+
+## 功能
+
+- **创建真实 DSH 会话。** `session_bridge_create` 在当前工作区创建新的主会话（顶层 UI 会话），
+  传 `workspaceId` / `cwd` 则跨工作区；可选发送首条 prompt 并阻塞等待首条回复。provider / model /
+  reasoning effort 默认继承调用会话。
+- **向任意会话发消息。** `session_bridge_send` 追加一轮（`mode=queue`）或向运行中的步骤注入
+  steering（`mode=steer`），可选等待下一条回复。
+- **等待回复。** `session_bridge_wait` 阻塞直至 `sinceSeq` 之后出现新的带文本 assistant 回复；
+  开 `requireTurnEnd` 则同时等待回合收尾。超时 / 中止返回部分结果，而非抛错。
+- **读取任意会话。** `session_bridge_read` 把会话事件日志折叠为可读行——live 或离线（持久化）均可；
+  支持 `sinceSeq` 分页、role 过滤、`limit`（默认 20，最大 100）。
+- **恢复离线会话。** `session_bridge_resume` 让持久化会话重新上线（幂等），可覆盖 provider / model。
+- **查找会话。** `session_bridge_find` 跨全部工作区按 标题 / id / workspace / 目录 匹配，返回
+  live/running 状态、标题、工作目录；bridge 登记的标题作为别名参与匹配。
+- **监控并调度主任务。** `session_bridge_status` 读取会话实时进度（running/idle、是否 `openTurn`、
+  距最近事件毫秒数做卡住检测、待处理消息、最新回复）；`session_bridge_cancel` 停止一个运行中的会话；
+  `session_bridge_monitor_start` 运行一个**后台守护循环**，轮询任务、卡住时催办、偏离时纠偏、
+  持续卡住则终止、完成即收尾。
+- **归档会话。** `session_bridge_archive` 把会话加入 DSH workspace 归档集合（从所有分组视图隐藏，
+  历史与位置保留）；`session_bridge_archived` 列出归档集合，可选解析标题。
+
+## 监控守护循环
+
+`session_bridge_monitor_start` 安装一个定时器驱动的循环。每轮对目标会话执行
+「观察 → 判定 → 调度 → 落日志」：
+
+| 判定 | 动作 |
+|---|---|
+| 回复命中 `doneKeywords` 且会话空闲 | 收尾并停止守护（日志 `DONE`） |
+| 空闲且无待处理 | 收尾（settled）——不无谓催办 / 取消 |
+| `running` 且距最近事件超过 `stalledMs` | 记一次卡住 → `steer` 催办（开 `useLlm` 时先判 `offtrack`/`stuck`） |
+| 连续卡住 ≥ `maxStuckCycles` | `cancel` 终止 |
+| 正常推进 | 重置卡住计数（steady） |
+
+守护只对 **running** 会话判定"卡住"，因此已完成/空闲的任务会被收尾而非无限催办。日志写入
+`~/.dsh/super-injector/dsh-session-bridge-monitor.log`（可用 `logFile` 覆盖）。
+
+用 `session_bridge_monitor_start` / `_stop` / `_list` 控制。
+
+## 环境要求
+
+- [Node.js](https://nodejs.org) ≥ 20
+- [pnpm](https://pnpm.io)
+- DSH ≥ `0.1.0-rc.6`
+
+## 构建
+
+```bash
+# 类型检查 + 打包 host bundle + 生成 tgz（DSH_CHECKOUT 指向 dsh 源码 checkout）
+bash scripts/build.sh && npm run build:client
+
+# 或经注入器工具链
+dev_build_plugin dsh-session-bridge
+```
+
+## 部署
+
+DSH web 从活动 profile 加载外部插件。本包是一个 **bundle**：`package.json` 声明了
+`dsh.bundle.patch` → [`cordis.patch.yml`](./cordis.patch.yml)，其 `insert` 行挂载插件。
+正是这一声明让 `dsh plugin add` 能**一步安装并激活**本包。
+
+### 从 npm 安装
+
+本包已发布到 [npmjs.com](https://www.npmjs.com/package/dsh-session-bridge)。
+发布由 `publish.yml` GitHub Actions 工作流在 `v*` 标签触发；发布前会把
+`package.json` 与 `dsh.plugin.json` 的版本同步到该标签。
+
+```bash
+npx -p @deepseek-ai/dsh dsh plugin --profile web add dsh-session-bridge
+```
+
+pnpm 会安装发布的 tarball 并运行其 `prepare` 脚本（`tsdown`）以确保 `lib/` 就绪，
+随后 `dsh` 激活该 bundle。
+
+### 从 GitHub 安装
+
+```bash
+npx -p @deepseek-ai/dsh dsh plugin --profile web add github:heartmove/dsh-session-bridge
+```
+
+`dsh plugin` 在 `~/.dsh/profiles/web/` 内转发给 pnpm，然后把本 bundle 归并到 profile 的
+`dsh.profile.bundles` 层列表。git 安装会拉取源码，因此 pnpm 会在 checkout 后运行本包的
+`prepare` 脚本（`tsdown`）从 `src/` 构建 `lib/`。
+
+pnpm ≥ 10 默认拒绝运行 git 依赖的 `prepare` 脚本，首次 `add` 会报 "Ignored build scripts" 提示。
+把 pnpm 打印出的包名复制到 profile 的 `pnpm-workspace.yaml`
+（`~/.dsh/profiles/web/pnpm-workspace.yaml`）：
+
+```yaml
+allowBuilds:
+  dsh-session-bridge: true
+```
+
+然后重新运行 `add`。该放行表示"在安装时运行这个包的代码"——只放行源码可信的包，并锁定 commit
+（`github:heartmove/dsh-session-bridge#<sha>`）以避免后续推送静默改变运行内容。
+
+之后重启 `dsh web`，并强制刷新页面（Ctrl/Cmd+Shift+R）。
+
+### 从本地 checkout 安装
+
+在包含本 checkout 的目录下：
+
+```bash
+npx -p @deepseek-ai/dsh dsh plugin --profile web add ./dsh-session-bridge
+```
+
+pnpm 链接该 checkout，`dsh` 以同样的方式激活 bundle。
+
+### 手动 link
+
+想手动管理 profile 时，把本包链接并列入 `~/.dsh/profiles/web/package.json` 的 bundles
+（bundle 自带的 `cordis.patch.yml` 提供 loader 行，无需额外的 `insert` 条目）：
+
+```json
+{
+  "dependencies": {
+    "dsh-session-bridge": "link:D:\\path\\to\\dsh-session-bridge"
+  },
+  "dsh": {
+    "profile": {
+      "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-session-bridge"]
+    }
+  }
+}
+```
+
+（POSIX 系统用 `link:/path/to/dsh-session-bridge`。）然后在 profile 目录运行 `pnpm install` 并重启 `dsh web`。
+
+### 直接注入（开发用）
+
+开发调试阶段也可经注入器工具链直接加载（无需 bundle 条目）：
+
+```bash
+dev_inject_plugin D:\code\dsh-session-bridge
+```
+
+卸载用 `dev_uninject_plugin dsh-session-bridge`（清除注入器注册与 junction；重启不再自动装配）。
+
+## 工具清单
+
+| 工具 | 作用 |
+|---|---|
+| `session_bridge_create` | 创建主会话（当前或其它工作区，经 `workspaceId` / `cwd`）；可选首条 prompt + `waitForReply`。 |
+| `session_bridge_send` | 发消息（`mode=queue`/`steer`）；可选等待回复。 |
+| `session_bridge_wait` | 等待 `sinceSeq` 之后新的带文本 assistant 回复；可选 `requireTurnEnd`。 |
+| `session_bridge_read` | 读取消息 —— live 或离线；`sinceSeq` 分页、`role` 过滤、`limit`。 |
+| `session_bridge_resume` | 让持久化会话重新上线（幂等）。 |
+| `session_bridge_find` | 跨工作区按 标题 / id / workspace / 目录 查找会话。 |
+| `session_bridge_status` | 读取会话实时进度（running、openTurn、卡住检测、待处理、最新回复）。 |
+| `session_bridge_cancel` | 停止运行中的会话（中止活动 turn；`keepInbox` 保留排队/steering 输入）。 |
+| `session_bridge_monitor_start` | 对一个主会话启动后台守护（轮询、催办、纠偏、终止、收尾）。 |
+| `session_bridge_monitor_stop` | 停止守护（会话本身不终止）。 |
+| `session_bridge_monitor_list` | 列出活动守护及其状态。 |
+| `session_bridge_archive` | 归档会话（从分组隐藏；历史与位置保留）。 |
+| `session_bridge_archived` | 列出归档集合，可选解析标题。 |
+
+所有工具输出 lossless JSON；等待类工具超时不抛错，返回 `timedOut` / `aborted` 标记。
+
+## 项目结构
+
+```
+src/
+  index.ts    host 插件入口（注册工具；挂载监控）
+  core.ts     共享 host 逻辑（create/send/wait/read/find、status 快照、archive 记账）
+  tools.ts    工具注册（bridge + status/cancel + monitor + archive）
+  monitor.ts  后台守护循环（statusSnapshot + 规则 + 可选 LLM 判定）
+  registry.ts 桥侧标题/workspace 登记表（~/.dsh/session-bridge-registry.json）
+scripts/
+  build.sh    类型检查 + 链接 DSH checkout 类型
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Bundle patch layer for dsh-session-bridge. This file is referenced by the
+# package.json `dsh.bundle.patch` declaration, so `dsh plugin add` reconciles
+# this package into the profile's bundle list and this row mounts the plugin.
+# `name` is the package name: the Loader resolves it from the profile's
+# node_modules (where pnpm installs the checkout / git dependency).
+- insert:
+    - id: dsh-session-bridge
+      name: dsh-session-bridge

package/dsh.plugin.json

@@ -0,0 +1,27 @@
+{
+  "id": "dsh-external/dsh-session-bridge",
+  "version": "0.2.0",
+  "main": "./lib/index.js",
+  "description": "会话桥：创建主会话 / 向任意会话发消息 / 等待回复 / 读取消息 / 按名或 id 查找会话（支持跨工作区）；另含监控/调度主任务与归档会话。",
+  "engines": {
+    "dsh": "^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0"
+  },
+  "contributes": {
+    "tools": [
+      "session_bridge_create",
+      "session_bridge_send",
+      "session_bridge_resume",
+      "session_bridge_wait",
+      "session_bridge_read",
+      "session_bridge_find",
+      "session_bridge_status",
+      "session_bridge_cancel",
+      "session_bridge_monitor_start",
+      "session_bridge_monitor_stop",
+      "session_bridge_monitor_list",
+      "session_bridge_archive",
+      "session_bridge_archived"
+    ],
+    "skills": []
+  }
+}