opencode-superagent 0.1.0 → 0.2.1

package/README.md

@@ -85,6 +85,14 @@ opencode plugin add opencode-superagent
 
 4. 重启 TUI，确认插件加载成功。
 
+### 升级与重启（不支持热加载）
+
+插件没有热加载：改完 `src/` / `server.ts` 或换掉 npm 包版本后，必须**重启 OpenCode 网关**（`opencode service restart`，本仓库可用 `sh restart-service.sh`）才会加载新代码；只重启 TUI 或重开窗口不会更新后台服务。
+
+- 启动日志会打印一行 `superagent <version> loaded; restart the OpenCode gateway after upgrading (no hot reload)`，只含版本号，不含路径、配置、token 或会话信息。
+- `status` 工具输出的首行、以及 `status` RPC 的 `version` 字段，都会给出当前**已加载**的插件版本；升级后这里若还是旧版本，说明网关没重启。
+- 排查顺序：日志里的版本 → `status` 首行 → `opencode service status`。三者一致仍行为异常时，再怀疑代码本身。
+
 ## 使用
 
 - 输入 `/superagent`（或在命令面板执行 `Superagent`）：通过 RPC 创建/获取 Router 会话并跳转过去。
@@ -130,6 +138,7 @@ Router 的 system prompt 里只有短摘要（Inline）：worker 数量、pendin
 | 工具                                                                                                           | 用途                                                                                                           |
 | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
 | `dispatch`                                                                                                     | 派活给后台 Worker，可并行多次调用                                                                              |
+| `sleep({ seconds? })`                                                                                          | 暂停 Router 指定秒数（默认 30，范围 1..600 的整数），Goal 模式下 dispatch 后给 Worker 执行时间；真实定时器，不忙等 |
 | `ticket_create({ threadID, title, objective, acceptance, directory, priority?, parentTicketID?, dedupeKey? })` | 建工单：`objective`/`acceptance`(1-10 条)/`directory` 必填，同 thread 同 dedupeKey 自动复用（reused=true）     |
 | `ticket_list({ threadID?, status?, since?, limit? })`                                                          | 按 thread/状态/更新时间列工单（默认 20 条，上限 100），含 id/state/title/priority/更新时间/worker              |
 | `ticket_update({ ticketID, status?, note? })`                                                                  | 按状态机推进工单（open→in_progress→blocked/done/failed/cancelled/superseded），非法迁移报错                    |
@@ -140,7 +149,8 @@ Router 的 system prompt 里只有短摘要（Inline）：worker 数量、pendin
 | `report_read({ sessionID, offset?, limit? })`                                                                  | 按字符区间读取 Worker 结束报告的**完整全文**（默认 4000 字/页，上限 20000），返回总长度与 nextOffset           |
 | `abort_session({ sessionID?, reason?, all?, stale? })`                                                         | 终止/清理 Worker：中断、等待终态、标记 `aborted`、解除 thread 亲和（见下）                                     |
 
-- 只有 Router 能调这些工具（`ticket_*`、`thread_detail`/`worker_detail`/`report_read`/`abort_session` 复用 `status` 的权限位，Router 会话已放行；其他会话直调会被拒绝）。
+- 只有 Router 能调这些工具（`dispatch`、`sleep`、`ticket_*`、`thread_detail`/`worker_detail`/`report_read`/`abort_session` 复用 `status` 的权限位，Router 会话已放行；其他会话直调会被拒绝）。
+- `sleep` 是 Goal 模式的节流阀：dispatch 之后暂停 Router（默认 30 秒，1..600 的整数，非法值直接报错），用 `Effect.sleep` 真实定时器等待，期间其他任务照常推进，不会忙等。它是 Router-only 工具：Worker 会话的工具列表里没有它，直调也会被 `guard` 拒绝。
 - Router 会话的权限位由 `src/tools.ts` 的目录派生（`ROUTER_PERMISSIONS`）：新增工具必须在 spec 里声明 `permission`，`Tool.snapshot` 会按该权限位过滤，漏声明会让工具从模型可见列表里消失。
 - 所有 Spill 输出都是紧凑文本，`thread_detail`/`worker_detail` 单次总长度控制在 6000 字内，超出截断并注明；`report_read` 按页返回（默认 4000 字/页）。
 - trigger 历史持久化在 KV（`trigger:<id>`，含全文、route、sessionID）：排队事件入队即记（全文，内存同步+KV 异步），flush 后补 `route=router`；直投 Worker 的事件由 prompt 钩子补记（文本与 Worker 可见格式一致）。hydrate 只加载最近 200 条（按 createdAt 倒序），`triggerTotal` 记总数。
@@ -154,8 +164,8 @@ Router 的 system prompt 里只有短摘要（Inline）：worker 数量、pendin
 - 去重：`dedupeKey` 缺省为 `sha1(source + threadID + 归一化 objective)`，建单前在同 thread 找 `open/in_progress` 的同键单，命中则返回原单并标 `reused=true`。
 - authorization：自动取 Router 最近一次被投递的 trigger（`triggerID` + 原文摘要 ≤300 字），所以每张单都能追溯「用户当时怎么说的」。
 - 存储：`ticket:<id>` 存全量记录；`ticketidx:status:<state>`、`ticketidx:thread:<threadID>`、`ticketidx:all` 是按 createdAt 倒序的派生索引（各截断 200 项）。hydrate 扫 `ticket:` 前缀重建内存与索引，索引丢失不会丢单；历史 Worker 不回填工单。
-- 强制：`dispatch` 的 `ticketID` 必填（工具与 RPC 同一实现）。缺失、单据不存在、单据已关闭（非 `open/in_progress`）、`threadID` 与单据不符、或单据已绑定运行中的 Worker，一律拒绝并给出可操作提示；RPC 直达同样被拦。
-- 联动：派发成功即原子绑定——写入 `workerSessionID`、`attempts` 追加一条、`state → in_progress`；绑定失败会回滚新建的 Worker 会话（不会出现「Worker 起来了但单没绑上」）。Worker prompt 头部附「工单 + objective + acceptance」；Worker `done/failed` 由 watcher 结单，`abort_session` 与 watchdog 置 `failed`（note=aborted / stalled）。
+- 强制：`dispatch` 的 `ticketID` 必填，工单门禁只作用于 **Router 的工具调用**——工具拿得到宿主的 `context.sessionID`，能证明调用方就是 Router。RPC 的 `dispatch` / `stop` 属于 fail-closed：RPC 上下文里没有调用方身份，伪造 `caller`/`routerID` 也没用，所以两者一律以 `dispatch.rejected` / `stop.rejected` 拒绝（`dispatch` 不会建会话、`stop` 不会中断 Worker），见下面「RPC 接口」。工具路径上的拒绝规则：缺失单据、单据不存在、单据已关闭（非 `open/in_progress`）、`threadID` 与单据不符、或单据已绑定运行中的 Worker，都会给出可操作提示。
+- 联动：派发成功即原子绑定——写入 `workerSessionID`、`attempts` 追加一条、`state → in_progress`；绑定失败会回滚新建的 Worker 会话（不会出现「Worker 起来了但单没绑上」）。Worker prompt 头部附「工单 + objective + acceptance」；Worker `done/failed` 由 watcher 结单，`abort_session` 关闭为 `failed`；watchdog 只告警，不改状态也不结单。
 
 ## 侧栏工单面板
 
@@ -231,8 +241,9 @@ context.ui.slot({ append: "sidebar.content", render: () => <SidebarTickets conte
   - `stale: true`：只清理 `done`/`failed`/`idle`/`aborted` 的记录，不中断运行中的 Worker。
   - `all: true`：全部 Worker 都终止，运行中的先中断。
 - 单个终止的校验顺序：调用者自身 → Router 会话 → 必须是 superagent 记录的 Worker；用户手动会话、未知 sessionID 一律拒绝（不会误删用户会话）。
-- 运行中的 Worker：先 `session.interrupt`（优雅中断，`resume: false`，不重放队列），再 `session.wait` 等终态，超时 `ABORT_TIMEOUT_MS = 10s`（超时也会标记 `aborted` 并在结果里注明 `settle-timeout`）。
-- 已结束的 Worker（`done`/`failed`/`idle`，或 `time.busy` 不新于 `time.idle`）：不发中断信号，只做清理语义，返回 `already-ended`。
+- 所有存在的 Worker：无条件先 `session.interrupt`（未运行视为无害 no-op，但会清掉排队中的 prompt，避免 abort 返回后它才开始）。
+- 运行中的 Worker：再 `session.wait` 等终态，超时 `ABORT_TIMEOUT_MS = 10s`（超时也会标记 `aborted` 并在结果里注明 `settle-timeout`）。
+- 已结束的 Worker（`done`/`failed`/`idle`，或 `time.busy` 不新于 `time.idle`）：不等待，返回 `already-ended`；若 interrupt 清掉了排队 prompt，`lastReport` 记 `interrupted queued prompt`。
 - KV 变更（`worker:<sessionID>`）：`state` 置为 `aborted`，`lastReport` 前缀 `aborted (<reason>) [<detail>]`（保留旧 report），`updatedAt` 刷新；**记录保留**，不删除，便于追溯。
 - thread 亲和：从 `thread:<threadID>` 的 `workers` 列表移除该会话（列表空则删除该键），后续消息不再投给它；该 thread 没有其它可用 Worker 时，下条消息回落 Router 重新 `dispatch`。Worker 记录里的 `threads` 保留用于追溯。
 - 竞态保护：`state` 在中断**之前**就置为 `aborted`，`watcher.ts` 的 `handleEnded`/`session.idle` 会跳过 `aborted`，避免中断落地时被改回 `idle`/`done` 或重复向 Router 报“已完成”。
@@ -261,6 +272,7 @@ context.ui.slot({ append: "sidebar.content", render: () => <SidebarTickets conte
 .                              # 仓库根即本包
 ├── tui.tsx                      # TUI 入口：keymap、slash 命令、RPC 调用、侧栏工单面板
 ├── src/protocol.ts              # 服务端 RPC 契约（由服务端实现提供）
+├── src/version.ts               # 从 package.json 读插件版本（带 fallback），生成启动/status 的版本提示
 ├── src/ticket-view.ts           # 侧栏面板的纯视图模型：解析 tickets 文本、排序、按 cell 截断
 ├── src/agents.ts                # Router/Worker agent 的程序化注册（插件 setup 调用）
 ├── src/                          # 服务端 Router/Worker/批处理实现
@@ -275,13 +287,15 @@ context.ui.slot({ append: "sidebar.content", render: () => <SidebarTickets conte
 └── README.md
 ```
 
-TUI 侧只依赖 `src/protocol.ts` 导出的 `Definition`（`id: "opencode.superagent"`）与 `src/tools.ts` 的工具目录（`/tools` 直接渲染它，不发 RPC），当前使用六个方法：
+TUI 侧只依赖 `src/protocol.ts` 导出的 `Definition`（`id: "opencode.superagent"`）与 `src/tools.ts` 的工具目录（`/tools` 直接渲染它，不发 RPC）。服务端注册的就是同一个 `Definition` 对象（`server.ts` 的 `ServerDefinition = Definition`），所以方法、入参/出参和声明错误两边不会漂移。TUI 实际调用六个方法：
 
 - `router({}) -> { sessionID }`：创建或返回 Router 会话。
-- `status({}) -> { router?, pending, workers }`：查看 Router 与各 Worker 的 thread 归属，演示命令用它等待 `T-1` 的 Worker 就绪。
+- `status({}) -> { version?, router?, pending, workers }`：`version` 是当前网关加载的插件版本（启动日志里也有），Router 尚未创建时不带 `router` 字段；演示命令用它等待 `T-1` 的 Worker 就绪。
 - `trigger({ source, threadID, author?, text, title?, createdAt?, id? }) -> { route, sessionID? }`：注入一条事件，`route` 为 `router` / `worker` / `dropped`。
 - `abort({ sessionID?, reason?, all?, stale? }) -> { text }`：终止/清理 Worker，被拒绝时抛 `abort.rejected`（带可读 message）。TUI 的 `/abort`（或命令面板 “Superagent abort worker”）会列出 Worker 供选择，首项是“清理全部已结束 worker”。
-- `tickets({ threadID?, status?, limit? }) -> { text }` / `ticket({ ticketID }) -> { text }`：渲染工单列表（按状态分组，窄终端友好）与单张工单的详情；对应 `/tickets` 与 `/ticket <id>`。
+- `tickets({ threadID?, status?, limit? }) -> { text }` / `ticket({ ticketID }) -> { text }`：渲染工单列表（按状态分组，窄终端友好）与单张工单的详情；对应 `/tickets` 与 `/ticket <id>`。`status` 是闭合枚举，传非法值（如 `DONE`、拼写错误）会直接被协议校验拒绝，不会退化成“不过滤的完整列表”；服务端另有 `tickets.invalid_status` 作为第二道防线。
+
+契约里还声明了 `dispatch` 与 `stop`：两者只给 Router 的工具使用，**RPC 调用一律 fail-closed**。RPC 传输层不提供调用方 session（`RpcCallContext` 只有 `error`），入参里的 `caller`/`routerID` 可伪造（router id 在 `status` 里公开），因此 `dispatch` 固定返回 `dispatch.rejected`、`stop` 固定返回 `stop.rejected`，既不会建 Worker 也不会中断 Worker。这两个错误与其他方法一样声明在共享 `Definition` 里，server 与 TUI 读同一份定义；真正的 Router 通过工具干活，工具的 `context.sessionID` 由宿主提供，是唯一被信任的身份来源。
 
 ## 已知限制与下一步
 
@@ -328,7 +342,7 @@ npm pack --dry-run     # 预览 tarball（prepack/prepare 会各跑一次 build
 
 - **检查间隔**：插件 scope 内 `Stream.tick` 每 60 秒跑一次（`src/watchdog.ts` 的 `WATCHDOG_INTERVAL_MS`），可用插件选项 `watchdogIntervalMs`（毫秒）覆盖。
 - **停滞定义**：`state` 为 `running` 的 Worker，若其会话 `time.busy` 比当前早超过 30 分钟（`STALL_TIMEOUT_MS`，可用 `stallTimeoutMs` 覆盖），且 `time.idle` 没有新于 `busy` 的更新（执行期间 `idle` 只保留上一次执行的结束时间），视为停滞。
-- **只告警不自动杀**：停滞后向 Router 注入一条 delivery `queue` 的提示（`Worker <sid>（<title>）已停滞 <N> 分钟，建议：stop 后重派或人工介入`），并把该 Worker 记为 `failed`（`lastReport` 前缀 `watchdog: stalled <N>m`）。不 interrupt，避免误杀长任务。
+- **只告警不自动杀**：停滞后向 Router 注入一条 delivery `queue` 的提示（`Worker <sid>（<title>）已停滞 <N> 分钟，建议：stop 后重派或人工介入`）。不修改 Worker 的 `state`/`lastReport`，不结单，也不 interrupt；同一繁忙窗口只告警一次，避免误杀长任务和重复刷屏。
 - **单轮错误隔离**：单个 Worker 检查失败只 `logWarning` 并继续下一个；整轮失败也只告警，循环永不退出。
 - **pending 队列崩溃恢复**：入队时同步写 KV（键前缀 `pending:`，纯 JSON），flush 成功后删除该键；setup 时从 KV 读回未 flush 的 trigger 重新入内存队列（不自动建 Router，等下一次 `router` RPC 或新 trigger 时再 flush）。同一 id 重复入队会被去重。
-- **status 无 Router**：Router 尚未创建时 `status` 返回 `{pending, workers}` 且不含 `router` 字段（显式 `undefined` 会导致输出校验失败，故直接省略该键）。
+- **status 无 Router**：Router 尚未创建时 `status` 返回 `{version, pending, workers}` 且不含 `router` 字段（显式 `undefined` 会导致输出校验失败，故直接省略该键）。`version` 始终存在，是当前网关加载的插件版本。

package/dist/server.d.ts

@@ -1,3 +1,240 @@
 import { Plugin } from "@opencode/plugin/effect";
+import type { RpcHandlers } from "@opencode/plugin/effect/rpc";
+/**
+ * The RPC surface this server registers. It is the shared `Definition` object
+ * itself, not a copy: `stop.rejected` and `dispatch.rejected` live in
+ * `src/protocol.ts`, which is also what the TUI imports, so the server and the
+ * TUI can never advertise different errors.
+ */
+export declare const ServerDefinition: {
+    readonly id: "opencode.superagent";
+    readonly methods: {
+        router: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
+            output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+            }, {
+                readonly sessionID: string;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+            }>;
+        };
+        status: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
+            output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly version?: string | undefined;
+                readonly router?: string | undefined;
+                readonly pending: number;
+                readonly workers: readonly {
+                    readonly sessionID: string;
+                    readonly title?: string | undefined;
+                    readonly threads: readonly string[];
+                    readonly state: "aborted" | "done" | "failed" | "idle" | "running";
+                }[];
+            }, {
+                readonly version?: string | undefined;
+                readonly router?: string | undefined;
+                readonly pending: number;
+                readonly workers: readonly {
+                    readonly sessionID: string;
+                    readonly title?: string | undefined;
+                    readonly threads: readonly string[];
+                    readonly state: "aborted" | "done" | "failed" | "idle" | "running";
+                }[];
+            }> & import("effect/Schema").Struct<{
+                readonly version: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly router: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly pending: import("effect/Schema").Number;
+                readonly workers: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                    readonly sessionID: import("effect/Schema").String;
+                    readonly title: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                    readonly threads: import("effect/Schema").$Array<import("effect/Schema").String>;
+                    readonly state: import("effect/Schema").Literals<readonly ["running", "idle", "failed", "done", "aborted"]>;
+                }>>;
+            }>;
+        };
+        tickets: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly threadID?: string | undefined;
+                readonly status?: "blocked" | "cancelled" | "done" | "failed" | "in_progress" | "open" | "superseded" | undefined;
+                readonly limit?: number | undefined;
+            }, {
+                readonly threadID?: string | undefined;
+                readonly status?: "blocked" | "cancelled" | "done" | "failed" | "in_progress" | "open" | "superseded" | undefined;
+                readonly limit?: number | undefined;
+            }> & import("effect/Schema").Struct<{
+                readonly threadID: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly status: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["open", "in_progress", "blocked", "done", "failed", "cancelled", "superseded"]>>;
+                readonly limit: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
+            }>;
+            output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly text: string;
+            }, {
+                readonly text: string;
+            }> & import("effect/Schema").Struct<{
+                readonly text: import("effect/Schema").String;
+            }>;
+            errors: {
+                "tickets.invalid_status": import("effect/StandardSchema").StandardSchemaV1<{
+                    readonly status: string;
+                }, {
+                    readonly status: string;
+                }> & import("effect/Schema").Struct<{
+                    readonly status: import("effect/Schema").String;
+                }>;
+            };
+        };
+        ticket: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly ticketID: string;
+            }, {
+                readonly ticketID: string;
+            }> & import("effect/Schema").Struct<{
+                readonly ticketID: import("effect/Schema").String;
+            }>;
+            output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly text: string;
+            }, {
+                readonly text: string;
+            }> & import("effect/Schema").Struct<{
+                readonly text: import("effect/Schema").String;
+            }>;
+        };
+        dispatch: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly task: string;
+                readonly title?: string | undefined;
+                readonly threadID?: string | undefined;
+                readonly agent?: string | undefined;
+                readonly directory?: string | undefined;
+                readonly ticketID: string;
+            }, {
+                readonly task: string;
+                readonly title?: string | undefined;
+                readonly threadID?: string | undefined;
+                readonly agent?: string | undefined;
+                readonly directory?: string | undefined;
+                readonly ticketID: string;
+            }> & import("effect/Schema").Struct<{
+                readonly task: import("effect/Schema").String;
+                readonly title: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly threadID: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly agent: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly directory: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly ticketID: import("effect/Schema").String;
+            }>;
+            output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+            }, {
+                readonly sessionID: string;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+            }>;
+            errors: {
+                "dispatch.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
+            };
+        };
+        trigger: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly id?: string | undefined;
+                readonly source: string;
+                readonly threadID: string;
+                readonly author?: string | undefined;
+                readonly text: string;
+                readonly title?: string | undefined;
+                readonly createdAt?: number | undefined;
+            }, {
+                readonly id?: string | undefined;
+                readonly source: string;
+                readonly threadID: string;
+                readonly author?: string | undefined;
+                readonly text: string;
+                readonly title?: string | undefined;
+                readonly createdAt?: number | undefined;
+            }> & import("effect/Schema").Struct<{
+                readonly id: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly source: import("effect/Schema").String;
+                readonly threadID: import("effect/Schema").String;
+                readonly author: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly text: import("effect/Schema").String;
+                readonly title: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly createdAt: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
+            }>;
+            output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly route: "dropped" | "router" | "worker";
+                readonly sessionID?: string | undefined;
+            }, {
+                readonly route: "dropped" | "router" | "worker";
+                readonly sessionID?: string | undefined;
+            }> & import("effect/Schema").Struct<{
+                readonly route: import("effect/Schema").Literals<readonly ["router", "worker", "dropped"]>;
+                readonly sessionID: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+            }>;
+        };
+        stop: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+            }, {
+                readonly sessionID: string;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+            }>;
+            output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly interrupted: boolean;
+            }, {
+                readonly interrupted: boolean;
+            }> & import("effect/Schema").Struct<{
+                readonly interrupted: import("effect/Schema").Boolean;
+            }>;
+            errors: {
+                "stop.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
+            };
+        };
+        abort: {
+            input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID?: string | undefined;
+                readonly reason?: string | undefined;
+                readonly all?: boolean | undefined;
+                readonly stale?: boolean | undefined;
+            }, {
+                readonly sessionID?: string | undefined;
+                readonly reason?: string | undefined;
+                readonly all?: boolean | undefined;
+                readonly stale?: boolean | undefined;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly reason: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                readonly all: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
+                readonly stale: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
+            }>;
+            output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly text: string;
+            }, {
+                readonly text: string;
+            }> & import("effect/Schema").Struct<{
+                readonly text: import("effect/Schema").String;
+            }>;
+            errors: {
+                "abort.rejected": import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
+            };
+        };
+    };
+    readonly events: {};
+};
+type ServerRpcHandlers = RpcHandlers<typeof ServerDefinition>;
+/**
+ * Router-only RPC methods are rejected unconditionally.
+ *
+ * The RPC transport does not expose a caller identity: `RpcCallContext` only
+ * carries `error`. The old handler therefore passed `store.routerID` as
+ * `runDispatch`'s caller, which let every RPC client act as the router. Input
+ * fields such as `caller` / `routerID` are just as forgeable (and the router
+ * id is public in `status`), so they are never used as proof of identity.
+ * Until the host exposes the calling session on the RPC context, the safe
+ * behavior is to keep router-only effects off the RPC surface. The real
+ * router still works through its tools, whose `context.sessionID` is
+ * authoritative and is checked by `runDispatch` / `runAbort`.
+ */
+export declare const rejectedRouterRpc: Pick<ServerRpcHandlers, "dispatch" | "stop">;
 declare const _default: Plugin.Plugin<import("effect/Scope").Scope>;
 export default _default;

package/dist/server.js

@@ -1,20 +1,22 @@
-import { Plugin } from "@opencode/plugin/effect";
+import { Plugin, Rpc } from "@opencode/plugin/effect";
 import { Effect } from "effect";
 import { registerAbort, runAbort } from "./src/abort.js";
 import { registerAgents } from "./src/agents.js";
 import { registerContext } from "./src/context.js";
 import { hydrateDirs } from "./src/dirs.js";
-import { registerTools, runDispatch } from "./src/dispatch.js";
+import { registerTools } from "./src/dispatch.js";
 import { formatTrigger } from "./src/format.js";
 import { Definition } from "./src/protocol.js";
 import { hydrateReports } from "./src/report.js";
 import { ensureRouter, enqueuePending, flushPending, hydratePending, registerRouterIdle } from "./src/router.js";
 import { hydrateSessionMeta } from "./src/session-meta.js";
+import { registerSleep } from "./src/sleep.js";
 import { hydrate, store, toSessionID } from "./src/state.js";
 import { hydrateTickets, TICKET_STATES } from "./src/ticket.js";
 import { registerTicketTools, renderTicketText, renderTicketsText } from "./src/ticket-tools.js";
 import { registerWatcher } from "./src/watcher.js";
 import { registerWatchdog } from "./src/watchdog.js";
+import { pluginVersion, versionNotice } from "./src/version.js";
 const runTrigger = Effect.fn("superagent.runTrigger")(function* (ctx, input) {
     const sources = ctx.options.sources;
     if (Array.isArray(sources) && !sources.includes(input.source))
@@ -53,26 +55,48 @@ const runTrigger = Effect.fn("superagent.runTrigger")(function* (ctx, input) {
         yield* flushPending(ctx);
     return { route: "router", sessionID: routerID };
 });
-const runStop = Effect.fn("superagent.runStop")(function* (ctx, sessionID) {
-    if (!store.workers.has(sessionID))
-        return { interrupted: false };
-    const result = yield* ctx.session
-        .interrupt({ sessionID: toSessionID(sessionID) })
-        .pipe(Effect.catch(() => Effect.succeed({ interrupted: false })));
-    return { interrupted: result.interrupted };
-});
+/**
+ * The RPC surface this server registers. It is the shared `Definition` object
+ * itself, not a copy: `stop.rejected` and `dispatch.rejected` live in
+ * `src/protocol.ts`, which is also what the TUI imports, so the server and the
+ * TUI can never advertise different errors.
+ */
+export const ServerDefinition = Definition;
+/**
+ * Router-only RPC methods are rejected unconditionally.
+ *
+ * The RPC transport does not expose a caller identity: `RpcCallContext` only
+ * carries `error`. The old handler therefore passed `store.routerID` as
+ * `runDispatch`'s caller, which let every RPC client act as the router. Input
+ * fields such as `caller` / `routerID` are just as forgeable (and the router
+ * id is public in `status`), so they are never used as proof of identity.
+ * Until the host exposes the calling session on the RPC context, the safe
+ * behavior is to keep router-only effects off the RPC surface. The real
+ * router still works through its tools, whose `context.sessionID` is
+ * authoritative and is checked by `runDispatch` / `runAbort`.
+ */
+export const rejectedRouterRpc = {
+    dispatch: (_input, context) => Effect.fail(context.error("dispatch.rejected", "dispatch is only available to the router session; RPC callers cannot prove that identity — use the router's dispatch tool", {})),
+    stop: (_input, context) => Effect.fail(context.error("stop.rejected", "stop is only available to the router session; RPC callers cannot prove that identity — use abort_session from the router", {})),
+};
 export default Plugin.define({
     id: "opencode.superagent",
     effect: Effect.fn(function* (ctx) {
+        // Version only: no paths, options or tokens. Makes a stale gateway obvious
+        // in the log right after an upgrade (the plugin has no hot reload).
+        yield* Effect.logInfo(versionNotice());
+        // Tickets first: hydrating workers reconciles finished `running` records
+        // and closes their tickets, so the ticket store must already be loaded.
+        yield* hydrateTickets(ctx);
         yield* hydrate(ctx);
         // Before any session work: the Router and Worker sessions resolve their agent by id.
         yield* registerAgents(ctx);
         yield* hydratePending(ctx);
         yield* hydrateDirs(ctx);
         yield* hydrateSessionMeta(ctx);
-        yield* hydrateTickets(ctx);
         yield* hydrateReports(ctx);
         yield* registerTools(ctx);
+        yield* registerSleep(ctx);
         yield* registerTicketTools(ctx);
         yield* registerAbort(ctx);
         yield* registerContext(ctx);
@@ -80,9 +104,12 @@ export default Plugin.define({
         yield* registerWatcher(ctx);
         yield* registerWatchdog(ctx);
         yield* ctx.rpc
-            .register(Definition, {
+            .register(ServerDefinition, {
             router: () => ensureRouter(ctx).pipe(Effect.map((sessionID) => ({ sessionID })), Effect.catch((cause) => Effect.logWarning("superagent router handler failed", { cause }).pipe(Effect.andThen(Effect.die(new Error("superagent router is unavailable")))))),
             status: () => Effect.sync(() => ({
+                // Reported alongside the runtime state so the TUI/diagnostics can
+                // show which plugin build the gateway actually loaded.
+                version: pluginVersion(),
                 // Omit the key entirely when no router exists: an explicit
                 // `undefined` value fails output validation.
                 ...(store.routerID === undefined ? {} : { router: store.routerID }),
@@ -94,20 +121,25 @@ export default Plugin.define({
                     state: worker.state,
                 })),
             })),
-            tickets: (input) => Effect.sync(() => renderTicketsText({
-                ...(input.threadID === undefined ? {} : { threadID: input.threadID }),
-                ...(input.status === undefined || !TICKET_STATES.includes(input.status)
-                    ? {}
-                    : { status: input.status }),
-                ...(input.limit === undefined ? {} : { limit: input.limit }),
-            })).pipe(Effect.map((text) => ({ text }))),
+            tickets: (input, context) => {
+                // The protocol literal already rejects unknown states with
+                // `rpc.invalid_input`; keep an explicit RPC error as a second line of
+                // defence so a bypassed/older client can never turn an unknown status
+                // into an unfiltered list.
+                if (input.status !== undefined && !TICKET_STATES.includes(input.status)) {
+                    return Effect.fail(context.error("tickets.invalid_status", `invalid ticket status: ${String(input.status)}`, {
+                        status: String(input.status),
+                    }));
+                }
+                return Effect.sync(() => renderTicketsText({
+                    ...(input.threadID === undefined ? {} : { threadID: input.threadID }),
+                    ...(input.status === undefined ? {} : { status: input.status }),
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                })).pipe(Effect.map((text) => ({ text })));
+            },
             ticket: (input) => Effect.sync(() => ({ text: renderTicketText(input.ticketID) })),
-            // RPC dispatches go through the same implementation as the tool, so
-            // the ticket gate (required ticketID, workable state, thread match, no
-            // running worker) cannot be skipped by calling the RPC directly.
-            dispatch: (input, context) => runDispatch(ctx, input, store.routerID ?? "").pipe(Effect.map((result) => result.output), Effect.catchTag("Tool.Error", (error) => Effect.fail(context.error("dispatch.rejected", error.message, {})))),
+            ...rejectedRouterRpc,
             trigger: (input) => runTrigger(ctx, input).pipe(Effect.catch((cause) => Effect.logWarning("superagent trigger handler failed", { cause }).pipe(Effect.as({ route: "dropped" })))),
-            stop: (input) => runStop(ctx, input.sessionID).pipe(Effect.catch((cause) => Effect.logWarning("superagent stop handler failed", { cause }).pipe(Effect.as({ interrupted: false })))),
             abort: (input, context) => runAbort(ctx, input).pipe(Effect.map((result) => ({ text: result.output.text })), Effect.catchTag("Tool.Error", (error) => Effect.fail(context.error("abort.rejected", error.message, {})))),
         })
             .pipe(Effect.orDie);

package/dist/src/abort.js

@@ -1,7 +1,7 @@
 import { Tool } from "@opencode/schema/tool";
-import { DateTime, Effect, Option, Schema } from "effect";
+import { Effect, Option, Schema } from "effect";
 import { requireRouter } from "./guard.js";
-import { encodeThread, saveWorker, store, threadKey, toSessionID } from "./state.js";
+import { encodeThread, isRunning, saveWorker, store, threadKey, toSessionID } from "./state.js";
 import { closeTicketsForWorker } from "./ticket.js";
 import { specFor, toolPermission } from "./tools.js";
 /** How long a terminating call waits for an interrupted worker to settle before reporting a timeout. */
@@ -13,14 +13,6 @@ export const AbortInput = Schema.Struct({
     stale: Schema.optionalKey(Schema.Boolean),
 });
 const AbortOutput = Schema.Struct({ text: Schema.String });
-/** A Session is running while `time.busy` is newer than the last completed execution's `time.idle`. */
-function isRunning(info) {
-    const busy = info.time.busy;
-    if (busy === undefined)
-        return false;
-    const idle = info.time.idle;
-    return idle === undefined || DateTime.toEpochMillis(busy) > DateTime.toEpochMillis(idle);
-}
 function abortNote(reason, detail, previous) {
     const head = `aborted${reason === undefined ? "" : ` (${reason})`} [${detail}]`;
     return previous === undefined ? head : `${head} | ${previous}`;
@@ -83,12 +75,15 @@ const abortWorker = Effect.fn("superagent.abortWorker")(function* (ctx, sessionI
         yield* saveWorker(ctx, worker);
         return { sessionID, status: "missing", interrupted: false, timedOut: false, threads };
     }
+    // Interrupt unconditionally: when the session is not executing this is a
+    // harmless no-op, but it still clears a prompt queued behind the previous
+    // execution so it cannot start after abort returned.
+    const interrupted = yield* ctx.session.interrupt({ sessionID: toSessionID(sessionID) }).pipe(Effect.map((result) => result.interrupted), Effect.catch((cause) => Effect.logWarning("superagent abort interrupt failed", { sessionID, cause }).pipe(Effect.as(false))));
     if (!running) {
-        worker.lastReport = abortNote(reason, "already ended", previous);
+        worker.lastReport = abortNote(reason, interrupted ? "interrupted queued prompt" : "already ended", previous);
         yield* saveWorker(ctx, worker);
-        return { sessionID, status: "already-ended", interrupted: false, timedOut: false, threads };
+        return { sessionID, status: "already-ended", interrupted, timedOut: false, threads };
     }
-    const interrupted = yield* ctx.session.interrupt({ sessionID: toSessionID(sessionID) }).pipe(Effect.map((result) => result.interrupted), Effect.catch((cause) => Effect.logWarning("superagent abort interrupt failed", { sessionID, cause }).pipe(Effect.as(false))));
     const settled = yield* ctx.session.wait({ sessionID: toSessionID(sessionID) }).pipe(Effect.timeoutOption(ABORT_TIMEOUT_MS), Effect.catch((cause) => Effect.logWarning("superagent abort wait failed", { sessionID, cause }).pipe(Effect.as(Option.some(undefined)))));
     const timedOut = Option.isNone(settled);
     const detail = timedOut ? "interrupted, settle timeout" : interrupted ? "interrupted" : "no active execution";

package/dist/src/context.d.ts

@@ -9,9 +9,16 @@ import { Effect } from "effect";
  */
 export declare function buildRecallInjection(threadID: string | undefined): string;
 /**
- * Router-only context hook: strip every tool outside the router set
- * (derived from the tool catalog in `src/tools.ts`),
- * then append the router prompt plus a short live status line.
+ * Narrow one request's toolset by session role. The Router keeps only the
+ * catalog tools; a tracked Worker loses every router-only tool (dispatch,
+ * sleep, tickets, recall, abort_session), so those tools are not listed to
+ * the worker model at all. User sessions are left untouched.
+ */
+export declare function filterSessionTools(sessionID: string, tools: Record<string, unknown>): void;
+/**
+ * Context hook: strip each session's toolset to what that role may see
+ * (Router: catalog only; Worker: catalog tools removed), then append the
+ * router prompt plus a short live status line for the Router.
  *
  * The status line carries the ticket counters and the current thread's
  * in-progress ticket ids/titles, so a follow-up can be linked back to an

package/dist/src/context.js

@@ -66,9 +66,25 @@ export function buildRecallInjection(threadID) {
     return clip(lines.map((line) => clip(line, perLine)).join("\n"), RECALL_BUDGET);
 }
 /**
- * Router-only context hook: strip every tool outside the router set
- * (derived from the tool catalog in `src/tools.ts`),
- * then append the router prompt plus a short live status line.
+ * Narrow one request's toolset by session role. The Router keeps only the
+ * catalog tools; a tracked Worker loses every router-only tool (dispatch,
+ * sleep, tickets, recall, abort_session), so those tools are not listed to
+ * the worker model at all. User sessions are left untouched.
+ */
+export function filterSessionTools(sessionID, tools) {
+    const router = store.routerID !== undefined && sessionID === store.routerID;
+    const worker = store.workers.has(sessionID);
+    if (!router && !worker)
+        return;
+    for (const name of Object.keys(tools)) {
+        if (router ? !ROUTER_TOOLS.has(name) : ROUTER_TOOLS.has(name))
+            delete tools[name];
+    }
+}
+/**
+ * Context hook: strip each session's toolset to what that role may see
+ * (Router: catalog only; Worker: catalog tools removed), then append the
+ * router prompt plus a short live status line for the Router.
  *
  * The status line carries the ticket counters and the current thread's
  * in-progress ticket ids/titles, so a follow-up can be linked back to an
@@ -76,12 +92,12 @@ export function buildRecallInjection(threadID) {
  */
 export const registerContext = Effect.fn("superagent.registerContext")(function* (ctx) {
     yield* ctx.session.hook("context", (event) => Effect.sync(() => {
-        if (store.routerID === undefined || event.sessionID !== store.routerID)
+        const router = store.routerID !== undefined && event.sessionID === store.routerID;
+        if (!router && !store.workers.has(event.sessionID))
+            return;
+        filterSessionTools(event.sessionID, event.tools);
+        if (!router)
             return;
-        for (const name of Object.keys(event.tools)) {
-            if (!ROUTER_TOOLS.has(name))
-                delete event.tools[name];
-        }
         const stats = ticketStats();
         const threadID = currentTrigger()?.threadID;
         const active = activeTicketSummary(threadID);

package/dist/src/dispatch.d.ts

@@ -17,6 +17,12 @@ interface DispatchInput {
     readonly directory?: string;
     readonly ticketID: string;
 }
+/**
+ * Compact status text for the `status` tool and its diagnostics readers.
+ * Starts with the plugin version so a stale gateway (code upgraded but not
+ * restarted) is visible from the first line instead of guessed from behavior.
+ */
+export declare function statusText(): string;
 /**
  * The one dispatch implementation, shared by the `dispatch` tool and the
  * `dispatch` RPC. Both paths pass the same ticket gate: `ticketID` is required