opencode-session-spawn 2.1.0 → 2.2.0

package/README.md

@@ -1,14 +1,15 @@
 # opencode-session-spawn
 
-opencode 插件：**会话生成原语**。只做一件事——**创建一个新的顶层会话，并把起始语句注入为该会话的首条消息**。
+opencode 插件：**会话生成原语**。做两件事——**创建一个新的顶层会话，并把起始语句注入为该会话首条消息**；以及**子会话反向通知父会话**（`notify_parent`：注入一条 `[relay]` 消息并唤醒父会话）。
 
-它的用途是**无人值守长任务编排**：当一条任务超出单会话上下文时，当前会话的模型可以在需要时自行生成一段交接语句、调用工具开出一个新会话继续，新会话拿到语句立即开跑。插件不落文书、不读文书、不追踪链、无状态文件——需要交接文书时，把「读取某份文书路径」等引导写进起始语句即可，与其他工具天然兼容。
+它的用途是**无人值守长任务编排**：当一条任务超出单会话上下文时，当前会话的模型可以在需要时自行生成一段交接语句、调用工具开出一个新会话继续，新会话拿到语句立即开跑；子会话完成 / 受阻时可用 `notify_parent` 回调 spawn 它的会话。插件不落文书、不读文书、不追踪链、无状态文件——需要交接文书时，把「读取某份文书路径」等引导写进起始语句即可，与其他工具天然兼容。
 
-## 两个入口（共用同一实现）
+## 入口与工具
 
-| 入口 | 用法 | 谁触发 |
+| 入口 / 工具 | 用法 | 谁触发 |
 |------|------|--------|
 | 工具 `spawn_session` | `spawn_session({ prompt, title?, agent?, directory? })` | **模型自主调用**（打通无人值守） |
+| 工具 `notify_parent` | `notify_parent({ text })` | **子会话模型自主调用**（完成 / 受阻时回调父会话） |
 | 命令 | `@spawn [--agent <名称>] [--title <标题>] <起始语句>`（兼容 `@relay spawn`） | 人工触发 |
 
 参数 / 行为：
@@ -17,20 +18,26 @@ opencode 插件：**会话生成原语**。只做一件事——**创建一个
 - `title`（可选）：新会话标题。缺省取 `prompt` 首行（清洗非法字符、截断 60）。
 - `agent`（可选，工具参数）：新会话以某 agent/模式启动（如 `leader`）。仅在传了非空白值时透传，交服务端校验。
 - `directory`（可选，工具参数）：新会话绑定的项目目录（如 `D:\dev\bbcare`）。仅在传了非空白值时透传，交服务端校验。
+- `parentID`（自动，非参数）：`spawn_session` 自动把调用者会话 id 写入新会话 `parentID`（`context.sessionID` 非空白时）；命令 `@spawn` 无会话上下文，不带 `parentID`。
 - 命令 flag 说明：`--agent` / `--title` 值均为**单个 token**（不处理引号/空格）；仅解析命令后**前导** flag，起始语句内部再出现的 `--xxx` 原样保留；flag 缺值或起始语句为空 → warning toast 且不建会话。`--title` 优先于起始语句首行。
-- 内部调用：`client.session.create({ body: { title }, query: { directory } })` → `client.session.promptAsync({ path: { id }, body: { agent, parts: [{ type: "text", text: prompt }] } })`；`agent` / `directory` 未传时不出现对应键。
+- 内部调用（spawn）：`client.session.create({ body: { title, parentID }, query: { directory } })` → `client.session.promptAsync({ path: { id }, body: { agent, parts: [{ type: "text", text: prompt }] } })`；`agent` / `directory` / `parentID` 未传时不出现对应键。
+- `notify_parent` 行为：仅能通知**父会话**（不提供任意 session id 参数）；`client.session.get` 解析自身 `parentID` 后，向父会话注入 `[relay] <text>` 并唤醒它；父会话以服务端默认模式（`build`）被唤醒；空文本 / 无父会话 / 读取或注入失败 → 返回错误文本（不抛）；无重试 / 队列 / 追踪（保持无状态原语）。
 - 优先 `promptAsync`（异步 fire-and-forget，**不阻塞父会话**）；缺失则回退同步 `prompt`。
 - create 失败 → 不建会话；create 成功但注入失败 → **保留已建会话**并提示 id，不产生重复会话。
 
 ## 安装（部署到桌面版）
 
-桌面版从用户配置目录加载活插件：
+现有部署形态：公共层配置 `share/opencode.json`（挂载到项目内即 `.opencode/opencode.json`）的 `plugin` 数组注册 **npm 包名**：
 
-```bash
-cp index.js package.json "$HOME/.config/opencode/plugins/session-relay/"
+```jsonc
+{
+  "plugin": ["opencode-session-spawn"]
+}
 ```
 
-在全局 `opencode.jsonc` 的 `plugin` 数组注册 `./plugins/session-relay`，重启桌面版生效。
+opencode 启动时自动把最新发布安装到包缓存 `~/.cache/opencode/packages/opencode-session-spawn/`（活实例为其中的 `node_modules/opencode-session-spawn/index.js`），**重启桌面版生效**。发布新版本后重启即自动更新；若缓存未刷新，删除 `~/.cache/opencode/packages/opencode-session-spawn@latest` 后重启强制重装。
+
+> 旧的本地目录注册写法（如 `./plugins/session-relay/`）已作废；开发与生产验证统一走 `test/test.mjs` + `RELAY_MAIN`（见下节）。
 
 ## 编排示例
 
@@ -53,19 +60,27 @@ E:\\proj\\handoff\\migration-3.md
 @spawn --agent leader --title "[P1-10] sprint" 读取 handoff/migration-3.md 后继续迁移任务
 ```
 
+父子回复约定（防环路）：父会话在起始语句里要求「子会话收尾 / 受阻时调用 `notify_parent`」；子会话执行：
+
+```
+notify_parent({ text: "P1-10 已完成，验收报告见 runs/P1-10-acceptance.md" })
+```
+
+父会话会收到一条 `[relay] …` 消息并以服务端默认模式被唤醒；收到通知后按需行动，**不要自动回发通知**（`notify_parent` 只向父会话发送，避免环路）。
+
 ## 开发与测试
 
 ```bash
 npm install          # 安装 devDependency @opencode-ai/plugin（唯一依赖，仅测试用）
-node test/test.mjs   # 23 用例 / 62 断言
+node test/test.mjs   # 34 用例 / 86 断言
 ```
 
-- `test/test.mjs` 默认经相对路径 `../index.js` 测项目版；环境变量 `RELAY_MAIN` 覆盖为其他路径（如生产活实例）。生产版从 `.config/opencode/node_modules` 解析 `@opencode-ai/plugin`。
+- `test/test.mjs` 默认经相对路径 `../index.js` 测项目版；环境变量 `RELAY_MAIN` 覆盖为其他路径（tarball 解包版 / 包缓存活实例）。`RELAY_MAIN` 目标须能向上解析到 `@opencode-ai/plugin`（解包放项目内即可）。
 - 以尾部 `==== 结果: N 通过, 0 失败 ====` 为准。
 
 ## 发布
 
-`index.js` + `package.json` 成对同步生产 → `RELAY_MAIN=<生产路径> node test/test.mjs` 回归全绿 → 重启桌面版实测 → commit → push → `npm publish`（不打 git tag；发布前 `npm whoami` 确认登录态，凭据不入库）。详见 `AGENTS.md`。
+bump 版本号（`package.json` 与 `index.js` 头注释同步）→ `node test/test.mjs` 全绿 → `npm pack` 解包核对哈希 + `RELAY_MAIN` 回归全绿 → commit → push → `npm publish`（不打 git tag；先 `npm whoami` 确认登录态，凭据不入库）→ 重启桌面版实测 `@spawn` / `spawn_session`；实测不过修复补丁重发。详见 `AGENTS.md`。
 
 ## 历史
 

package/index.js

@@ -1,19 +1,23 @@
 import { tool } from "@opencode-ai/plugin/tool";
 
 /**
- * session-spawn —— 会话生成原语（v2.1.0，2026-09-12 起支持 agent/directory）
+ * session-spawn —— 会话生成原语（v2.2.0，2026-09-15 起支持 parentID / notify_parent 反向通知）
  *
- * 只做一件事：创建一个新的顶层会话，并把起始语句注入为该会话首条消息。
- *   create: client.session.create({ body: { title }, query: { directory } })
- *   inject: client.session.promptAsync({ path: { id }, body: { agent, parts: [{ type: "text", text }] } })
- *   （agent / directory 均可选，仅在显式传入且非空白时透传；不做校验，交服务端）
+ * 只做两件事：
+ *   1. 创建一个新的顶层会话，并把起始语句注入为该会话首条消息。
+ *      create: client.session.create({ body: { title, parentID? }, query: { directory } })
+ *      inject: client.session.promptAsync({ path: { id }, body: { agent, parts: [{ type: "text", text }] } })
+ *      （agent / directory / parentID 均可选，仅在显式传入且非空白时透传；不做校验，交服务端）
+ *   2. 子会话向父会话注入一条 [relay] 消息并唤醒它（工具 notify_parent；仅父会话，无任意会话注入）。
  *
  * 设计约束（用户定稿）：
- *   - 插件只负责「建会话 + 注入语句」，不落文书、不读文书、不追踪链、无状态文件。
+ *   - 插件只负责「建会话 + 注入语句 + 父会话通知」，不落文书、不读文书、不追踪链、无状态文件。
  *   - 编排中若需交接文书，由调用方把「读取文书路径」等引导写进起始语句即可（与其他工具天然兼容）。
  *   - 优先 promptAsync（异步 fire-and-forget，不阻塞父会话）；缺失则回退同步 prompt。
  *   - 两个入口共用同一 spawn()：① 工具 spawn_session（模型自主触发，打通无人值守）
  *                                        ② 命令 @spawn / @relay spawn（人工触发）。
+ *   - spawn_session 自动把调用者会话 id 写入新会话 parentID；notify_parent 只沿 parentID 上行，
+ *     不提供任意 session id 参数、无重试 / 队列 / 追踪（保持无状态原语）。
  *
  * 历史：本仓库前身 session-relay 的接力链、两阶段文书、空闲事件驱动、哨兵等机制已全部移除。
  */
@@ -87,7 +91,7 @@ export const SessionSpawn = async (ctx) => {
   };
 
   // 核心：建新会话 + 注入起始语句。
-  // opts.agent / opts.directory 可选；仅在非空白时透传（不做校验，交服务端）。
+  // opts.agent / opts.directory / opts.parentID 可选；仅在非空白时透传（不做校验，交服务端）。
   // 返回 { id, title, injected, agent?, directory?, error? }；create 失败则抛出（未建会话）。
   async function spawn(prompt, title, opts = {}) {
     const text = typeof prompt === "string" ? prompt : "";
@@ -98,8 +102,10 @@ export const SessionSpawn = async (ctx) => {
     const t = (title && String(title).trim()) || defaultTitle(text);
     const agent = nonEmpty(opts.agent);
     const directory = nonEmpty(opts.directory);
+    const parentID = nonEmpty(opts.parentID);
 
     const createReq = { body: { title: t } };
+    if (parentID !== undefined) createReq.body.parentID = parentID;
     if (directory !== undefined) createReq.query = { directory };
     const created = await client.session.create(createReq);
     const id = created && (created.data?.id || created.id);
@@ -138,9 +144,13 @@ export const SessionSpawn = async (ctx) => {
           agent: tool.schema.string().optional().describe("新会话以某 agent/模式启动（如 leader）；缺省由服务端默认"),
           directory: tool.schema.string().optional().describe("新会话绑定的项目目录（绝对路径，如 D:\\dev\\bbcare）；缺省由服务端默认"),
         },
-        async execute(args) {
+        async execute(args, context) {
           try {
-            const r = await spawn(args.prompt, args.title, { agent: args.agent, directory: args.directory });
+            const r = await spawn(args.prompt, args.title, {
+              agent: args.agent,
+              directory: args.directory,
+              parentID: context && context.sessionID,
+            });
             if (!r.injected) {
               return `会话「${r.title}」(id=${r.id}) 已创建，但起始语句注入失败：${r.error}。请手动打开该会话补发指令。`;
             }
@@ -150,6 +160,47 @@ export const SessionSpawn = async (ctx) => {
           }
         },
       }),
+
+      // 工具：子会话反向通知父会话（沿 parentID 上行；失败一律返回文本，不抛）。
+      notify_parent: tool({
+        description:
+          "向本会话的父会话（spawn 本会话的会话）注入一条消息并唤醒它：用于子会话完成 / 受阻时通知父会话。仅能通知父会话，不支持指定任意会话；注入文本自动加 [relay] 前缀；父会话以服务端默认模式（build）被唤醒。收到通知后按需行动即可，不要自动回发通知（防环路）。",
+        args: {
+          text: tool.schema.string().describe("通知内容（注入父会话，自动加 [relay] 前缀）"),
+        },
+        async execute(args, context) {
+          const text = typeof args.text === "string" ? args.text : "";
+          if (!text.trim()) return "通知失败：内容为空";
+          if (!client || !client.session || typeof client.session.get !== "function") {
+            return "通知失败：client.session.get 不可用";
+          }
+
+          let parentID;
+          try {
+            const got = await client.session.get({ path: { id: context && context.sessionID } });
+            parentID = got && ((got.data && got.data.parentID) || got.parentID);
+          } catch (e) {
+            return `通知失败：读取会话失败（${e.message}）`;
+          }
+          if (!parentID) return "当前会话没有父会话，无法通知";
+
+          const body = { parts: [{ type: "text", text: "[relay] " + text }] };
+          const injectFn =
+            typeof client.session.promptAsync === "function"
+              ? client.session.promptAsync.bind(client.session)
+              : typeof client.session.prompt === "function"
+                ? client.session.prompt.bind(client.session)
+                : null;
+          if (!injectFn) return "通知失败：client.session.promptAsync/prompt 均不可用";
+
+          try {
+            await injectFn({ path: { id: parentID }, body });
+          } catch (e) {
+            return `通知失败：注入父会话失败（${e.message}）`;
+          }
+          return `已通知父会话 (id=${parentID})。`;
+        },
+      }),
     },
 
     // 人工命令：@spawn [--agent <名称>] [--title <标题>] <起始语句>（兼容 @relay spawn）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-session-spawn",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "type": "module",
   "description": "opencode 会话生成原语：创建新顶层会话并注入起始语句，用于无人值守长任务编排（工具 spawn_session + 命令 @spawn）。",
   "main": "index.js",