opencode-session-spawn 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Qiu Kejian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# opencode-session-spawn
+
+opencode 插件：**会话生成原语**。做四件事——**创建一个新的顶层会话，并把起始语句注入为该会话首条消息**（新会话保持顶层，会出现在会话列表中，便于人工查看；默认还会让 UI 选中它）；**子会话反向通知父会话**（`notify_parent`：注入一条 `[relay]` 消息并唤醒父会话）；**向任意指定会话注入并唤醒它**（`notify_session`：父/任意会话向已知会话投递指令/纠偏/叫停）；以及**只读列举派生会话**（`list_sessions`：按父链接发现直接 / 传递派生的会话 id）。
+
+它的用途是**无人值守长任务编排**：当一条任务超出单会话上下文时，当前会话的模型可以在需要时自行生成一段交接语句、调用工具开出一个新会话继续，新会话拿到语句立即开跑；子会话完成 / 受阻时可用 `notify_parent` 回调 spawn 它的会话；父会话也可用 `list_sessions` 找回（可能由中间会话间接派生的）会话 id，再用 `notify_session` 向指定会话投递纠偏 / 叫停指令。插件不落文书、不读文书、不追踪链、无状态文件——需要交接文书时，把「读取某份文书路径」等引导写进起始语句即可，与其他工具天然兼容。
+
+## 入口与工具
+
+| 入口 / 工具 | 用法 | 谁触发 |
+|------|------|--------|
+| 工具 `spawn_session` | `spawn_session({ prompt, title?, agent?, directory?, model?, select? })` | **模型自主调用**（打通无人值守） |
+| 工具 `notify_parent` | `notify_parent({ text })` | **子会话模型自主调用**（完成 / 受阻时回调父会话） |
+| 工具 `notify_session` | `notify_session({ sessionID, text, prefix?, agent? })` | **父 / 任意会话模型自主调用**（向指定会话投递指令 / 纠偏 / 叫停） |
+| 工具 `list_sessions` | `list_sessions({ parentSessionID?, recursive?, directory? })` | **模型自主调用**（只读发现派生会话 id） |
+| 命令 | `@spawn [--agent <名称>] [--title <标题>] [--no-select] <起始语句>`（兼容 `@relay spawn`） | 人工触发 |
+
+参数 / 行为：
+
+- `prompt`（必填）：注入新会话的起始语句。可内含读取文件、复述要点、执行下一步等引导。
+- `title`（可选）：新会话标题。缺省取 `prompt` 首行（清洗非法字符、截断 60）。
+- `agent`（可选，工具参数）：新会话以某 agent/模式启动（如 `leader`）。仅在传了非空白值时透传，交服务端校验。
+- `directory`（可选，工具参数）：新会话绑定的项目目录（如 `D:\dev\bbcare`）。仅在传了非空白值时透传，交服务端校验。
+- `model`（可选，工具参数）：新会话使用的模型，格式 `provider/model`（如 `deepseek/deepseek-v4-flash`、`opencode/big-pickle`），透传为 `{ providerID, id }`；空 / 无 `/` 视为未传，缺省由服务端默认。
+- `select`（可选，工具参数，默认 `true`）：创建后让 UI 选中新会话——优先 `client.tui.selectSession({ sessionID })`，缺失则回退 `client.tui.publish({ type: "tui.session.select", properties: { sessionID } })`；失败 / 不可用仅记录，不影响创建与注入。**TUI 即时生效；桌面端 app 尚未消费该事件（上游 issue #45963），当前为 no-op**，接线后自动打开/切换到该会话 tab。命令 `--no-select` 可关闭。
+- 父链接（自动，非参数）：`spawn_session` 把调用者会话 id 写入新会话 **`metadata.spawnParentID`**（`context.sessionID` 非空白时）。**不写 `parentID`**——桌面端会话列表只拉取顶层会话，写 `parentID` 会让新会话变成「子会话」而从列表消失（v2.2.0 的可见性回归）；metadata 不影响列表。命令 `@spawn` 无会话上下文，不带父链接。
+- 命令 flag 说明：`--agent` / `--title` 值均为**单个 token**（不处理引号/空格）；`--no-select` 为布尔开关；仅解析命令后**前导** flag，起始语句内部再出现的 `--xxx` 原样保留；flag 缺值或起始语句为空 → warning toast 且不建会话。`--title` 优先于起始语句首行。
+- 内部调用（spawn）：`client.session.create({ body: { title, metadata?, model? }, query: { directory } })` → `client.tui.selectSession({ sessionID })`（可选）→ `client.session.promptAsync({ path: { id }, body: { agent, parts: [{ type: "text", text: prompt }] } })`；`agent` / `directory` / `model` / `metadata` 未传时不出现对应键。
+- `notify_parent` 行为：仅能通知**父会话**（不提供任意 session id 参数）；`client.session.get` 解析自身 `metadata.spawnParentID`（旧会话回退 `parentID`）后，向父会话注入 `[relay] <text>` 并唤醒它；父会话以服务端默认模式（`build`）被唤醒；空文本 / 无父会话 / 读取或注入失败 → 返回错误文本（不抛）；无重试 / 队列 / 追踪（保持无状态原语）。
+- `notify_session` 行为：向**指定会话**注入一条消息并唤醒它，与 `notify_parent` 相对（父 / 任意会话 → 指定会话）。先用 `client.session.get({ path: { id } })` **校验目标存在**，再向其注入文本并唤醒；`prefix: false` 关闭 `[relay] ` 前缀（默认加），可选 `agent` 指定唤醒模式。空 `sessionID` / 空 `text` / 目标=自身 / 目标不存在 / 读取或注入失败 / prompt 均不可用 → 返回错误文本（不抛），一律不注入。**默认允许任意 sessionID**（用户明确要求「任意」）：可向非派生会话注入，误用可能致互喷 / 环路——请仅对自己已知 / 派生的会话使用，收到通知后按需行动、勿自动回发。
+- `list_sessions` 行为：**只读**列举会话。数据来自 **SDK** `client.session.list({ query: { directory? } })`（**不查 opencode.db**、不落状态文件）；按 `metadata.spawnParentID` 过滤（**不用 `session.children`**——它走真 `parentID`，而本插件故意不写 parentID）。`parentSessionID` 缺省 = 当前会话；`recursive: false`（默认）只列**直接**子会话，`true` 沿 `spawnParentID` BFS 列**全部传递后代**（visited 去重防环）。返回紧凑表格文本（每行 `id | title | directory | parent | updated`），无匹配 → `无匹配会话`。旧客户端 `list` 不带 `metadata` 时，逐个 `session.get` 回退读取（N+1，会话量小可接受）。
+- 优先 `promptAsync`（异步 fire-and-forget，**不阻塞父会话**）；缺失则回退同步 `prompt`。
+- create 失败 → 不建会话；create 成功但注入失败 → **保留已建会话**并提示 id，不产生重复会话。
+
+## 安装（部署到桌面版）
+
+现有部署形态：公共层配置 `share/opencode.json`（挂载到项目内即 `.opencode/opencode.json`）的 `plugin` 数组注册 **npm 包名**：
+
+```jsonc
+{
+  "plugin": ["opencode-session-spawn"]
+}
+```
+
+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`（见下节）。
+
+## 编排示例
+
+模型在长任务中决定交接，直接调用工具（可选 `agent` / `directory`）：
+
+```
+spawn_session({
+  prompt: `你是本任务的接手会话。先读取交接文书：
+E:\\proj\\handoff\\migration-3.md
+通读后复述要点（已完成/未完成/下一步第 1 件事），确认后继续执行。`,
+  title: "[迁移] 第 3 棒",
+  agent: "leader",
+  directory: "D:\\dev\\bbcare"
+})
+```
+
+或人工在会话里发（前导 flag 可省略、顺序不限）：
+
+```
+@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` 只向父会话发送，避免环路）。
+
+父会话向指定（可能由中间会话间接派生的）会话投递纠偏 / 叫停：
+
+```
+list_sessions({ recursive: true })   // 找回派生会话 id（默认只列直接子会话；recursive 含全部传递后代）
+notify_session({ sessionID: "ses_xxx", text: "停止当前分支并汇报进度" })
+notify_session({ sessionID: "ses_yyy", text: "仅执行下列修正：…", prefix: false })
+```
+
+`list_sessions` 只读、走 SDK（**不查数据库**），按 `metadata.spawnParentID` 发现会话；`notify_session` 目标须已存在，默认加 `[relay] ` 前缀（`prefix: false` 关闭），亦可带 `agent` 指定唤醒模式。
+
+## 开发与测试
+
+```bash
+npm install          # 安装 devDependency @opencode-ai/plugin（唯一依赖，仅测试用）
+node test/test.mjs   # 64 用例 / 152 断言
+```
+
+- `test/test.mjs` 默认经相对路径 `../index.js` 测项目版；环境变量 `RELAY_MAIN` 覆盖为其他路径（tarball 解包版 / 包缓存活实例）。`RELAY_MAIN` 目标须能向上解析到 `@opencode-ai/plugin`（解包放项目内即可）。
+- 以尾部 `==== 结果: N 通过, 0 失败 ====` 为准。
+
+## 发布
+
+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`。
+
+## 历史
+
+前身 `opencode-session-relay` 的接力链、两阶段交接文书、空闲事件驱动、哨兵兜底、`@relay status/leave/refresh/verify` 等机制已全部移除，仅保留「建会话 + 注入语句」这一核心原语。
+
+- **v2.5.0（2026-10-14）**：新增工具 `notify_session`（向任意指定 `sessionID` 注入 `[relay]` 消息并唤醒；`prefix` / `agent` 可选；先校验目标存在；默认允许任意会话）与 `list_sessions`（**只读**、走 SDK `client.session.list`、按 `metadata.spawnParentID` 发现直接 / 传递派生的会话，**不查数据库**）。用于「父 / 任意会话 → 指定会话」的纠偏 / 叫停通道与会话发现（填补 `notify_parent` 只能上行、`task` 操作不了 `spawn_session` 顶层会话的缺口）。
+- **v2.4.0（2026-09-15）**：创建后默认让 UI 选中新会话（`client.tui.selectSession`，回退 `tui.publish` 事件；`select: false` / `@spawn --no-select` 关闭）。TUI 即时生效；桌面端 app 尚未消费 `tui.session.select`（上游 issue #45963），当前为 no-op，接线后自动开 tab。
+- **v2.3.0（2026-09-15）**：父链接由 `parentID` 改为 **`metadata.spawnParentID`**（修复 v2.2.0 可见性回归：写 parentID 会让新会话变成子会话、从桌面端会话列表消失；且子会话默认不能再开 `task` 子代理，会破坏编排）；`notify_parent` 兼容旧会话的 `parentID` 回退；新增可选 `model` 参数（`provider/model`）。
+- **v2.2.0**：新增 `notify_parent` 反向通知；`spawn_session` 自动挂 `parentID`。
+- **v2.1.0**：`spawn_session` 支持 `agent` / `directory`；命令 `@spawn` 支持 `--agent` / `--title`。

package/index.js

@@ -0,0 +1,407 @@
+import { tool } from "@opencode-ai/plugin/tool";
+
+/**
+ * session-spawn —— 会话生成原语（v2.5.0，2026-10-14 起：新增 notify_session 向指定会话注入 + list_sessions 会话发现）
+ *
+ * 只做四件事：
+ *   1. 创建一个新的顶层会话，并把起始语句注入为该会话首条消息。
+ *      create: client.session.create({ body: { title, metadata?, model? }, query: { directory } })
+ *      inject: client.session.promptAsync({ path: { id }, body: { agent, parts: [{ type: "text", text }] } })
+ *      select: client.tui.selectSession({ sessionID })（可选，默认开；回退 tui.publish 事件）
+ *      （agent / directory / model 均可选，仅在显式传入且非空白时透传；不做校验，交服务端）
+ *   2. 子会话向父会话注入一条 [relay] 消息并唤醒它（工具 notify_parent；仅父会话，上行单向）。
+ *   3. 向任意指定会话注入一条 [relay] 消息并唤醒它（工具 notify_session；父/任意会话 → 指定会话，与 notify_parent 相对）。
+ *   4. 只读列举会话（工具 list_sessions；按 metadata.spawnParentID 发现直接/传递派生的会话）。
+ *
+ * 设计约束（用户定稿）：
+ *   - 插件只负责「建会话 + 注入语句 + 通知/发现会话」，不落文书、不读文书、不追踪链、无状态文件。
+ *   - 编排中若需交接文书，由调用方把「读取文书路径」等引导写进起始语句即可（与其他工具天然兼容）。
+ *   - 优先 promptAsync（异步 fire-and-forget，不阻塞父会话）；缺失则回退同步 prompt。
+ *   - 入口共用：① 工具 spawn_session / notify_parent / notify_session / list_sessions（模型自主触发）
+ *              ② 命令 @spawn / @relay spawn（人工触发）。
+ *   - **父链接写入会话 metadata（`spawnParentID`），不写 `parentID`**：桌面端会话列表只拉取顶层会话，
+ *     写 parentID 会让派发会话变成「子会话」而从列表消失（v2.2.0 的可见性回归）；metadata 不影响列表，
+ *     notify_parent 沿 `metadata.spawnParentID` 上行并兼容旧会话的 `parentID` 回退；list_sessions 亦按此过滤。
+ *   - **创建后默认让 UI 选中新会话**（`tui.selectSession`，失败忽略、不阻塞返回）：TUI 即时生效；
+ *     桌面端 app 尚未消费该事件（上游 issue #45963），当前为 no-op，接线后自动开 tab。
+ *   - **list_sessions 只读且走 SDK**（`client.session.list`），不读 opencode.db、不落状态文件（跨平台脆弱 + 保持无状态）。
+ *   - **notify_session 默认允许任意 sessionID**（用户明确要「任意」）；文档标注风险（可向非派生会话注入，误用致环路）。
+ *
+ * 历史：本仓库前身 session-relay 的接力链、两阶段文书、空闲事件驱动、哨兵等机制已全部移除。
+ */
+
+// 标题清洗：首行 → 去 Windows 非法字符与控制符 → 截断 60；空则回退 "spawn"。
+function defaultTitle(prompt) {
+  return (
+    String(prompt || "")
+      .split(/\r?\n/)[0]
+      .replace(/[<>:"/\\|?*\x00-\x1f]/g, "")
+      .trim()
+      .slice(0, 60) || "spawn"
+  );
+}
+
+function userText(parts) {
+  if (!Array.isArray(parts)) return "";
+  return parts
+    .filter((p) => p && p.type === "text" && typeof p.text === "string")
+    .map((p) => p.text)
+    .join(" ");
+}
+
+// 可选参数透传判定：空串 / 纯空白视为未传（返回 undefined）。
+function nonEmpty(v) {
+  return typeof v === "string" && v.trim() !== "" ? v : undefined;
+}
+
+// 解析 "provider/model" → { providerID, id }；空 / 无 "/" / 缺段 → undefined（视为未传）。
+function parseModel(v) {
+  const s = nonEmpty(v);
+  if (s === undefined) return undefined;
+  const i = s.indexOf("/");
+  if (i <= 0 || i >= s.length - 1) return undefined;
+  return { providerID: s.slice(0, i), id: s.slice(i + 1) };
+}
+
+const SPAWN_USAGE = "用法：@spawn [--agent <名称>] [--title <标题>] [--no-select] <起始语句>";
+
+// 解析人工命令：@spawn / @relay spawn，支持前导 --agent / --title / --no-select。
+// 返回 null（非 spawn 命令）或 { prompt, agent, title, select } / { error, flag?, agent?, title? }。
+// 规则：仅解析命令后前导的 flag；--agent/--title 值为单个空白分隔 token；--no-select 为布尔开关；剩余内容原样作为起始语句。
+function parseSpawnCommand(text) {
+  const m = /^\s*@(?:relay\s+)?spawn\b([\s\S]*)$/i.exec(String(text || ""));
+  if (!m) return null;
+
+  let rest = m[1];
+  let agent;
+  let title;
+  let select = true;
+  while (true) {
+    const bm = /^\s*--no-select(?=\s|$)/.exec(rest);
+    if (bm) {
+      rest = rest.slice(bm[0].length);
+      select = false;
+      continue;
+    }
+    const fm = /^\s*(--agent|--title)(?=\s|$)/.exec(rest);
+    if (!fm) break;
+    rest = rest.slice(fm[0].length);
+    const vm = /^\s+(\S+)/.exec(rest);
+    const value = vm && vm[1];
+    if (!value || value.startsWith("--")) {
+      return { error: "missing-value", flag: fm[1], agent, title };
+    }
+    rest = rest.slice(vm[0].length);
+    if (fm[1] === "--agent") agent = value;
+    else title = value;
+  }
+
+  const prompt = rest.trim();
+  if (!prompt) return { error: "empty-prompt", agent, title };
+  return { prompt, agent, title, select };
+}
+
+export const SessionSpawn = async (ctx) => {
+  const { client } = ctx;
+
+  const notify = async (title, message, variant = "info") => {
+    try {
+      if (client && client.tui && client.tui.showToast) {
+        await client.tui.showToast({ title, message, variant, duration: 15000 });
+      }
+    } catch (e) {
+      console.error(`[session-spawn] toast 通知失败: ${e.message}`);
+    }
+  };
+
+  // 创建后让 UI 选中新会话：优先 client.tui.selectSession，缺失则回退 tui.publish 事件；
+  // 均不可用 / 失败 → 仅记录，不影响 spawn 结果（桌面端 app 当前未消费该事件，为 no-op）。
+  async function selectCreatedSession(sessionID) {
+    try {
+      if (client && client.tui && typeof client.tui.selectSession === "function") {
+        await client.tui.selectSession({ sessionID });
+        return;
+      }
+      if (client && client.tui && typeof client.tui.publish === "function") {
+        await client.tui.publish({ type: "tui.session.select", properties: { sessionID } });
+        return;
+      }
+    } catch (e) {
+      console.error(`[session-spawn] 选中新会话失败（忽略）: ${e.message}`);
+    }
+  }
+
+  // 解析注入函数：优先异步 promptAsync（fire-and-forget），缺失回退同步 prompt；均不可用 → null。
+  function resolveInjectFn() {
+    if (!client || !client.session) return null;
+    if (typeof client.session.promptAsync === "function") return client.session.promptAsync.bind(client.session);
+    if (typeof client.session.prompt === "function") return client.session.prompt.bind(client.session);
+    return null;
+  }
+
+  // 核心：建新会话 + 注入起始语句。
+  // opts.agent / opts.directory / opts.model / opts.select / opts.parentSessionID 可选；仅非空白时透传（不做校验）。
+  // 父链接写 metadata.spawnParentID（不写 parentID：保持顶层 → 会话列表可见）。
+  // 返回 { id, title, injected, agent?, directory?, error? }；create 失败则抛出（未建会话）。
+  async function spawn(prompt, title, opts = {}) {
+    const text = typeof prompt === "string" ? prompt : "";
+    if (!text.trim()) throw new Error("起始语句为空");
+    if (!client || !client.session || typeof client.session.create !== "function") {
+      throw new Error("client.session.create 不可用");
+    }
+    const t = (title && String(title).trim()) || defaultTitle(text);
+    const agent = nonEmpty(opts.agent);
+    const directory = nonEmpty(opts.directory);
+    const parentSessionID = nonEmpty(opts.parentSessionID);
+    const model = parseModel(opts.model);
+
+    const createReq = { body: { title: t } };
+    if (parentSessionID !== undefined) createReq.body.metadata = { spawnParentID: parentSessionID };
+    if (model !== undefined) createReq.body.model = model;
+    if (directory !== undefined) createReq.query = { directory };
+    const created = await client.session.create(createReq);
+    const id = created && (created.data?.id || created.id);
+    if (!id) throw new Error("create 未返回会话 id");
+    if (opts.select !== false) await selectCreatedSession(id);
+
+    const body = { parts: [{ type: "text", text }] };
+    if (agent !== undefined) body.agent = agent;
+    const injectFn = resolveInjectFn();
+    if (!injectFn) {
+      return { id, title: t, injected: false, agent, directory, error: "client.session.promptAsync/prompt 均不可用" };
+    }
+
+    try {
+      await injectFn({ path: { id }, body });
+      return { id, title: t, injected: true, agent, directory };
+    } catch (e) {
+      console.error(`[session-spawn] 注入失败（会话 ${id} 已建保留）: ${e.message}`);
+      return { id, title: t, injected: false, agent, directory, error: e.message };
+    }
+  }
+
+  return {
+    // 工具：模型自主调用 → 无人值守长任务编排的最短路径。
+    tool: {
+      spawn_session: tool({
+        description:
+          "创建一个新的顶层会话并向其注入起始语句，用于无人值守长任务编排：当前会话模型在需要时自行决定把工作交给一个新会话继续。新会话会立即开始执行该起始语句；它保持顶层，会出现在会话列表中（便于人工查看），并默认让 UI 选中它（TUI 即时生效；桌面端需 app 支持，当前为 no-op）。若需让其读取某份交接文书，请把文书路径与读取要求写进 prompt。agent 可指定新会话以某 agent/模式启动（如 leader）；directory 可绑定项目目录；model 可指定模型（provider/model）。新会话可用 notify_parent 回通知本会话。",
+        args: {
+          prompt: tool.schema.string().describe("注入新会话的起始语句（可内含读取交接文书路径等引导）"),
+          title: tool.schema.string().optional().describe("新会话标题；缺省取起始语句首行"),
+          agent: tool.schema.string().optional().describe("新会话以某 agent/模式启动（如 leader）；缺省由服务端默认"),
+          directory: tool.schema.string().optional().describe("新会话绑定的项目目录（绝对路径，如 D:\\dev\\bbcare）；缺省由服务端默认"),
+          model: tool.schema.string().optional().describe("新会话使用的模型（provider/model，如 deepseek/deepseek-v4-flash 或 opencode/big-pickle）；缺省由服务端默认"),
+          select: tool.schema.boolean().optional().describe("创建后让 UI 选中新会话（默认 true；传 false 关闭）"),
+        },
+        async execute(args, context) {
+          try {
+            const r = await spawn(args.prompt, args.title, {
+              agent: args.agent,
+              directory: args.directory,
+              model: args.model,
+              select: args.select,
+              parentSessionID: context && context.sessionID,
+            });
+            if (!r.injected) {
+              return `会话「${r.title}」(id=${r.id}) 已创建，但起始语句注入失败：${r.error}。请手动打开该会话补发指令。`;
+            }
+            return `已创建会话「${r.title}」(id=${r.id}) 并注入起始语句，新会话已开始执行。`;
+          } catch (e) {
+            return `创建会话失败：${e.message}`;
+          }
+        },
+      }),
+
+      // 工具：子会话反向通知父会话（沿 metadata.spawnParentID 上行，兼容 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 } });
+            const info = (got && (got.data || got)) || {};
+            const meta = info.metadata || {};
+            parentID = nonEmpty(meta.spawnParentID) || nonEmpty(info.parentID);
+          } catch (e) {
+            return `通知失败：读取会话失败（${e.message}）`;
+          }
+          if (!parentID) return "当前会话没有父会话，无法通知";
+
+          const body = { parts: [{ type: "text", text: "[relay] " + text }] };
+          const injectFn = resolveInjectFn();
+          if (!injectFn) return "通知失败：client.session.promptAsync/prompt 均不可用";
+
+          try {
+            await injectFn({ path: { id: parentID }, body });
+          } catch (e) {
+            return `通知失败：注入父会话失败（${e.message}）`;
+          }
+          return `已通知父会话 (id=${parentID})。`;
+        },
+      }),
+
+      // 工具：父（或任意）会话向「指定」会话注入消息并唤醒它（与 notify_parent 相对；失败一律返回文本，不抛）。
+      notify_session: tool({
+        description:
+          "向指定会话（sessionID）注入一条消息并唤醒它：用于父会话向自己派生的会话投递指令/纠偏/叫停，或向任意已知会话投递消息。与 notify_parent 相对（后者只通知自己的父会话）。注入文本默认加 [relay] 前缀（prefix:false 关闭）。目标须已存在（会先校验）；默认允许任意 sessionID，请仅对自己已知/派生的会话使用，收到通知后按需行动、勿自动回发（防环路）。",
+        args: {
+          sessionID: tool.schema.string().describe("目标会话 id（如 spawn_session 返回的 id / list_sessions 列出的 id）"),
+          text: tool.schema.string().describe("注入内容"),
+          prefix: tool.schema.boolean().optional().describe("是否加 [relay] 前缀（默认 true）"),
+          agent: tool.schema.string().optional().describe("唤醒模式（如 leader）；缺省由服务端默认"),
+        },
+        async execute(args, context) {
+          const sessionID = nonEmpty(args.sessionID);
+          const text = typeof args.text === "string" ? args.text : "";
+          if (!sessionID) return "通知失败：sessionID 为空";
+          if (!text.trim()) return "通知失败：内容为空";
+          if (context && context.sessionID && sessionID === context.sessionID) {
+            return "通知失败：目标为本会话自身";
+          }
+          if (!client || !client.session || typeof client.session.get !== "function") {
+            return "通知失败：client.session.get 不可用";
+          }
+          try {
+            const got = await client.session.get({ path: { id: sessionID } });
+            const info = got && (got.data || got);
+            if (!info || !info.id) return `通知失败：目标会话不存在 (id=${sessionID})`;
+          } catch (e) {
+            return `通知失败：读取目标会话失败（${e.message}）`;
+          }
+
+          const body = { parts: [{ type: "text", text: (args.prefix === false ? "" : "[relay] ") + text }] };
+          const agent = nonEmpty(args.agent);
+          if (agent !== undefined) body.agent = agent;
+          const injectFn = resolveInjectFn();
+          if (!injectFn) return "通知失败：client.session.promptAsync/prompt 均不可用";
+
+          try {
+            await injectFn({ path: { id: sessionID }, body });
+          } catch (e) {
+            return `通知失败：注入目标会话失败（${e.message}）`;
+          }
+          return `已通知会话 (id=${sessionID})。`;
+        },
+      }),
+
+      // 工具：只读列举会话（默认本会话直接派生的子会话；recursive 含全部传递后代）。
+      // 数据来自 SDK client.session.list（不查数据库/文件）；按 metadata.spawnParentID 过滤（不用 session.children）。
+      list_sessions: tool({
+        description:
+          "只读列出会话：默认列出本会话直接派生的子会话（按 metadata.spawnParentID），recursive:true 含所有传递后代。数据来自 SDK client.session.list（不查数据库）。用于父会话找回（可能由中间会话派生的）会话 id，再配 notify_session 投递指令。",
+        args: {
+          parentSessionID: tool.schema.string().optional().describe("父会话 id；缺省=当前会话"),
+          recursive: tool.schema.boolean().optional().describe("是否含所有传递后代（默认 false，仅直接子会话）"),
+          directory: tool.schema.string().optional().describe("按项目目录过滤（透传 session.list）"),
+        },
+        async execute(args, context) {
+          if (!client || !client.session || typeof client.session.list !== "function") {
+            return "列举失败：client.session.list 不可用";
+          }
+          const root = nonEmpty(args.parentSessionID) || nonEmpty(context && context.sessionID);
+          if (!root) return "列举失败：无法确定父会话 id";
+
+          let all;
+          try {
+            const res = await client.session.list(args.directory ? { query: { directory: args.directory } } : {});
+            all = (res && (res.data || res)) || [];
+          } catch (e) {
+            return `列举失败：${e.message}`;
+          }
+          if (!Array.isArray(all)) return "列举失败：client.session.list 返回格式异常";
+
+          // 读 spawnParentID：优先用 list 返回的 metadata；metadata 整段缺失（旧客户端）则逐个 session.get 回退。
+          const canGet = typeof client.session.get === "function";
+          async function parentOf(s) {
+            if (s && s.metadata) return nonEmpty(s.metadata.spawnParentID);
+            if (!canGet) return undefined;
+            try {
+              const g = await client.session.get({ path: { id: s.id } });
+              const info = g && (g.data || g);
+              return nonEmpty(info && info.metadata && info.metadata.spawnParentID);
+            } catch {
+              return undefined;
+            }
+          }
+
+          const byParent = new Map();
+          for (const s of all) {
+            if (!s || !s.id || s.id === root) continue;
+            const p = await parentOf(s);
+            if (p === undefined) continue;
+            if (!byParent.has(p)) byParent.set(p, []);
+            byParent.get(p).push(s);
+          }
+
+          const seen = new Set([root]);
+          const out = [];
+          let frontier = [root];
+          while (frontier.length) {
+            const next = [];
+            for (const id of frontier) {
+              for (const s of byParent.get(id) || []) {
+                if (seen.has(s.id)) continue;
+                seen.add(s.id);
+                out.push(s);
+                next.push(s.id);
+              }
+            }
+            if (!args.recursive) break;
+            frontier = next;
+          }
+          if (!out.length) return "无匹配会话";
+
+          return out
+            .map((s) => {
+              const t = (s.time && s.time.updated) || 0;
+              const up = t ? new Date(t).toISOString().slice(0, 19).replace("T", " ") : "";
+              return `${s.id} | ${s.title || ""} | ${s.directory || ""} | ${s.metadata?.spawnParentID || s.parentID || ""} | ${up}`;
+            })
+            .join("\n");
+        },
+      }),
+    },
+
+    // 人工命令：@spawn [--agent <名称>] [--title <标题>] [--no-select] <起始语句>（兼容 @relay spawn）。
+    "chat.message": async ({ sessionID }, { parts }) => {
+      try {
+        const text = userText(parts);
+        const parsed = parseSpawnCommand(text);
+        if (!parsed) return;
+        if (parsed.error === "missing-value") {
+          await notify("spawn", `${parsed.flag} 缺少值。${SPAWN_USAGE}`, "warning");
+          return;
+        }
+        if (parsed.error === "empty-prompt") {
+          await notify("spawn", SPAWN_USAGE, "warning");
+          return;
+        }
+        try {
+          const r = await spawn(parsed.prompt, parsed.title, { agent: parsed.agent, select: parsed.select });
+          if (!r.injected) {
+            await notify("spawn", `会话「${r.title}」(id=${r.id}) 已创建，但注入失败：${r.error}`, "warning");
+          } else {
+            await notify("spawn", `已创建会话「${r.title}」(id=${r.id}) 并注入起始语句。`);
+          }
+        } catch (e) {
+          await notify("spawn", `创建失败：${e.message}`, "error");
+        }
+      } catch (e) {
+        console.error(`[session-spawn] chat.message 处理失败: ${e.message}`);
+      }
+    },
+  };
+};
+
+export default SessionSpawn;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "opencode-session-spawn",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "opencode 会话生成原语：创建新顶层会话并注入起始语句、向指定会话注入消息、只读列举派生会话，用于无人值守长任务编排（工具 spawn_session / notify_parent / notify_session / list_sessions + 命令 @spawn）。",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "plugin",
+    "session",
+    "spawn",
+    "orchestration",
+    "unattended"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Qiu-Kejian/opencode-session-spawn.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.1.36"
+  }
+}