opencode-session-spawn 2.3.0 → 2.4.0

package/README.md

@@ -1,6 +1,6 @@
 # opencode-session-spawn
 
-opencode 插件：**会话生成原语**。做两件事——**创建一个新的顶层会话，并把起始语句注入为该会话首条消息**（新会话保持顶层，会出现在会话列表中，便于人工查看）；以及**子会话反向通知父会话**（`notify_parent`：注入一条 `[relay]` 消息并唤醒父会话）。
+opencode 插件：**会话生成原语**。做两件事——**创建一个新的顶层会话，并把起始语句注入为该会话首条消息**（新会话保持顶层，会出现在会话列表中，便于人工查看；默认还会让 UI 选中它）；以及**子会话反向通知父会话**（`notify_parent`：注入一条 `[relay]` 消息并唤醒父会话）。
 
 它的用途是**无人值守长任务编排**：当一条任务超出单会话上下文时，当前会话的模型可以在需要时自行生成一段交接语句、调用工具开出一个新会话继续，新会话拿到语句立即开跑；子会话完成 / 受阻时可用 `notify_parent` 回调 spawn 它的会话。插件不落文书、不读文书、不追踪链、无状态文件——需要交接文书时，把「读取某份文书路径」等引导写进起始语句即可，与其他工具天然兼容。
 
@@ -8,9 +8,9 @@ opencode 插件：**会话生成原语**。做两件事——**创建一个新
 
 | 入口 / 工具 | 用法 | 谁触发 |
 |------|------|--------|
-| 工具 `spawn_session` | `spawn_session({ prompt, title?, agent?, directory?, model? })` | **模型自主调用**（打通无人值守） |
+| 工具 `spawn_session` | `spawn_session({ prompt, title?, agent?, directory?, model?, select? })` | **模型自主调用**（打通无人值守） |
 | 工具 `notify_parent` | `notify_parent({ text })` | **子会话模型自主调用**（完成 / 受阻时回调父会话） |
-| 命令 | `@spawn [--agent <名称>] [--title <标题>] <起始语句>`（兼容 `@relay spawn`） | 人工触发 |
+| 命令 | `@spawn [--agent <名称>] [--title <标题>] [--no-select] <起始语句>`（兼容 `@relay spawn`） | 人工触发 |
 
 参数 / 行为：
 
@@ -19,9 +19,10 @@ opencode 插件：**会话生成原语**。做两件事——**创建一个新
 - `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**（不处理引号/空格）；仅解析命令后**前导** flag，起始语句内部再出现的 `--xxx` 原样保留；flag 缺值或起始语句为空 → warning toast 且不建会话。`--title` 优先于起始语句首行。
-- 内部调用（spawn）：`client.session.create({ body: { title, metadata?, model? }, query: { directory } })` → `client.session.promptAsync({ path: { id }, body: { agent, parts: [{ type: "text", text: prompt }] } })`；`agent` / `directory` / `model` / `metadata` 未传时不出现对应键。
+- 命令 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`）被唤醒；空文本 / 无父会话 / 读取或注入失败 → 返回错误文本（不抛）；无重试 / 队列 / 追踪（保持无状态原语）。
 - 优先 `promptAsync`（异步 fire-and-forget，**不阻塞父会话**）；缺失则回退同步 `prompt`。
 - create 失败 → 不建会话；create 成功但注入失败 → **保留已建会话**并提示 id，不产生重复会话。
@@ -73,7 +74,7 @@ notify_parent({ text: "P1-10 已完成，验收报告见 runs/P1-10-acceptance.m
 
 ```bash
 npm install          # 安装 devDependency @opencode-ai/plugin（唯一依赖，仅测试用）
-node test/test.mjs   # 39 用例 / 94 断言
+node test/test.mjs   # 46 用例 / 106 断言
 ```
 
 - `test/test.mjs` 默认经相对路径 `../index.js` 测项目版；环境变量 `RELAY_MAIN` 覆盖为其他路径（tarball 解包版 / 包缓存活实例）。`RELAY_MAIN` 目标须能向上解析到 `@opencode-ai/plugin`（解包放项目内即可）。
@@ -87,6 +88,7 @@ bump 版本号（`package.json` 与 `index.js` 头注释同步）→ `node test/
 
 前身 `opencode-session-relay` 的接力链、两阶段交接文书、空闲事件驱动、哨兵兜底、`@relay status/leave/refresh/verify` 等机制已全部移除，仅保留「建会话 + 注入语句」这一核心原语。
 
+- **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

@@ -1,12 +1,13 @@
 import { tool } from "@opencode-ai/plugin/tool";
 
 /**
- * session-spawn —— 会话生成原语（v2.3.0，2026-09-15 起：父链接走 metadata + 可选 model）
+ * session-spawn —— 会话生成原语（v2.4.0，2026-09-15 起：父链接走 metadata + 可选 model + 创建后选中新会话）
  *
  * 只做两件事：
  *   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；仅父会话，无任意会话注入）。
  *
@@ -19,6 +20,8 @@ import { tool } from "@opencode-ai/plugin/tool";
  *   - **父链接写入会话 metadata（`spawnParentID`），不写 `parentID`**：桌面端会话列表只拉取顶层会话，
  *     写 parentID 会让派发会话变成「子会话」而从列表消失（v2.2.0 的可见性回归）；metadata 不影响列表，
  *     notify_parent 沿 `metadata.spawnParentID` 上行，并兼容旧会话的 `parentID` 回退。
+ *   - **创建后默认让 UI 选中新会话**（`tui.selectSession`，失败忽略、不阻塞返回）：TUI 即时生效；
+ *     桌面端 app 尚未消费该事件（上游 issue #45963），当前为 no-op，接线后自动开 tab。
  *
  * 历史：本仓库前身 session-relay 的接力链、两阶段文书、空闲事件驱动、哨兵等机制已全部移除。
  */
@@ -56,11 +59,11 @@ function parseModel(v) {
   return { providerID: s.slice(0, i), id: s.slice(i + 1) };
 }
 
-const SPAWN_USAGE = "用法：@spawn [--agent <名称>] [--title <标题>] <起始语句>";
+const SPAWN_USAGE = "用法：@spawn [--agent <名称>] [--title <标题>] [--no-select] <起始语句>";
 
-// 解析人工命令：@spawn / @relay spawn，支持前导 --agent / --title。
-// 返回 null（非 spawn 命令）或 { prompt, agent, title } / { error, flag?, agent?, title? }。
-// 规则：仅解析命令后前导的 flag；值均为单个空白分隔 token；剩余内容原样作为起始语句。
+// 解析人工命令：@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;
@@ -68,7 +71,14 @@ function parseSpawnCommand(text) {
   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);
@@ -84,7 +94,7 @@ function parseSpawnCommand(text) {
 
   const prompt = rest.trim();
   if (!prompt) return { error: "empty-prompt", agent, title };
-  return { prompt, agent, title };
+  return { prompt, agent, title, select };
 }
 
 export const SessionSpawn = async (ctx) => {
@@ -100,8 +110,25 @@ export const SessionSpawn = async (ctx) => {
     }
   };
 
+  // 创建后让 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}`);
+    }
+  }
+
   // 核心：建新会话 + 注入起始语句。
-  // opts.agent / opts.directory / opts.model / opts.parentSessionID 可选；仅非空白时透传（不做校验）。
+  // 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 = {}) {
@@ -123,6 +150,7 @@ export const SessionSpawn = async (ctx) => {
     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;
@@ -150,13 +178,14 @@ export const SessionSpawn = async (ctx) => {
     tool: {
       spawn_session: tool({
         description:
-          "创建一个新的顶层会话并向其注入起始语句，用于无人值守长任务编排：当前会话模型在需要时自行决定把工作交给一个新会话继续。新会话会立即开始执行该起始语句；它保持顶层，会出现在会话列表中（便于人工查看）。若需让其读取某份交接文书，请把文书路径与读取要求写进 prompt。agent 可指定新会话以某 agent/模式启动（如 leader）；directory 可绑定项目目录；model 可指定模型（provider/model）。新会话可用 notify_parent 回通知本会话。",
+          "创建一个新的顶层会话并向其注入起始语句，用于无人值守长任务编排：当前会话模型在需要时自行决定把工作交给一个新会话继续。新会话会立即开始执行该起始语句；它保持顶层，会出现在会话列表中（便于人工查看），并默认让 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 {
@@ -164,6 +193,7 @@ export const SessionSpawn = async (ctx) => {
               agent: args.agent,
               directory: args.directory,
               model: args.model,
+              select: args.select,
               parentSessionID: context && context.sessionID,
             });
             if (!r.injected) {
@@ -220,7 +250,7 @@ export const SessionSpawn = async (ctx) => {
       }),
     },
 
-    // 人工命令：@spawn [--agent <名称>] [--title <标题>] <起始语句>（兼容 @relay spawn）。
+    // 人工命令：@spawn [--agent <名称>] [--title <标题>] [--no-select] <起始语句>（兼容 @relay spawn）。
     "chat.message": async ({ sessionID }, { parts }) => {
       try {
         const text = userText(parts);
@@ -235,7 +265,7 @@ export const SessionSpawn = async (ctx) => {
           return;
         }
         try {
-          const r = await spawn(parsed.prompt, parsed.title, { agent: parsed.agent });
+          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 {

package/package.json

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