opencode-session-spawn 2.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,67 @@
+# opencode-session-spawn
+
+opencode 插件：**会话生成原语**。只做一件事——**创建一个新的顶层会话，并把起始语句注入为该会话的首条消息**。
+
+它的用途是**无人值守长任务编排**：当一条任务超出单会话上下文时，当前会话的模型可以在需要时自行生成一段交接语句、调用工具开出一个新会话继续，新会话拿到语句立即开跑。插件不落文书、不读文书、不追踪链、无状态文件——需要交接文书时，把「读取某份文书路径」等引导写进起始语句即可，与其他工具天然兼容。
+
+## 两个入口（共用同一实现）
+
+| 入口 | 用法 | 谁触发 |
+|------|------|--------|
+| 工具 `spawn_session` | `spawn_session({ prompt, title? })` | **模型自主调用**（打通无人值守） |
+| 命令 | `@spawn <起始语句>`（兼容 `@relay spawn`） | 人工触发 |
+
+参数 / 行为：
+
+- `prompt`（必填）：注入新会话的起始语句。可内含读取文件、复述要点、执行下一步等引导。
+- `title`（可选）：新会话标题。缺省取 `prompt` 首行（清洗非法字符、截断 60）。
+- 内部调用：`client.session.create({ body: { title } })` → `client.session.promptAsync({ path: { id }, body: { parts: [{ type: "text", text: prompt }] } })`。
+- 优先 `promptAsync`（异步 fire-and-forget，**不阻塞父会话**）；缺失则回退同步 `prompt`。
+- create 失败 → 不建会话；create 成功但注入失败 → **保留已建会话**并提示 id，不产生重复会话。
+
+## 安装（部署到桌面版）
+
+桌面版从用户配置目录加载活插件：
+
+```bash
+cp index.js package.json "$HOME/.config/opencode/plugins/session-relay/"
+```
+
+在全局 `opencode.jsonc` 的 `plugin` 数组注册 `./plugins/session-relay`，重启桌面版生效。
+
+## 编排示例
+
+模型在长任务中决定交接，直接调用工具：
+
+```
+spawn_session({
+  prompt: `你是本任务的接手会话。先读取交接文书：
+E:\\proj\\handoff\\migration-3.md
+通读后复述要点（已完成/未完成/下一步第 1 件事），确认后继续执行。`,
+  title: "[迁移] 第 3 棒"
+})
+```
+
+或人工在会话里发：
+
+```
+@spawn 读取 handoff/migration-3.md 后继续迁移任务
+```
+
+## 开发与测试
+
+```bash
+npm install          # 安装 devDependency @opencode-ai/plugin（唯一依赖，仅测试用）
+node test/test.mjs   # 12 用例 / 39 断言
+```
+
+- `test/test.mjs` 默认经相对路径 `../index.js` 测项目版；环境变量 `RELAY_MAIN` 覆盖为其他路径（如生产活实例）。生产版从 `.config/opencode/node_modules` 解析 `@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`。
+
+## 历史
+
+前身 `opencode-session-relay` 的接力链、两阶段交接文书、空闲事件驱动、哨兵兜底、`@relay status/leave/refresh/verify` 等机制已全部移除，仅保留「建会话 + 注入语句」这一核心原语。

package/index.js

@@ -0,0 +1,136 @@
+import { tool } from "@opencode-ai/plugin/tool";
+
+/**
+ * session-spawn —— 会话生成原语（v2.0.0，2026-09-12 卍解简化定稿）
+ *
+ * 只做一件事：创建一个新的顶层会话，并把起始语句注入为该会话首条消息。
+ *   create: client.session.create({ body: { title } })
+ *   inject: client.session.promptAsync({ path: { id }, body: { parts: [{ type: "text", text }] } })
+ *
+ * 设计约束（用户定稿）：
+ *   - 插件只负责「建会话 + 注入语句」，不落文书、不读文书、不追踪链、无状态文件。
+ *   - 编排中若需交接文书，由调用方把「读取文书路径」等引导写进起始语句即可（与其他工具天然兼容）。
+ *   - 优先 promptAsync（异步 fire-and-forget，不阻塞父会话）；缺失则回退同步 prompt。
+ *   - 两个入口共用同一 spawn()：① 工具 spawn_session（模型自主触发，打通无人值守）
+ *                                        ② 命令 @spawn / @relay spawn（人工触发）。
+ *
+ * 历史：本仓库前身 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(" ");
+}
+
+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}`);
+    }
+  };
+
+  // 核心：建新会话 + 注入起始语句。
+  // 返回 { id, title, injected, error? }；create 失败则抛出（未建会话）。
+  async function spawn(prompt, title) {
+    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 created = await client.session.create({ body: { title: t } });
+    const id = created && (created.data?.id || created.id);
+    if (!id) throw new Error("create 未返回会话 id");
+
+    const body = { parts: [{ type: "text", 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 { id, title: t, injected: false, error: "client.session.promptAsync/prompt 均不可用" };
+
+    try {
+      await injectFn({ path: { id }, body });
+      return { id, title: t, injected: true };
+    } catch (e) {
+      console.error(`[session-spawn] 注入失败（会话 ${id} 已建保留）: ${e.message}`);
+      return { id, title: t, injected: false, error: e.message };
+    }
+  }
+
+  return {
+    // 工具：模型自主调用 → 无人值守长任务编排的最短路径。
+    tool: {
+      spawn_session: tool({
+        description:
+          "创建一个新的顶层会话并向其注入起始语句，用于无人值守长任务编排：当前会话模型在需要时自行决定把工作交给一个新会话继续。新会话会立即开始执行该起始语句。若需让其读取某份交接文书，请把文书路径与读取要求写进 prompt。",
+        args: {
+          prompt: tool.schema.string().describe("注入新会话的起始语句（可内含读取交接文书路径等引导）"),
+          title: tool.schema.string().optional().describe("新会话标题；缺省取起始语句首行"),
+        },
+        async execute(args) {
+          try {
+            const r = await spawn(args.prompt, args.title);
+            if (!r.injected) {
+              return `会话「${r.title}」(id=${r.id}) 已创建，但起始语句注入失败：${r.error}。请手动打开该会话补发指令。`;
+            }
+            return `已创建会话「${r.title}」(id=${r.id}) 并注入起始语句，新会话已开始执行。`;
+          } catch (e) {
+            return `创建会话失败：${e.message}`;
+          }
+        },
+      }),
+    },
+
+    // 人工命令：@spawn <起始语句>（兼容 @relay spawn）。
+    "chat.message": async ({ sessionID }, { parts }) => {
+      try {
+        const text = userText(parts);
+        const m = /^\s*@(?:relay\s+)?spawn\b([\s\S]*)$/i.exec(text);
+        if (!m) return;
+        const prompt = m[1].trim();
+        if (!prompt) {
+          await notify("spawn", "用法：@spawn <起始语句>", "warning");
+          return;
+        }
+        try {
+          const r = await spawn(prompt);
+          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": "2.0.0",
+  "type": "module",
+  "description": "opencode 会话生成原语：创建新顶层会话并注入起始语句，用于无人值守长任务编排（工具 spawn_session + 命令 @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": "https://github.com/Qiu-Kejian/opencode-session-relay.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.1.36"
+  }
+}