wake-bridge 0.9.0-preview.8

package/dist/src/util.js

@@ -0,0 +1,136 @@
+import { createHash, randomUUID } from "node:crypto";
+export const DEFAULT_TIMEZONE = "UTC";
+export function id(prefix) {
+    return `${prefix}_${randomUUID()}`;
+}
+export function isoNow(now = new Date()) {
+    return now.toISOString();
+}
+export function asDate(value) {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime()))
+        throw new Error(`Invalid date: ${String(value)}`);
+    return date;
+}
+export function addMs(value, milliseconds) {
+    return new Date(asDate(value).getTime() + milliseconds).toISOString();
+}
+export function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function parseJson(value, fallback) {
+    if (typeof value !== "string")
+        return value ?? fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function stableJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    const object = value;
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableJson(object[key])}`).join(",")}}`;
+}
+export function getPath(value, path) {
+    return path.split(".").reduce((current, key) => {
+        if (current && typeof current === "object" && key in current) {
+            return current[key];
+        }
+        return undefined;
+    }, value);
+}
+export function localParts(date, timezone) {
+    const formatter = new Intl.DateTimeFormat("en-CA", {
+        timeZone: timezone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hourCycle: "h23",
+    });
+    const values = Object.fromEntries(formatter.formatToParts(date).map((part) => [part.type, part.value]));
+    return {
+        date: `${values.year}-${values.month}-${values.day}`,
+        hour: Number(values.hour),
+        minute: Number(values.minute),
+        second: Number(values.second),
+    };
+}
+export function localMinute(date, timezone) {
+    const parts = localParts(date, timezone);
+    return parts.hour * 60 + parts.minute;
+}
+export function parseClock(value) {
+    const match = /^(\d{1,2}):(\d{2})$/.exec(value.trim());
+    if (!match)
+        throw new Error(`Invalid local time: ${value}`);
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    if (hour > 23 || minute > 59)
+        throw new Error(`Invalid local time: ${value}`);
+    return hour * 60 + minute;
+}
+export function clockInWindow(minute, start, end) {
+    if (start === end)
+        return true;
+    if (start < end)
+        return minute >= start && minute < end;
+    return minute >= start || minute < end;
+}
+export function quietWindowAt(date, config, fallbackTimezone = DEFAULT_TIMEZONE) {
+    if (!config?.windows?.length)
+        return false;
+    const timezone = config.timezone || fallbackTimezone;
+    const minute = localMinute(date, timezone);
+    return config.windows.some((window) => clockInWindow(minute, parseClock(window.start), parseClock(window.end)));
+}
+/** Find the first minute at which a quiet-hours gate is open again. */
+export function quietEndAfter(date, config, fallbackTimezone = DEFAULT_TIMEZONE) {
+    if (!quietWindowAt(date, config, fallbackTimezone))
+        return date;
+    // A local clock window is at most 24 hours.  Scan in minute increments so
+    // this remains correct across timezone offsets and midnight windows. Start
+    // from an absolute minute boundary so a 01:45:37 observation releases at
+    // 03:30:00, never 03:30:37.
+    const start = date.getTime();
+    const firstBoundary = Math.floor(start / 60_000) * 60_000;
+    for (let minute = 1; minute <= 48 * 60 + 2; minute += 1) {
+        const candidate = new Date(firstBoundary + minute * 60_000);
+        if (!quietWindowAt(candidate, config, fallbackTimezone))
+            return candidate;
+    }
+    return new Date(start + 24 * 60 * 60_000);
+}
+/** Resolve the next occurrence of HH:mm in a timezone using a bounded search. */
+export function nextLocalClock(date, clock, timezone) {
+    const target = parseClock(clock);
+    const start = date.getTime();
+    const firstBoundary = Math.floor(start / 60_000) * 60_000;
+    for (let minute = 0; minute <= 48 * 60 + 2; minute += 1) {
+        const candidate = new Date(firstBoundary + minute * 60_000);
+        if (candidate.getTime() < start)
+            continue;
+        const parts = localParts(candidate, timezone);
+        if (parts.hour * 60 + parts.minute === target && candidate.getTime() >= start) {
+            return candidate;
+        }
+    }
+    return new Date(start + 24 * 60 * 60_000);
+}
+export function jsonValue(value) {
+    return value;
+}
+export function assertFiniteMs(value, field, fallback) {
+    const resolved = value ?? fallback;
+    if (!Number.isFinite(resolved) || resolved < 0)
+        throw new Error(`${field} must be a non-negative finite number`);
+    return resolved;
+}
+//# sourceMappingURL=util.js.map

package/dist/src/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../../src/util.ts"],"names":[],"mappings":"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"}

package/dist/src/version.d.ts

@@ -0,0 +1 @@
+export declare const RELEASE_VERSION = "0.9.0-preview.8";

package/dist/src/version.js

@@ -0,0 +1,2 @@
+export const RELEASE_VERSION = "0.9.0-preview.8";
+//# sourceMappingURL=version.js.map

package/dist/src/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC"}

package/docs/adapters/botlingknows.md

@@ -0,0 +1,40 @@
+# 小机知道通知 Source Connector adapter
+
+状态：official optional Source Connector，available but default disabled。通用 connector 代码与 fixture 已实现；
+每个 Agent Space 仍须独立完成 identity verify、from-now bootstrap、无读取副作用检查与真实 UAT 后才可 enable。
+本文不证明某台机器当前已运行，也不能把第一位使用者的安装流程当作项目起源。
+
+## 已实现的边界
+
+- manifest 声明 `read_side_effects=none`、`credential_custody=connector`、上游 credential breadth `unknown`，以及 connector 对 Bridge 暴露 `notifications.read`；
+- 只调用 `notifications(view=full, mark_read=false)`；
+- raw notification `id` 生成稳定 dedupe key；
+- 当前 provider page limit 为 50；公开 `sources.json.example` 固定使用 50，不能沿用 generic connector 的 100；
+- event 只保存 type、category、稳定 id、resource reference 与 `next_action`，不复制通知正文；
+- opaque 分页 cursor 只用于完成当前扫描，不冒充增量 high-watermark；
+- 一页事件全部 durable 后才 CAS 推进 source checkpoint；崩溃重放由 event dedupe 吸收；
+- 提供显式 `from-now` bootstrap helper，避免上线时偷偷把旧通知当新事件。
+- 独立 connector 从自己的 `BOTLINGKNOWS_MCP_URL` 读取现有 Streamable HTTP MCP 登录，按标准 `initialize → notifications/initialized → tools/call` 调用；Wake Bridge 只持 connector-local bearer。
+- owning agent 自己配置 `BOTLINGKNOWS_MCP_URL` 与非敏感的 `BOTLINGKNOWS_SUBJECT_REF`；connector 在内部从 URL/config 计算 `binding_fingerprint`。Wake Bridge 不发现、不复制、不修改 URL；
+- 上游 URL、路径内身份、响应正文与 connector token 都不会进入 Wake Bridge event/checkpoint；checkpoint 只保存 agent 确认的 subject ref、binding hash 与 opaque cursor。上游身份撤销或 binding 变化投影为结构性 `needs_attention`，不无限重试。
+
+## Cursor 语义
+
+checkpoint 同时记录：
+
+- `high_watermark`：上一次完整扫描确认的最高 notification id；
+- `page_cursor`：尚未扫完时的临时分页位置；
+- `pending_max_id`：本次扫描已经看到的最高 id。
+
+只在扫到旧 watermark 或分页结束后，才把 `pending_max_id` 提升为新的 high-watermark。这样 bounded polling 不会因为先提交最新页而漏掉后续旧页中的新事件。
+
+## Discover → configure → verify → bootstrap → UAT → enable
+
+1. 使用 v0.9 `botlingknows-connector` 安装独立进程。它复用 owning agent 自己配置的 MCP URL；provider 无需修改 server 或签发专用 credential。上游 URL 只进入 connector env，不进入 Wake Bridge daemon、模型上下文或 event。
+2. Connector manifest 如实记录实际上游 credential breadth。若当前 MCP credential 是 broad，就写 `broad` 而不是伪装成 `read_only`；Bridge 只获得 `notifications.read` connector capability。
+3. 用真实调用确认 full view 的字段和排序与 fixture 一致，且 `mark_read=false` 在调用前后不改变 `read_at`。
+4. Owning agent 先用 `attention_source_verify` 核对 subject/binding，再明确使用 `from-now` 或受控 backfill；P0 的 `attention_source_bootstrap/rebind/enable/disable` 不要求手改 SQLite、静态 source JSON 或 LaunchAgent。
+5. 通用 runner、退避、health 与 connector 进程已实现；仍需安装两个 LaunchAgent/env，先用隔离 DB 做 bootstrap + `source-once`，再以一条专用测试通知做 canary。
+6. 真实 canary 只验证 event/claim/receipt，不自动回复、不 mark useful、不改通知 read state。
+
+若小机知道未来提供原生 `notifications:read` scope，可以无缝换成更窄的上游授权；这会降低 connector 被攻破时的影响面，但不是首次接入的前置条件。

package/docs/adapters/gmail-planned.md

@@ -0,0 +1,16 @@
+# Gmail Source Connector
+
+状态：planned，not bundled，not enableable。
+
+Gmail 出现在 catalog 中仅用于说明预期的 Source Connector 形状；当前发行物没有 Gmail 实现、登录流程或支持承诺。
+
+进入 `available` 以前至少需要完成：
+
+- 选择并记录合规的 Google OAuth 应用与最小 scope；
+- 定义 message/thread resource reference，不把邮件正文复制进 Wake Bridge；
+- 明确 History API cursor、过期 cursor、初次 from-now bootstrap 和 backfill 语义；
+- 验证读取不会自动 mark read、archive、modify 或发送邮件；
+- 实现 token custody、refresh、revoke、rate limit、offline catch-up 与 `needs_attention`；
+- 使用隔离账号完成真实身份、重启、重复 delivery 和端到端 wake UAT。
+
+这些条件完成并经过独立版本验收后，catalog 才能把 Gmail 改为 `available`。

package/docs/adapters/group-chat.md

@@ -0,0 +1,126 @@
+# Group Chat source adapter
+
+状态：public SDK reference adapter 与 loopback HTTP connector；从 `0.9.0-preview.6` 起进入 package。
+
+本文件属于 Wake Bridge。它描述第一个官方 reference adapter 如何消费独立 Group Chat 项目的公开 event feed；Group Chat 不导入或实现本仓库协议。
+
+“第一个官方 reference adapter”只表示它在最初方案中用于验证真实的 mention/reply 垂直链路，不表示它拥有 core
+特权，也不覆盖小机知道用户提问这一项目起源。第三方 source 必须能沿同一 SDK、contract test 与注册路径接入。
+
+## 依赖方向
+
+```text
+Wake Bridge group-chat adapter
+            │ consumes a narrow connector surface
+            ▼
+agent-controlled Group Chat connector
+            │ existing principal auth
+            ▼
+Group Chat versioned event-feed contract
+```
+
+adapter 是 anti-corruption layer：验证 Group Chat schema，再转换成通用 WakeEvent input。实现通过
+`wake-bridge/source/group-chat` 发布，只依赖 public source/event contract；Wake Bridge core 不认识 room/message 领域对象，也不持有 Group Chat principal credential。
+
+下面列的是这个 reference source 已经具备、connector 可以利用的能力，不是 Wake Bridge 要求所有第三方服务新增的接口。若另一个服务只有 OAuth REST、MCP、webhook 或本地 session，应由它自己的 connector 适配现有能力。
+
+## 所需 Group Chat 能力
+
+- service consumer credential，绑定一个 member principal 与 room scopes；
+- `read_events(after_event_cursor, limit, wait_ms, types?)`；
+- stable event id、global event cursor、schema version；
+- resource URI/message id/message cursor；
+- 使用相同 principal credential 读取 resource 的 API 或 MCP。
+
+adapter 不需要 Group Chat 管理员 credential。
+
+## v1 映射
+
+| Group Chat event | Wake source/type | coalesce key | 默认 channel hint |
+| --- | --- | --- | --- |
+| `room.mention.created` | `group_chat/mention` | `group:<room_id>` | `group:<room_id>` |
+| `room.reply.created` | `group_chat/reply` | `group:<room_id>` | `group:<room_id>` |
+| `room.message.created` | `group_chat/activity` | `group:<room_id>` | `group:<room_id>` |
+| `room.message.tombstoned` | `group_chat/tombstone` | `group:<room_id>` | `group:<room_id>` |
+| `room.membership.changed` | `group_chat/membership` | `group:<room_id>` | `default` |
+
+映射只表达事件类别，不决定 immediate/scheduled/suppress。个人 policy 才拥有这个决定。
+
+## WakeEvent input 示例
+
+```json
+{
+  "schema_version": 1,
+  "occurred_at": "2026-08-26T03:21:00Z",
+  "type": "mention",
+  "dedupe_key": "event:gev_01...",
+  "coalesce_key": "group:room_home",
+  "priority_hint": "high",
+  "attention_channel_hint": "group:room_home",
+  "actor_ref": "group-member:member-b",
+  "resource": {
+    "uri": "group-chat://room_home/messages/msg_01...",
+    "cursor": "184"
+  },
+  "metadata": {
+    "room_id": "room_home",
+    "group_event_cursor": 955,
+    "group_schema_version": 1,
+    "direct": true
+  },
+  "payload_preview": null
+}
+```
+
+`priority_hint=high` 只是 adapter 的保守提示，不能绕过个人 policy 或 quiet-hours rule。
+
+## Cursor 与事务
+
+```text
+read group events after local committed cursor
+  → validate every event schema/audience
+  → map to SourceDeliveries
+  → durable insert/dedupe all WakeEvents in the page
+  → revision-CAS the opaque group event cursor
+```
+
+进程在 event commit 后、cursor CAS 前崩溃会重读同一页；stable ids 使其幂等。adapter 不向 Group Chat 写 consumer ack，也不推进任何 member last-seen cursor。
+
+## 当前证据与集成责任
+
+仓内 fixture 验证五类 event 的 v1 schema fence、mention/reply/activity mapping、resource reference、opaque cursor、
+重复页拒绝，并确认 Core 没有 Group Chat 专用分支。Connector tests 另行验证 from-now bootstrap、credential-bound
+identity、cursor catch-up、重复读取幂等和正文不进入 Wake Bridge ledger。
+
+接入真实 Group Chat provider 时，维护方仍须验证 provider schema/version、principal scopes、credential revoke、
+offline restart/catch-up、读取副作用和真实 Host Adapter 投递。这些现场能力不由 reference fixture 自动保证。
+
+## 醒来后的读取
+
+Wake payload 只携带 resource reference。agent 醒来后使用 Group Chat 自己的 MCP：
+
+```text
+group.get_context / group.get_message
+  → understand authoritative room history
+  → group.mark_seen(actual message cursor)
+  → optional group.post_message
+```
+
+Wake Bridge 的 `agent_seen` 与 Group Chat 的 `member last_seen` 是不同事实。
+
+## 失败语义
+
+- Group Chat offline：adapter 记录 source unavailable，保留本地 cursor；其他 sources 继续。
+- schema version unsupported：停止该 source 并 needs_attention，不丢弃/猜测字段。
+- credential revoked：fail closed，不降级为匿名读取。
+- event resource tombstoned：仍可消费 tombstone/audit metadata，不要求正文存在。
+- Wake Bridge offline：Group Chat 正常运行，event log 等待稍后 catch up。
+
+## 独立性验收
+
+1. Group Chat 仓库不引用 Wake Bridge package、schema 或运行地址。
+2. adapter 可以只靠公开 event-feed fixture 完成 contract tests。
+3. 删除本 adapter，Wake Bridge 的 manual/timer/其他 sources 继续通过。
+4. 停止 Wake Bridge，Group Chat UI/API/MCP/event feed 继续通过自身测试。
+5. Wake Bridge core 不出现 Group Chat 专用 schema、数据库列或调度分支。
+6. 一个只实现公开 source fixtures 的第二 adapter 能通过同一 conformance suite。

package/docs/operations/connector-catalog.md

@@ -0,0 +1,40 @@
+# Source Connector catalog
+
+状态：current public catalog（2026-09-07）。Catalog 是可发现性清单，不是自动安装器；所有 connector 默认
+`disabled`，未配置时不会登录 provider、创建 checkpoint、轮询或产生 wake。
+
+查看机器可读清单：
+
+```sh
+wakebridge connector-catalog
+```
+
+## 当前条目
+
+| Connector | 类型 | 可用性 | Bundled | Enable |
+| --- | --- | --- | --- | --- |
+| 小机知道 | official optional | available | yes | 完成 configure → verify identity → from-now bootstrap → UAT 后可显式 enable |
+| Gmail | official optional | planned | no | 不可 enable；见 [planned status](../adapters/gmail-planned.md) |
+| Group Chat fixture | reference | available | yes | 仅用于 contract/conformance 与自建来源参考 |
+
+Catalog 的 `availability` 描述发行物能力；某个已配置 source 的 `disabled | enabled | needs_attention` 是运行状态，
+两者不可混用。`available` 也不等于已经登录、已启用或生产 SLA。
+
+## 小机知道：首次启用
+
+1. 按 [小机知道 Connector](../adapters/botlingknows.md) 启动独立 connector process，并让 provider credential
+   只留在该 process。
+2. 将 source 写入私有 `sources.json`，但保持 disabled。
+3. 运行 `attention_source_verify`，由 agent/operator 核对返回的 `subject_ref` 与 `binding_fingerprint`。
+4. 显式执行 `attention_source_bootstrap(mode="from-now")`，避免把历史通知当作新事件。
+5. 用一条专用测试通知验收 cursor、restart、`mark_read=false`、event/claim/wake 与 authoritative resource。
+6. UAT 通过后执行 `attention_source_enable`。失败时保持 disabled 或 `needs_attention`，不要盲目重试登录。
+
+命令行环境可用 `source-validate`、`source-bootstrap` 与 `source-once` 完成相同的低层验证。Connector 不携带默认
+唤醒策略；用户需单独安装 policy。仓库提供的
+[`botlingknows-conservative.json`](../../examples/policies/botlingknows-conservative.json) 只是可选 recipe：@mention
+即时但尊重 quiet hours/presence，其余通知排到本地 09:00。安装前应按自己的 attention channel 与节奏修改并 preview。
+这样同一条通知可以由不同 Agent Space 按各自节奏处理。
+
+当前 catalog 刻意不包含尚未沟通和验收的第三方来源。添加条目需要先明确公开接口、认证与权限、读取副作用、
+cursor/replay、速率限制、维护责任和真实 UAT，不因“能抓到数据”就自动成为 official connector。

package/docs/operations/operator-control.md

@@ -0,0 +1,83 @@
+# Operator status and dead-letter recovery
+
+状态：introduced in `wake-bridge@0.9.0-preview.3`; current in `0.9.0-preview.8`。
+
+这组命令面向单 Agent Space 的 operator，不属于第三方 SDK，也不进入 agent MCP。它只补运行态定位与永久投递失败的受控
+恢复，不替 agent 判断来源工作是否仍需处理。
+
+## Secret-free status
+
+停止或无法访问 daemon 时，可以直接读取 durable DB：
+
+```bash
+wakebridge status --config /absolute/path/wakebridge.config.json
+```
+
+这个路径以 observer mode 打开 Core，不回收 expired dispatch lease，也不运行 scheduler。它汇总：
+
+- 各 batch state 数量、当前 due 数、expired dispatch leases；
+- failed attempt 的 `error_class` 计数，以及最多 100 条 dead-letter / needs-attention 摘要；
+- endpoint/binding 的 live/stale 数量与 channel generation；
+- durable source checkpoint/control 摘要。
+
+离线读取无法观察另一个 daemon 进程内存中的 source supervisor，因此返回 `sources.runtime_observed=false`。运行中应优先请求
+owner-authenticated live endpoint：
+
+```bash
+curl --fail-with-body \
+  -H "Authorization: Bearer ${WAKEBRIDGE_ADMIN_TOKEN}" \
+  http://127.0.0.1:4311/v1/status
+```
+
+Live status 会加入 source 的 `healthy | backoff | needs_attention | stopped` 状态与已启动 Host Adapter 摘要。Source/host
+credential 不能调用该 endpoint。
+
+`health` 语义：
+
+- `healthy`：没有当前 queue/source/host degradation；
+- `degraded`：存在可自动恢复的 retry/backoff，或 batch 正等待 endpoint；
+- `needs_attention`：存在 dead letter、needs-attention batch、expired dispatch lease 或 source needs-attention。
+
+`ok=false` 与 CLI exit code `2` 只对应 `needs_attention`；`degraded` 仍返回 exit code `0`，但应由监控展示。Status 不返回 route
+address、lease token、session ref、provider error message、source credential 或 owner token。它只保留安全的 error class；详细 provider
+错误仍留在本地 DB/operator evidence 中，不进入结构化 health payload。
+
+## Dead-letter retry
+
+先读取 dead letter 的 `batch_id` 与当前 `attempt`，修复导致 permanent rejection 的 route、credential 或 provider configuration，
+再显式重开：
+
+```bash
+wakebridge batch-retry wb_... \
+  --config /absolute/path/wakebridge.config.json \
+  --expected-attempt 1 \
+  --reason "operator confirmed route repair"
+```
+
+运行中也可以使用 owner API：
+
+```bash
+curl --fail-with-body \
+  -X POST http://127.0.0.1:4311/v1/batches/wb_.../retry \
+  -H "Authorization: Bearer ${WAKEBRIDGE_ADMIN_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d '{"expected_attempt":1,"reason":"operator confirmed route repair"}'
+```
+
+Contract：
+
+1. 只接受 `dead_letter`；`needs_attention`、等待 endpoint、已 dispatched/seen 的 batch 不可重开；
+2. `expected_attempt` 是 CAS fence，防止旧命令重开更新后的失败 generation；
+3. 所有 claim 必须仍为 `batched`；已经 consume/dismiss/finalize 的工作不会被复活；
+4. 成功只把 batch 改为 `retry_wait` 并写 `dead_letter → retry_wait` transition，调用本身不 dispatch；
+5. 相同 attempt 的响应丢失后重放返回 `retried=false`，不会重复写 transition；
+6. 后续 canonical daemon scheduler 或 operator 显式 `dispatch` 才创建新 attempt；attempt number 会递增。
+
+Reason 会作为本地 transition audit 保存；不要把 credential、正文或其他 secret 写进 reason。命令限制为 1–200 个可打印字符。
+
+## 仍未覆盖的 operator hardening
+
+本票没有承诺 metrics backend、长期 structured log pipeline、dead-letter bulk replay、任意 export、Linux/systemd、端口扫描或自动
+backup drill。`doctor/release-preflight` 继续负责 runtime/schema/config permission readiness；backup/restore 流程见
+[release lifecycle](release-lifecycle.md)。这些剩余项应按独立风险与验收继续推进，不能因有了 status 就宣称 production operations
+全部完成。

package/docs/operations/out-of-process-host-adapter.md

@@ -0,0 +1,150 @@
+# Out-of-process local Host Adapter protocol
+
+状态：current public Host Adapter Contract。所有具体 host/product support 由 adapter 维护者按 host/version 独立声明；
+Wake Bridge package 本身不内置产品支持。
+
+这个协议面向已经有 backend agent session、bridge service 或自建 frontend 的宿主。外部 service 保管宿主身份与内部 credential，
+Wake Bridge daemon 只知道一个 opaque session、声明的 capability 与精确 loopback delivery route。
+
+它不是动态 plugin loader。Daemon 不 import 第三方代码，也不把 Core、DB、owner token 或 agent memory 交给 adapter。具体宿主实现仍是
+仓库外 integration；通过该协议不等于该宿主进入 Wake Bridge supported-host matrix。
+
+## 1. Operator 配置
+
+Bootstrap token 只放环境变量：
+
+```sh
+export WAKEBRIDGE_EXAMPLE_HOST_TOKEN="<至少 32 字符的随机 token>"
+```
+
+reference file 只保存 env 名、固定 host identity、允许的 channel 与诚实 capability：
+
+```json
+{
+  "version": 1,
+  "adapters": [
+    {
+      "id": "example-host-local",
+      "adapter_kind": "example_host",
+      "adapter_version": "1.0.0",
+      "host_kind": "example_host",
+      "tested_host_versions": ["your-host/1.0"],
+      "token_env": "WAKEBRIDGE_EXAMPLE_HOST_TOKEN",
+      "attention_channels": ["life"],
+      "capabilities": {
+        "warm_resume": true,
+        "cold_push": false,
+        "exact_live_route": true,
+        "requires_live_binding": true,
+        "queue_when_busy": true,
+        "session_activity_observable": true
+      },
+      "receipt_upper_bound": "host_accepted"
+    }
+  ]
+}
+```
+
+启动 daemon：
+
+```sh
+wakebridge daemon \
+  --config /absolute/path/wakebridge.config.json \
+  --host-adapters /absolute/path/host-adapters.json \
+  --host 127.0.0.1 --port 4311
+```
+
+启动前可以用同一 env/file 运行 `wakebridge doctor --config ... --host-adapters ...`。Doctor 只输出 adapter kind/version、host kinds、
+experimental tier 与错误摘要，不打印 token；缺失 env、无效 capability 或重复 kind 会令 readiness fail。
+
+当前文件只允许 `experimental` out-of-process adapters。`receipt_upper_bound` 只能是 `accepted_to_live_pipe` 或
+`host_accepted`；HTTP 202 不能声明 `agent_completed`。每个 adapter kind 与 credential id 必须唯一。
+
+## 2. 外部 service 生命周期
+
+仓库外 service 从 `wake-bridge/transport` 导入 `HostSessionClient`。它在确认自己的精确 session 后启动一个 credential-free
+loopback HTTP origin，并为该进程生成独立 route token：
+
+```ts
+import { HostSessionClient } from "wake-bridge/transport";
+
+const client = new HostSessionClient({
+  base_url: "http://127.0.0.1:4311",
+  host_token: process.env.WAKEBRIDGE_EXAMPLE_HOST_TOKEN!,
+  adapter_kind: "example_host",
+});
+
+const registration = await client.open({
+  session_ref: "opaque-session-id",
+  attention_channel: "life",
+  route_origin: "http://127.0.0.1:18790",
+  route_token: process.env.EXAMPLE_HOST_ROUTE_TOKEN!,
+});
+const lease = client.lease(registration);
+```
+
+Service 周期性 `renew(lease)`，正常退出时 `close(lease)`。重新 open 同一 session 会执行显式 takeover 并递增 binding generation；旧
+lease、旧 activity 与旧 delivery correlation 随后 fail closed。Route token 不得复用 owner、任一 host bootstrap 或 source token。
+
+`HostSessionClient` 只有 open/renew/close/presence/activity/wake-echo 方法，不能 inspect、emit、配置 policy、dispatch 或执行 operator retry。
+
+## 3. Delivery endpoint
+
+外部 service 实现：
+
+```text
+POST /v1/wakes
+Authorization: Bearer <per-process route token>
+X-WakeBridge-Delivery-Nonce: <same nonce as body>
+Content-Type: application/json
+```
+
+Body 使用 `LOCAL_HOST_PROTOCOL_VERSION=1`：
+
+```json
+{
+  "protocol_version": 1,
+  "attempt_id": "att_...",
+  "delivery_nonce": "opaque-one-shot-nonce",
+  "wake": {
+    "schema_version": 1,
+    "instance_id": "agent-a",
+    "wake_batch_id": "wb_...",
+    "attention_channel": "life",
+    "claim_refs": [],
+    "binding_generation": 3
+  }
+}
+```
+
+使用 `validateLocalHostDeliveryRequest()` 验证 body，并另行比较 nonce header。Wake payload 只有 durable reference 与有限 metadata，
+不是 prompt injection channel，也不复制来源正文。
+
+响应语义固定：
+
+- `202`：adapter 声明的 pipe/host 已接收；Core 只写 `transport_accepted`；
+- `408 | 425 | 429 | 5xx`：retryable；
+- 其他状态：permanent rejection，最终可进入 dead letter；
+- response body 被忽略，不进入 receipt、status 或 error message。
+
+Transport 使用有界 timeout、拒绝 redirects，只连接 `127.0.0.1` 或 `::1`。公网 URL、带 userinfo/path/query 的 origin 均在登记前
+拒绝。
+
+## 4. Activity 与更高层 receipt
+
+若 manifest 声明 `foreground_presence_observable`，adapter 必须只在真实用户 active edge 上调用
+`renewPresence(lease, { observed_by, observation, ttl_ms? })`。普通模型 activity、进程存活、窗口 focus 与 Wake echo 都不能续
+Foreground Presence Lease；Core 会同时核对 capability、endpoint token 与 current binding generation，未声明 observer 的 host
+调用会 fail closed。
+
+若 manifest 声明 `session_activity_observable`，外部 service 可以调用 `observeActivity()` 上报真实用户/runner activity，也可以在确认
+delivery nonce 确实进入相同 generation 后调用 `consumeWakeEcho()`。Wake echo 只建立可信 `wake_started` activity，不冒充
+`agent_seen`；batch 的 seen/consumed/acted 仍需 agent/harness 通过既有明确 acknowledgement 完成。
+
+## 5. 支持边界
+
+这项 contract 使自建 backend、CLI harness、frontend 或私有 runtime 可以独立实现 integration。它不使任何具体 runtime
+自动成为 Wake Bridge 支持对象。Core 不增加产品私有字段、不扫描 conversation、不读取 runtime DB、不选择最近窗口，也不
+承诺换窗后的 agent memory continuity。具体 adapter 必须用自己的真实 host/version 做 conformance 与 field canary。
+
+可运行的中立示例见 [Reference Host Adapter](../../examples/reference-host-adapter/README.md)。