dsh-wake-relay 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LittleCodeSauce
+
+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.en.md

@@ -0,0 +1,206 @@
+# dsh-wake-relay
+
+Let any external process wake a DeepSeek Harness session — build watchers, job runners, CI callbacks, scrapers, backup scripts, phone-push relays. Anything that can send one HTTP POST.
+
+The point is not "wake an agent". Schedulers and hook plugins already do that. The point is **what happens when the wake cannot be delivered right now**:
+
+```
+200  -> delivered AND flushed. Done.
+429  -> dropped by policy (duplicate / cooldown / burst). Do not retry.
+503  -> nothing was recorded. Retry later with the SAME event_id.
+```
+
+That is the whole contract. Because 503 means *nothing happened* — no dedupe entry, no rate-limit hit — a retry with the same `event_id` is safe by construction, and the caller can own the retry loop without guessing whether a timeout meant "delivered" or "not delivered".
+
+## Where the probe runs
+
+Every other wake plugin puts the timer inside the host process. Host exits (upgrade, crash, you closed it) and probing stops with it — a condition that becomes true *and then false* during that window is gone forever.
+
+This one splits the two halves:
+
+```
+external process (yours)                       host process (this plugin)
+  probe every 30s                                verify token
+  condition true -> append to local queue        dedupe + per-reason limits
+  POST /wake (idempotent event_id)  ──────────▶  resolveAgent -> followup -> flush
+  503 -> stays queued, retried until ttl  ◀────  200 only after flush
+```
+
+Two processes, two independent restart cycles:
+
+- Host down → the watcher keeps sampling, events queue, and they are delivered when the host returns.
+- Watcher down → the plugin is unaffected; already-queued wakes still deliver.
+- Both down → events wait on the watcher's disk queue until `ttl_s` expires.
+
+The cost of this split is that you need a resident external process. `watcher/` is one, but any script will do.
+
+## Compared to in-host probe plugins
+
+| | This | In-host probes (dsh-sentinel et al.) |
+|---|---|---|
+| Where the probe runs | external process | inside the host |
+| Host is down | still sampling, queueing, retrying | nothing is probed |
+| Condition vocabulary | any command exit code + JSON field assertions | fixed sensor types, mostly "did it change" |
+| Failure semantics | 503 + nothing recorded, idempotent retry | internal requeue |
+| UI | none (`GET /status` + log) | dock panel / dashboard |
+| Multiple instances | falls back to an ephemeral port | lease-based leader election |
+| Windows process probe | native `OpenProcess` | usually `pgrep` (unavailable) |
+
+No UI is a deliberate choice: this plugin's user is a script.
+
+## Install
+
+```bash
+dsh plugin --profile desktop add dsh-wake-relay     # from npm
+dsh plugin --profile <your-profile> add ./dsh-wake-relay   # from a local clone
+```
+
+Restart DSH afterwards — the plugin tree is composed at process start.
+
+### Two traps you only hit while installing
+
+**1. Bundle entry ids must be globally unique.** Enable/disable state is persisted per entry id in the profile's `cordis.patch.yml`:
+
+```yaml
+- id: wake-bridge
+  disabled: true
+```
+
+If another bundle's patch inserts the same id, it is swallowed silently — no error, no warning. The only reliable way to tell whether it loaded is to look for its runtime artifacts: a fresh `port` in `wake-endpoint.json`, a new `listening` line in `wake-bridge.log`, a generated `wake-bridge-secret.json`. `install_bundle` returns `applied` even when nothing loaded.
+
+**2. An empty `sessionId` is a valid setup that will not answer a bare curl.** Requests must then carry `session`, or you get `503 no_session_bound`. The startup log says which state you are in:
+
+```
+listening on 127.0.0.1:45871 — NO default session bound: every /wake request must carry "session"
+```
+
+Pin `sessionId` in `cordis.patch.yml`, or pass `session` on every request.
+
+> Installing from a local directory links the package (`pnpm link:`), and the linked copy cannot resolve host packages from the workspace root → `ERR_MODULE_NOT_FOUND`. Fix with a junction:
+> ```
+> mklink /J "…\dsh-wake-relay\node_modules\@deepseek-ai\dsh-llm" "C:\Users\<you>\.dsh\profiles\node_modules\@deepseek-ai\dsh-llm"
+> ```
+> After a failed load, `install_bundle` only reports `already-installed`; toggle `include:<id>` off and on to force a re-import.
+
+## Config
+
+Set on the bundle row in the profile's `cordis.patch.yml`, or in this package's `cordis.patch.yml`:
+
+| Field | Default | Meaning |
+|---|---:|---|
+| `port` | 45871 | Bind address is always `127.0.0.1`. If the port is taken, falls back to an ephemeral port and republishes the endpoint file |
+| `token` | empty | Empty = generated on first boot, persisted to `$DSH_HOME/wake-bridge-secret.json` (mode 0600) |
+| `sessionId` | empty | Default target. Empty = only requests carrying an explicit `session` are accepted |
+| `cooldownMs` | 90000 | Per-reason minimum spacing |
+| `reasonWindowMs` / `reasonMaxHits` | 300000 / 2 | How many times one reason may fire inside the window |
+| `globalBurstMs` | 3000 | Minimum gap between any two wakes; collapses simultaneous bursts only |
+| `flushTimeoutMs` | 10000 | Per-delivery ceiling; a timed-out flush returns 503 |
+| `dedupeWindowMs` | 604800000 | `event_id` dedupe window (7 days) |
+| `template` | empty | Message body; supports `{{detail}}`, `{{reason}}`, `{{data.k}}` |
+| `footnote` | empty | One line appended after the template |
+| `watcherStatePath` | empty | External watcher state file folded into `GET /status` |
+
+Template variables: `{{event_id}} {{kind}} {{reason}} {{detail}} {{context_path}} {{session}} {{time}}`, plus any `{{data.<path>}}`. Unknown variables are left verbatim.
+
+## API
+
+```
+GET  /health                  public      -> {ok, sessionId, inflight, seen, lastWakeAt}
+GET  /status                  (token)     -> counters, per-reason windows, external watcher queue summary
+POST /wake     (x-wake-token) -> {accepted, delivered, messageId, sessionId}
+POST /bind     (x-wake-token) -> {accepted, sessionId}   rebind the default (not persisted)
+```
+
+`POST /wake` body:
+
+```json
+{
+  "event_id": "build-2026-11-12-7f3a",
+  "kind": "signal",
+  "reason": "BUILD_DONE",
+  "detail": "17 passed, 0 failed",
+  "data": { "anything": "reachable as {{data.anything}} in a template" },
+  "context_path": "C:\\path\\to\\state.json",
+  "session": "session-… (optional, overrides the default)",
+  "text": "(optional) full message replacing the template, <= 2000 chars"
+}
+```
+
+| Status | Meaning | Caller |
+|---|---|---|
+| 200 | delivered and flushed | done |
+| 429 `duplicate` / `cooldown` / `burst` | dropped by policy | do **not** retry |
+| 503 `delivery_failed` / `session_not_found` / `no_session_bound` | nothing recorded | retry with the **same** `event_id` |
+| 401 / 400 | bad token / bad body | fix the caller |
+
+> Non-ASCII bodies must be sent as UTF-8 bytes. PowerShell needs `[System.Text.Encoding]::UTF8.GetBytes($body)`, otherwise `detail` arrives as a row of `?`.
+
+### Node
+
+```js
+import { wake } from "dsh-wake-relay/client";
+
+const r = await wake({ event_id: `job-${Date.now()}`, reason: "JOB_DONE", detail: "…" });
+if (r.retryable) setTimeout(() => wake(sameEvent), 30_000); // 503 means nothing was recorded
+```
+
+### Anything else
+
+```bash
+EP=$(cat ~/.dsh/wake-endpoint.json)   # {port, token, sessionId}
+curl -s -X POST "http://127.0.0.1:$PORT/wake" \
+  -H "x-wake-token: $TOKEN" -H "content-type: application/json; charset=utf-8" \
+  --data-binary @event.json
+```
+
+## Optional rules engine (Python)
+
+`watcher/` is a resident process plus a rule table, for the common case where you would otherwise write one polling script per condition:
+
+```bash
+python watcher/waiter.py --rules watcher/rules.example.json --list
+python watcher/waiter.py --rules my-rules.json --once --dry-run   # evaluate, send nothing
+pythonw watcher/waiter.py --rules my-rules.json                   # resident; rules hot-reload
+```
+
+| Probe | True when |
+|---|---|
+| `file_exists` / `file_contains` | path exists / content matches a regex |
+| `pid` | process alive or gone (native on Windows, `kill(pid,0)` elsewhere) |
+| `port` | TCP connect succeeds or fails |
+| `http_json` | a JSON field compares (`== != > >= < <= contains matches`) |
+| `command` | any command's exit code matches; stdout becomes `{detail}` |
+
+Edge-triggered (fires on the false→true transition only), `rearm_s` debounce, `once`, a persisted retry queue with `ttl_s`, and `session: latest` for the newest ordinary session. The rule file reloads without a restart.
+
+State lives in `$DSH_HOME/wake-bridge-watcher` (`waiter-state.json` / `waiter.log` / `waiter.pid`).
+
+## Runtime files (`$DSH_HOME`)
+
+| File | Content |
+|---|---|
+| `wake-endpoint.json` | `{port, token, sessionId, pid, startedAt}` — callers discover it, no second copy of the config |
+| `wake-bridge-secret.json` | the generated token (0600) |
+| `wake-bridge-events.jsonl` | accepted fires, append-only, 7-day window, compacted when it outgrows the window |
+| `wake-bridge.log` | accept / reject / delivered / failed |
+| `wake-bridge-watcher/` | external watcher edge state + retry queue |
+
+## Known limits
+
+- **The host must be online to deliver.** While it is down the watcher only accumulates events (within `ttl_s`); nothing is pre-staged for replay.
+- **`/bind` is not persisted.** A restart returns to the configured `sessionId`.
+- **The token is plaintext** in `wake-endpoint.json`. Loopback only — do not port-forward it, and tighten the file on shared machines.
+- **One wake = one full inference + one permanent message.** For high-frequency conditions write state to disk instead of waking; when you do wake, bring the context with you (`context_path`).
+- **`session: latest` is a guess.** It picks the newest ordinary session on disk. Long-running or unattended jobs must pin `session` explicitly, or the wake may land in a throwaway conversation.
+- An explicit `session` that cannot be resolved returns 503. It is **never** silently redirected — waking the wrong context is worse than not waking.
+
+## Tests
+
+```bash
+node selftest.mjs           # 21 checks: delivery, idempotency, limits, retry, templates, cross-restart dedupe, port fallback
+python watcher/selftest.py  # 11 groups: probes, edges, retry queue, session routing, rule validation (offline)
+```
+
+## License
+
+MIT.

package/README.md

@@ -1,3 +1,220 @@
-# Temporary Holding Version
+# dsh-wake-relay · 外部唤醒
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English: [README.en.md](./README.en.md)**
+
+让**任意外部进程**唤醒一个 DeepSeek Harness 会话：构建监听、任务收尾、CI 回调、抓取完成、备份完成、手机推送转发、你自己的 watcher——任何能发一个 HTTP POST 的东西。
+
+一句话说清它和同类插件的分工：**别人解决「agent 睡着了怎么叫醒它」，这个解决「叫醒它的那根线断了怎么办」。**
+
+---
+
+## 为什么
+
+DSH 的原生 `schedule` 和市面上的唤醒插件都把计时器/探针放在**宿主进程里**：宿主退出，探测停、投递停，那段时间里发生又消失的变化永久丢失。
+
+这个插件反过来——**判断在宿主外面，投递在宿主里面**：
+
+```
+外部进程（你自己的脚本 / 自带 watcher）
+  └─ 每轮探测，条件成立 → POST 127.0.0.1/wake ──┐
+                                                 │  宿主在线：立即注入并 flush
+                                                 │  宿主离线：连接失败，事件留在你的队列里
+                                                 └→ 宿主回来：同一个 event_id 补投
+```
+
+关键是这条约定：**HTTP 200 = 已投递并 flush；503 = 什么都没记录，可以用同一个 `event_id` 重试。** 投递从不"大概成功"，所以重试权可以完整地交给调用方，去重和幂等由插件这一侧兜住。
+
+代价是：你得有一个常驻的外部进程（自带 `watcher/` 里的规则引擎，或者你自己的脚本）。
+
+---
+
+## 与同类项目的差异
+
+| | 本插件 | 宿主内探针类（dsh-sentinel 等） |
+|---|---|---|
+| 探针在哪跑 | 外部进程 | 宿主进程内 |
+| 宿主退出期间 | **照常采样，事件排队等重试** | 不采样，窗口内变化丢失 |
+| 判断能力 | 任意命令退出码 + JSON 字段断言 | 固定几类 sensor，多数只判「变了没」 |
+| 失败语义 | 503 + 不记账，重试幂等 | at-least-once / 由插件内部重排 |
+| UI | 无（`GET /status` + 日志） | dock 面板 / 侧栏 dashboard |
+| 多实例 | 撞端口自动退到随机端口 | lease 选主 |
+| Windows 进程探针 | 原生 `OpenProcess` | 多为 `pgrep`（Windows 上不可用） |
+
+UI 是有意的取舍：这个插件的读者是**脚本**，不是人的眼睛。
+
+---
+
+## 安装
+
+```bash
+# 从 npm（发布后）
+dsh plugin --profile desktop add dsh-wake-relay
+
+# 从本地目录
+git clone <repo> dsh-wake-relay
+dsh plugin --profile <你的 profile> add ./dsh-wake-relay
+```
+
+装完**重启 DSH** 生效（插件树在进程启动时组合）。
+
+### 两个装的时候才会遇到的陷阱
+
+**① bundle 的 entry id 必须全局唯一。** 启用/禁用状态是按 entry id 持久化的，写在 profile 的 `cordis.patch.yml` 里：
+
+```yaml
+- id: wake-bridge
+  disabled: true
+```
+
+如果另一个 bundle 的 patch 也 `insert` 同名 id，它会被这条 disabled **静默吞掉**——不报错、不告警，只在日志里留个空。判断装没装上的唯一可靠方法是看运行时产物：`wake-endpoint.json` 里有没有新端口、`wake-bridge.log` 有没有新的 `listening` 行、`wake-bridge-secret.json` 有没有生成。`install_bundle` 的返回永远是 `applied`，它不代表加载成功。
+
+**② `sessionId` 留空是合法配置，但装完不能直接 curl。**留空时请求必须自带 `session`，否则返回 `503 no_session_bound`。启动日志会明说：
+
+```
+listening on 127.0.0.1:45871 — NO default session bound: every /wake request must carry "session"
+```
+
+要么在 `cordis.patch.yml` 里配死 `sessionId`，要么每次请求都带 `session`。
+
+> 本地目录安装的另一个已知坑：`install_bundle` 传目录落的是 `pnpm link:`，插件从 workspace 真实路径解析不到宿主包 → `ERR_MODULE_NOT_FOUND`。修法是在包目录里建 junction：
+> ```
+> mklink /J "…\dsh-wake-relay\node_modules\@deepseek-ai\dsh-llm" "C:\Users\<你>\.dsh\profiles\node_modules\@deepseek-ai\dsh-llm"
+> ```
+> 安装失败后 `install_bundle` 只会报 `already-installed`，要 `set_plugin` 把 `include:<id>` 关掉再打开才能强制重新 import。
+
+---
+
+## 配置
+
+写进 profile 的 `cordis.patch.yml`（bundle 行的 `config` 段），或本包的 `cordis.patch.yml`：
+
+| 字段 | 默认 | 说明 |
+|---|---:|---|
+| `port` | 45871 | 监听端口，只绑 `127.0.0.1`；被占用时自动退到随机端口并重写 endpoint 文件 |
+| `token` | 空 | 空 = 首次启动生成并持久化到 `$DSH_HOME/wake-bridge-secret.json`（0600） |
+| `sessionId` | 空 | 默认目标会话。空 = 只接受带显式 `session` 的请求 |
+| `cooldownMs` | 90000 | **per-reason** 最小间隔 |
+| `reasonWindowMs` / `reasonMaxHits` | 300000 / 2 | 同一 reason 在这个窗口内最多触发几次 |
+| `globalBurstMs` | 3000 | 任意两次唤醒的最小间隔，只压同时爆发 |
+| `flushTimeoutMs` | 10000 | 单次投递的上限，超时回 503 |
+| `dedupeWindowMs` | 604800000 | `event_id` 去重窗口（7 天） |
+| `template` | 空 | 消息模板，支持 `{{detail}}` `{{reason}}` `{{data.k}}` 等 |
+| `footnote` | 空 | 追加在消息末尾的一行 |
+| `watcherStatePath` | 空 | 外部 watcher 的 state 文件，`GET /status` 会折叠它 |
+
+模板变量：`{{event_id}} {{kind}} {{reason}} {{detail}} {{context_path}} {{session}} {{time}}`，以及任意 `{{data.<路径>}}`。未知变量原样保留。
+
+---
+
+## API
+
+```
+GET  /health                 公开（无 token）→ {ok, sessionId, inflight, seen, lastWakeAt}
+GET  /status                 (token) → 计数器 + reason 命中窗口 + 外部 watcher 的队列摘要
+POST /wake     (x-wake-token) → {accepted, delivered, messageId, sessionId}
+POST /bind     (x-wake-token) → {accepted, sessionId}   换默认绑定（不持久，重启回配置）
+```
+
+`POST /wake` 请求体：
+
+```json
+{
+  "event_id": "build-2026-11-12-7f3a",
+  "kind": "signal",
+  "reason": "BUILD_DONE",
+  "detail": "17 个用例通过，0 失败",
+  "data": { "任何": "结构化字段，模板里用 {{data.任何}} 取" },
+  "context_path": "C:\\path\\to\\state.json",
+  "session": "session-…（可选，覆盖默认绑定）",
+  "text": "（可选）整条消息，替代模板，2000 字以内"
+}
+```
+
+| 状态 | 含义 | 调用方 |
+|---|---|---|
+| 200 | 已投递并 flush | 完成 |
+| 429 `duplicate` / `cooldown` / `burst` | 按策略丢弃 | **不要重试** |
+| 503 `delivery_failed` / `session_not_found` / `no_session_bound` | 什么都没记录 | 用**同一个 event_id** 重试 |
+| 401 / 400 | token 错 / 请求格式错 | 修调用方 |
+
+> 中文 body 必须按 UTF-8 字节发。PowerShell 用 `[System.Text.Encoding]::UTF8.GetBytes($body)`，否则 `detail` 会变成一串 `?`。
+
+### Node 客户端
+
+```js
+import { wake } from "dsh-wake-relay/client";
+
+const r = await wake({ event_id: `job-${Date.now()}`, reason: "JOB_DONE", detail: "…" });
+if (r.retryable) setTimeout(() => wake(sameEvent), 30_000); // 503 → 值得重试
+```
+
+### 任何语言
+
+```bash
+EP=$(cat ~/.dsh/wake-endpoint.json)   # {port, token, sessionId}
+curl -s -X POST "http://127.0.0.1:$PORT/wake" \
+  -H "x-wake-token: $TOKEN" -H "content-type: application/json; charset=utf-8" \
+  --data-binary @event.json
+```
+
+---
+
+## 自带的规则引擎（可选，Python）
+
+`watcher/` 是一个常驻进程 + 一张规则表，替你把「每个场景写一个轮询脚本」收成「加一条规则」：
+
+```bash
+python watcher/waiter.py --rules watcher/rules.example.json --list
+python watcher/waiter.py --rules my-rules.json --once --dry-run   # 只判断不发
+pythonw watcher/waiter.py --rules my-rules.json                   # 常驻（改规则不用重启）
+```
+
+| 探针 | 成立条件 |
+|---|---|
+| `file_exists` / `file_contains` | 路径存在 / 内容匹配正则 |
+| `pid` | 进程在/不在（Windows 原生 `OpenProcess`，*nix `kill(pid,0)`） |
+| `port` | 端口开/关 |
+| `http_json` | 取 JSON 字段后比较（`== != > >= < <= contains matches`） |
+| `command` | 任意命令退出码符合；stdout 进 `{detail}` |
+
+边沿触发（只在假→真那一瞬发一次）、`rearm_s` 防抖、`once` 一次性、持久化重试队列 + `ttl_s`、`session: latest` 自动选磁盘上最新的普通会话。规则表热重载。
+
+状态目录：`$DSH_HOME/wake-bridge-watcher`（`waiter-state.json` / `waiter.log` / `waiter.pid`）。
+
+---
+
+## 运行时文件（`$DSH_HOME`）
+
+| 文件 | 内容 |
+|---|---|
+| `wake-endpoint.json` | `{port, token, sessionId, pid, startedAt}`，脚本自动发现，不用手抄 |
+| `wake-bridge-secret.json` | 自动生成的 token（0600） |
+| `wake-bridge-events.jsonl` | 已接受的 fire 记录（append-only，7 天窗口，超限自动 compact） |
+| `wake-bridge.log` | accept / reject / delivered / failed |
+| `wake-bridge-watcher/` | 外部 watcher 的边沿状态 + 重试队列 |
+
+---
+
+## 已知边界
+
+- **宿主必须在线才能投递**。宿主退出期间外部 watcher 只会攒事件（`ttl_s` 内），不会"预投"到磁盘再回放。
+- **`/bind` 不持久**；重启回配置里的 `sessionId`。
+- **token 是明文**（`wake-endpoint.json`）。只绑 `127.0.0.1`，别做端口转发；多用户机器上把这个文件权限收一收。
+- **一次唤醒 = 一次完整推理 + 一条永久消息**。高频条件请写 state 文件，别叫醒；真要叫，一次把上下文带全（`state_path`）。
+- **`session: latest` 是猜测**：它挑磁盘上最新的普通会话。长任务/无人值守必须显式钉 `session`，否则唤醒可能落进临时对话。
+- 显式 `session` 解析失败返回 503，**绝不静默改投**。
+
+---
+
+## 自测
+
+```bash
+node selftest.mjs           # 21 条：投递、幂等、限流、重试、模板、跨重启去重、撞端口回退
+python watcher/selftest.py  # 11 组：探针、边沿、重试队列、会话路由、规则校验（离线，不发真唤醒）
+```
+
+---
+
+## License
+
+MIT。

package/client.mjs

@@ -0,0 +1,71 @@
+/**
+ * Minimal client for dsh-wake-relay.
+ *
+ * Reads `$DSH_HOME/wake-endpoint.json` (or an explicit {port, token}) and POSTs
+ * one wake event. Nothing is retried here on purpose: the bridge returns 503
+ * only when it recorded nothing, so the decision to retry — and how often —
+ * belongs to whatever owns the schedule.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+export function dshHome() {
+  return process.env.DSH_HOME || join(homedir(), ".dsh");
+}
+
+export function readEndpoint(home = dshHome()) {
+  const raw = JSON.parse(readFileSync(join(home, "wake-endpoint.json"), "utf8"));
+  if (!raw || !raw.port) {
+    const error = new Error("wake endpoint is not published (host is down or the plugin is not loaded)");
+    error.code = "no_endpoint";
+    throw error;
+  }
+  return raw;
+}
+
+async function post(path, payload, endpoint, timeoutMs) {
+  const ep = endpoint || readEndpoint();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`http://127.0.0.1:${ep.port}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json; charset=utf-8", "x-wake-token": ep.token },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    const body = await res.json().catch(() => ({}));
+    return { status: res.status, ok: res.status === 200, body };
+  } catch (error) {
+    return { status: 0, ok: false, body: { reason: error && error.name === "AbortError" ? "timeout" : "unreachable" } };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * POST one wake event.
+ *
+ * @returns {Promise<{status:number, ok:boolean, retryable:boolean, body:object}>}
+ *   200 -> delivered and flushed.
+ *   429 -> dropped by policy (duplicate / cooldown / burst). Do NOT retry.
+ *   503 -> nothing was recorded. Same event_id may be retried verbatim.
+ */
+export async function wake(event, { endpoint, timeoutMs = 15_000 } = {}) {
+  if (!event || !event.event_id) throw new Error("event_id is required");
+  const result = await post("/wake", event, endpoint, timeoutMs);
+  return { ...result, retryable: result.status === 503 };
+}
+
+export async function bind(sessionId, { endpoint, timeoutMs = 5_000 } = {}) {
+  return post("/bind", { sessionId }, endpoint, timeoutMs);
+}
+
+export async function status({ endpoint, timeoutMs = 5_000 } = {}) {
+  const ep = endpoint || readEndpoint();
+  const res = await fetch(`http://127.0.0.1:${ep.port}/status`, {
+    headers: { "x-wake-token": ep.token },
+  });
+  return { status: res.status, body: await res.json().catch(() => ({})) };
+}

package/cordis.patch.yml

@@ -0,0 +1,21 @@
+# Bundle patch for dsh-wake-relay.
+#
+# The entry id must not collide with another bundle: profiles persist enable /
+# disable state per entry id, so reusing an id that another install already
+# disabled makes this one silently unavailable.
+#
+# Everything here is optional: with an empty token the plugin generates one on
+# first boot and persists it to $DSH_HOME/wake-bridge-secret.json; with an empty
+# sessionId only requests that carry an explicit `session` are accepted.
+- insert:
+    - id: dsh-wake-relay
+      name: dsh-wake-relay
+      config:
+        port: 45871
+        token: ''
+        sessionId: ''
+        cooldownMs: 90000
+        reasonWindowMs: 300000
+        reasonMaxHits: 2
+        globalBurstMs: 3000
+        flushTimeoutMs: 10000

package/docs/why-external.md

@@ -0,0 +1,65 @@
+# 为什么把判断放在宿主外面
+
+DSH 的插件生态里，「唤醒 agent」这个需求已经有几个实现。它们的共同结构是：
+
+```
+插件加载 → 定时器 → 探针 → 条件成立 → followup() 唤醒
+```
+
+全部跑在宿主进程里。这在 90% 的场景下够用，但有三种情况会漏：
+
+| 情况 | 宿主内探针的结果 |
+|---|---|
+| DSH 重启（升级、崩溃、你手动关了） | 计时器消失；这期间到达的条件不再被观察 |
+| 条件成立后又消失（数值穿过阈值又回来、文件写了又删、任务失败后被自动重试成功） | 窗口内的那个边沿永久丢失 |
+| 你需要「即使 agent 不在也要有人记着这件事」 | 没人记着 |
+
+根因不是实现质量，是**故障域**：探针和宿主共享同一个生命周期，宿主挂则探针挂。再多的重试逻辑也救不回来，因为重试代码本身也在那个进程里。
+
+## 拆成两半
+
+```
+┌──────────── 外部进程（你自己的） ────────────┐
+│  探测 30s 一轮                               │
+│  条件成立 → 事件进本地持久化队列              │
+│  POST /wake（幂等 event_id）                 │
+│  503 → 留在队列，TTL 内重试   ← 关键         │
+└──────────────────────────────────────────────┘
+                    │ HTTP 127.0.0.1
+┌──────────── 宿主进程（插件） ────────────────┐
+│  验证 token                                  │
+│  去重 / per-reason 限流                      │
+│  resolveAgent → followup → flush             │
+│  200 仅在此后返回；失败不记账                 │
+└──────────────────────────────────────────────┘
+```
+
+拆开之后，两个进程各自拥有独立的重启周期：
+
+- 宿主挂了：外部进程照常采样，事件排队，等宿主回来补投。
+- 外部进程挂了：插件不受影响，宿主里已有的唤醒照常投递。
+- 两个都挂了：事件在外部进程的磁盘队列里，TTL 内起来就能补。
+
+## 那个 200/503 约定是全部的关键
+
+如果插件在「投递成功之前」就返回 200，调用方会认为事情办完了，事件就永久丢了。反过来如果失败时也记账（写进去重表），重试就会被判成 duplicate，也永久丢。
+
+所以：
+
+- **200** 只在 `flush()` 真的返回之后发。
+- **503** 只在「什么都没发生」时发——不写去重表、不写限流窗口、不写日志之外的任何东西。
+- **429** 才是「按策略丢掉了」，明确告诉调用方别重试。
+
+这三条让重试成为纯安全操作：用同一个 `event_id` 重发，最多成功一次。
+
+## 代价
+
+1. 你得有一个常驻的外部进程。本包的 `watcher/` 是给这个用的，但任何脚本都行。
+2. 两段式意味着两个失效点——外部进程死了，唤醒就停了。所以它必须由计划任务/服务托管，并且要能自报状态（`GET /status` 会折叠外部 watcher 的队列摘要）。
+3. 判断逻辑不在模型手里。条件写死在规则表里；需要「看到条件后再判断」的场景，应该只把「条件成立」这个事实送进来，让会话去决定做什么——规则里不要写死结论。
+
+## 不该用它的时候
+
+- 纯时间（3 小时后、每天 9 点）：用原生 `schedule`。它持久化、停机后补发、不占进程。
+- 需要毫秒级闭环的动作（实时控制、硬件回环、执行层动作）：交给专门的执行系统，别经过一个模型。延迟、成本、可靠性都差三个数量级。
+- 想在会话里「等一会儿再看」：那是宿主内的活，别跨进程。

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#101820"/>
+  <path d="M32 12c-6.6 0-11.4 4.9-11.4 11.6v9.2l-4.2 7.1c-.7 1.2.2 2.7 1.6 2.7h28c1.4 0 2.3-1.5 1.6-2.7l-4.2-7.1v-9.2C43.4 16.9 38.6 12 32 12z"
+        fill="none" stroke="#f5a623" stroke-width="3.2" stroke-linejoin="round"/>
+  <path d="M26.2 47.2a6 6 0 0 0 11.6 0" fill="none" stroke="#f5a623" stroke-width="3.2" stroke-linecap="round"/>
+  <circle cx="46.5" cy="17.5" r="4.5" fill="#e74c3c"/>
+</svg>