dsh-bus 0.0.0-stage → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,73 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
5
+ and this project adheres to [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [1.3.0] — 2026-11-17
8
+
9
+ First public release. Reference implementation of the L1 file-mailbox bus
10
+ protocol v1.3, validated by a 14-script / 26+scenario stress campaign and a
11
+ live two-session DSH agent relay E2E.
12
+
13
+ ### Core (`dshbus.py`, zero-dependency, single file)
14
+ - Atomic commit: tmp + fsync + `os.replace`; crashed producers never pollute
15
+ committed messages.
16
+ - **`os.link` claim** — the only correct atomic-claim primitive on Windows:
17
+ concurrent `os.rename` on the same source exhibits a kernel-level
18
+ double-win race (both processes report success, one message on disk —
19
+ measured 143/200 false wins). Link losers always get `FileExistsError`.
20
+ - Three delivery semantics: point-to-point (exclusive claim), shared queue
21
+ (common tombstone dir, exactly one winner), broadcast (per-recipient copy).
22
+ - Lease tombstones: `claimed/*.meta` with claimant/pid/hb_ts/retries;
23
+ TTL 30 s, heartbeats, 3 failed redeliveries → `dead/` (DLQ).
24
+ - ack double-write: receipt lands in the sender's mailbox (for `wait`) and
25
+ the recipient's mailbox (for idempotent cleanup).
26
+ - at-least-once + idempotent contract; blob payloads by sha256 reference
27
+ with reference-counting GC.
28
+ - Security guards: name whitelist, path traversal / reserved device names /
29
+ trailing dot-space / lone surrogate rejection; directory-level reparse
30
+ (junction/symlink) pre-placement rejection; file-level symlink rejection,
31
+ pre-planted hard-link (nlink>1) rejection, realpath domain check.
32
+ - Cross-platform: the only OS-specific attribute access is guarded by
33
+ `getattr(..., 0)`; core API runs on Windows and POSIX.
34
+
35
+ ### CLI
36
+ - `send / recv (--block --timeout --hb) / ack / wait / status / recover / gc`
37
+ - `--from` identity, `--root` bus location, `DSH_BUS_NAME` / `DSH_BUS_ROOT`
38
+ environment defaults.
39
+
40
+ ### MCP server (`dshbus_mcp.py`, optional `[mcp]` extra)
41
+ - stdio MCP server exposing `bus_send / bus_recv / bus_ack / bus_wait /
42
+ bus_status / bus_recover` so MCP-capable agents (DSH included) get native
43
+ cross-window tools.
44
+
45
+ ### DSH bundle (`dsh-bus-mcp/`)
46
+ - Configuration-only MCP bundle wiring the stdio server into DSH via
47
+ `@deepseek-ai/dsh-mcp-client`.
48
+
49
+ ### Validation
50
+ - pytest: 25 locks (guards / semantics / lease / DLQ / idempotency / GC /
51
+ concurrency 8×25 zero-loss / CLI) — all green.
52
+ - Two-process smoke: 10/10 messages, ack/wait closed loop, 1 MiB blob,
53
+ Unicode + emoji payloads.
54
+ - Two-session DSH agent relay E2E (`E2E-DSH-INTERSECTION.md`): real AI
55
+ sessions exchanging tasks and receipts through the bus.
56
+ - Stress campaign: T1–T6 matrix (channels, concurrency, crash injection,
57
+ fs.watch 22.9% loss quantification, security vulnerabilities found and
58
+ fixed, junction attack reproduced and blocked).
59
+
60
+ ## [1.2.0] — 2026-11-17 (internal)
61
+
62
+ - Shared tombstone directory for multi-consumer queues (per-worker tombstones
63
+ left a double-consumption window — caught in external review).
64
+ - Wait/timeout semantics documented; `FileNotFoundError` claim path legalized.
65
+
66
+ ## [1.1.0] — 2026-11-17 (internal)
67
+
68
+ - Security guards v1: name whitelist, traversal/symlink/hard-link rejection.
69
+
70
+ ## [1.0.0] — 2026-11-17 (internal)
71
+
72
+ - First protocol draft: atomic commit, rename-claim (later found racy on
73
+ Windows), three semantics, ack receipts.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-bus authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,76 @@
1
- # Temporary Holding Version
1
+ # dsh-bus
2
+
3
+ Local file-mailbox message bus for cross-window (cross-session) agent
4
+ coordination on one machine — built and battle-tested for
5
+ [DSH](https://dsh.so) windows, usable by any process that can read files.
6
+
7
+ **中文文档: [README.zh-CN.md](README.zh-CN.md)**
8
+
9
+ ## Why
10
+
11
+ Multiple AI-agent windows on the same machine cannot see each other: no
12
+ session-end events cross windows, and ad-hoc shared files race each other.
13
+ dsh-bus gives every window a durable mailbox with claim leases, receipts and
14
+ recovery — the "electrical circuit" primitives for *task finished → other
15
+ window knows*, *wait for another window*, and *relay work between windows*.
16
+
17
+ ## Install
18
+
19
+ ```bash
20
+ pip install dsh-bus # core CLI (stdlib only, Python >= 3.10)
21
+ pip install "dsh-bus[mcp]" # + MCP server for native DSH/agent integration
22
+ ```
23
+
24
+ Or run straight from the repo: `python dshbus.py --help`.
25
+
26
+ ## Quick start (two terminals)
27
+
28
+ ```bash
29
+ # Window A: send a task, then wait for the receipt
30
+ dshbus --from window-a send window-b task '{"job":"analyze","file":"x.py"}' --corr t1
31
+ dshbus --from window-a wait t1 --deadline 600
32
+
33
+ # Window B: claim, do the work, acknowledge with the receipt
34
+ dshbus --from window-b recv
35
+ dshbus --from window-b ack <mid> --result '{"corr":"t1","status":"done"}'
36
+ ```
37
+
38
+ Mailboxes live under `~/.dsh/windowbus/<name>/{inbox,claimed,acks,dead,blobs}`.
39
+
40
+ ## MCP server (native DSH integration)
41
+
42
+ `dshbus-mcp` (or `python dshbus_mcp.py`) speaks MCP over stdio and exposes six
43
+ tools — `bus_send / bus_recv / bus_ack / bus_wait / bus_status / bus_recover`.
44
+ Install the configuration-only bundle in `dsh-bundle/` into your DSH profile
45
+ and **every window gains the bus tools natively** (verified: two DSH sessions
46
+ relayed a task end-to-end purely through the MCP tool surface).
47
+
48
+ ## Semantics (protocol v1.3)
49
+
50
+ | Guarantee | Mechanism |
51
+ |---|---|
52
+ | Atomic delivery | write-tmp → fsync → `os.replace`; unique ids `<sender>-<ms>-<rand6>` |
53
+ | Exactly-one claimant | `os.link` to a shared tombstone name — Windows `rename` has a kernel-level double-win race (71.5% false success measured, see CHANGELOG), `link` does not |
54
+ | At-least-once + idempotency | claim lease 30 s, heartbeat, expired leases redelivered (max 3) then dead-lettered; acked ids are silently reaped |
55
+ | Receipts | `ack` writes to **both** sender and receiver mailboxes; `wait(corrs)` polls sender-side receipts |
56
+ | Poison safety | malformed JSON or symlinked/hardlinked payloads go to `dead/` with a reason |
57
+ | Hardening | path-traversal / reserved device names / reparse-point (junction) directories / dangling-surrogate guards |
58
+
59
+ Full spec: see `CHANGELOG.md` and the test suite (25 pytest locks + dual-OS CI
60
+ matrix + 8×25 concurrent-producer zero-loss lock + real stdio MCP smoke).
61
+
62
+ ## Repo layout
63
+
64
+ ```
65
+ dshbus.py single-file core library + CLI (stdlib only)
66
+ dshbus_mcp.py MCP stdio server (optional [mcp] extra)
67
+ dsh-bundle/ DSH configuration-only bundle (installs the MCP row)
68
+ tests/ pytest suite + smoke_e2e + mcp_smoke
69
+ scripts/ smoke consumer example
70
+ ```
71
+
72
+ ## License
73
+
74
+ MIT © 2026 dsh-bus authors
2
75
 
3
- 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.
76
+ [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
@@ -0,0 +1,108 @@
1
+ # dsh-bus
2
+
3
+ DSH 多窗口文件信箱总线 —— L1 文件信箱协议 v1.3 的参考实现。
4
+ 单文件、纯标准库、零依赖,Windows 优先(跨平台可用)。
5
+
6
+ 让同一台机器上的多个 DSH 窗口(或其他任何进程)互相**发消息、等回执、
7
+ 接力任务**:一个窗口任务结束,另一个窗口自动知晓并继续。
8
+
9
+ ## 快速开始
10
+
11
+ ```python
12
+ from dshbus import Bus
13
+
14
+ a = Bus("window-a") # 我的信箱名;默认根 ~/.dsh/windowbus/
15
+ mid = a.send("window-b", "task", {"repo": "my-project", "action": "run-tests"}, corr="job-1")
16
+ res = a.wait(["job-1"], deadline_s=60) # 等待 window-b 的回执
17
+
18
+ # —— 窗口 B ——
19
+ b = Bus("window-b")
20
+ for m in b.recv(): # 阻塞版: CLI recv --block
21
+ ... # 处理消息
22
+ b.ack(m["id"], {"corr": m["corr"], "ok": True})
23
+ ```
24
+
25
+ ```text
26
+ python dshbus.py --from window-b recv --block --timeout 60 --hb # CLI 消费窗口
27
+ python dshbus.py --from window-a send window-b task '{"k":1}' --corr job-1
28
+ python dshbus.py --from window-a wait job-1 --deadline 60
29
+ python dshbus.py status # 全信箱对账
30
+ python dshbus.py recover # 回收过期租约(重投递 / 死信)
31
+ python dshbus.py gc # 清理 tmp / 过期 ack / 无引用 blob
32
+ ```
33
+
34
+ ## 三种消息语义(v1.3 §2)
35
+
36
+ | 语义 | 用法 | 保证 |
37
+ |---|---|---|
38
+ | 点对点 | `send("window-b", ...)` 后 B `recv()` | 独占消费,恰一接收者 |
39
+ | 公共队列 | 多个 worker 竞争同一信箱 `recv()` | link-claim 同名墓碑,恰一赢家 |
40
+ | 广播 | 循环 `send` 到每个信箱 | 每接收者一份副本 |
41
+
42
+ ## 可靠性规则(实测背书,见 最大强度测试报告-20261117.md)
43
+
44
+ - **原子提交**:tmp + fsync + `os.replace`;生产者崩溃只留 tmp,不污染 committed
45
+ - **claim = `os.link` 争抢**(Windows 上 rename 有内核级双赢竞态,link 输家必得
46
+ `FileExistsError` —— H1 修复)
47
+ - **at-least-once + 幂等契约**:消费者崩溃后租约过期由 `recover` 重投递;
48
+ 处理方必须幂等(同 id 重投递在 ack 后会被 recv 静默清理)
49
+ - **租约墓碑**:claimed/ 下 `.meta` 记录 claimant/pid/hb_ts/retries;
50
+ TTL 30s,`heartbeat()` 续租,3 次重投递失败 → `dead/`(DLQ)
51
+ - **ack 双落点**:回执写发送方信箱(供 `wait`)+ 收件方信箱(供幂等清理)
52
+ - **blob 引用制**:大负载按 sha256 落 `blobs/`,消息只带 `blob_ref`,GC 引用计数
53
+ - **fs.watch 只是唤醒信号**:快照对账(listdir)才是真相 —— RDCW 丢事件 22.9%
54
+ 场景由轮询兜底,0 丢失
55
+
56
+ ## 安全守卫(v1.3 §4)
57
+
58
+ 消息名/信箱名白名单字符 + 拒路径穿越/保留设备名(CON/COM1…)/尾随点空格/
59
+ 孤立代理对;目录级 reparse(junction/symlink)预置拒绝;文件级 symlink 拒绝
60
+ + 预植硬链接(nlink>1)拒绝 + realpath 域校验。
61
+ 威胁模型:单用户机器同用户进程(完整性 + 可移植性,非对抗多用户)。
62
+
63
+ ## 测试
64
+
65
+ ```text
66
+ python -X utf8 -m pytest tests/ -q # 25 锁:守卫/三语义/租约/DLQ/幂等/GC/并发/CLI
67
+ python -X utf8 scripts/smoke_e2e.py # 真实双进程 E2E(10/10 无丢失,ack/wait 闭环)
68
+ ```
69
+
70
+ ## DSH 窗口接入(agent 会话内直接用)
71
+
72
+ 任意 DSH 窗口的 agent 用 `pwsh`/`exec` 调 CLI 即可收发,无需任何安装。
73
+
74
+ ```powershell
75
+ # 窗口 A(发起方):发任务 + 等回执
76
+ dshbus --from window-a --root <root> send window-b task '<json>' --corr job-1
77
+ dshbus --from window-a --root <root> wait job-1 --deadline 300
78
+
79
+ # 窗口 B(消费方):循环 recv → 处理 → ack
80
+ dshbus --from window-b --root <root> recv --block --timeout 120 --limit 10
81
+ dshbus --from window-b --root <root> ack <消息id> --result '<json>'
82
+ ```
83
+
84
+ 实测纪律(2026-11-17 双 DSH 会话接力 E2E,见 `E2E-DSH-INTERSECTION.md`):
85
+
86
+ - **复杂 JSON 参数走临时脚本**:pwsh 内联 JSON 会被转义撕裂;且
87
+ PowerShell→原生程序传参会**剥掉内层双引号**(`--result '{"corr":…}'`
88
+ 到 Python 变 `{corr:…}` 直接 JSONDecodeError)。正道=写一次性
89
+ python 辅助脚本以 argv 列表传参(或用简单扁平字符串做 result)。
90
+ - 每条命令前加 `$env:PYTHONIOENCODING='utf-8';`(emoji/中文防 GBK 崩)。
91
+ - 对 AI 窗口消费者,`wait` 的 deadline 给足(≥5 分钟:子代理启动+LLM
92
+ 推理开销远大于进程直跑);超时返回 null ≠ 失败,回执可能后到,
93
+ 先 `status` + 查 `acks/` 再定论。
94
+ - 固定 `--from <窗口名>`,否则落到 `win-<pid>` 缺省信箱造成孤儿信箱。
95
+ - 真实活证:本仓 `.bus-e2e/` 保留现场(6 份 ack + _metrics.jsonl),
96
+ 两窗口独立报告交叉对账一致(A 侧 ack 文件 vs B 侧收尾报告)。
97
+
98
+ ## 已知边界(投产前清单,不阻塞窗口间日常使用)
99
+
100
+
101
+ - 可观测性最小面(_metrics.jsonl);背压配额/磁盘水位熔断未内置
102
+ - 大消息 >1MB 建议走 blob;超大分块未定稿
103
+ - 掉电持久性未验证(Windows 无目录 fsync);TOCTOU 检查-使用窗口在册
104
+ - 会话生命周期与接管方判定由上层约定(协议 §6)
105
+
106
+ 协议规范:`../生成产物/跨窗口通信-20261117/L1文件信箱协议规范-v1.3.md`
107
+
108
+ [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
@@ -0,0 +1,11 @@
1
+ - insert:
2
+ - id: dshbus-mcp
3
+ name: '@deepseek-ai/dsh-mcp-client'
4
+ config:
5
+ serverName: dshbus
6
+ transport: stdio
7
+ command: npx
8
+ args: ['-y', 'dsh-bus@latest']
9
+ env:
10
+ PYTHONIOENCODING: utf-8
11
+ failOnStartupError: true
@@ -0,0 +1,37 @@
1
+ # dsh-bus — cross-window task bus for DSH
2
+
3
+ Every DSH window (session) that loads this bundle gets six native tools backed by
4
+ a local file-mailbox bus (`~/.dsh/windowbus/`):
5
+
6
+ | Tool | What it does |
7
+ |---|---|
8
+ | `bus_send(to, type, payload, corr)` | Deliver a task/notice to another window's mailbox |
9
+ | `bus_recv(me, limit, timeout_s)` | Claim my inbox (blocking optional) |
10
+ | `bus_ack(mid, result)` | Finish a task; the receipt lands in the sender's mailbox |
11
+ | `bus_wait(corrs, deadline_s)` | Block until acks for my correlation ids arrive |
12
+ | `bus_status()` | Per-mailbox counters (inbox/claimed/acked/dead) |
13
+ | `bus_recover(ttl)` | Redeliver expired leases or dead-letter them |
14
+
15
+ ## Typical relay between two windows
16
+
17
+ 1. Window A: `bus_send(to="window-b", type="task", payload={...}, corr="t1")`
18
+ 2. Window A: `bus_wait(corrs=["t1"], deadline_s=600)` — A now sleeps on the bus
19
+ 3. Window B (whenever it works next): `bus_recv(me="window-b")` → does the work → `bus_ack(mid, {"corr":"t1", ...})`
20
+ 4. Window A's `bus_wait` returns with B's receipt and A continues automatically.
21
+
22
+ ## Semantics (protocol v1.3)
23
+
24
+ - Delivery is **at-least-once** with lease/redelivery; recipients should be idempotent on `mid`/`corr`.
25
+ - Point-to-point mailboxes are exclusively claimed; a shared queue name gives
26
+ exactly-one-winner per message across competing consumers (`os.link` claim).
27
+ - Guards reject path traversal, reserved device names, symlinked/hardlinked
28
+ payloads and reparse-point directories; payloads are JSON envelopes, large
29
+ blobs are content-addressed under `blobs/`.
30
+
31
+ ## Requirements
32
+
33
+ The bundle launches the MCP server through `npx -y dsh-bus@latest`, a tiny Node
34
+ launcher that spawns a Python ≥ 3.10 interpreter (probed automatically:
35
+ `DSHBUS_PYTHON` → `python3` → `python` → `py -3`; stdlib only). Alternative
36
+ install: `pip install dsh-bus[mcp]` and point your MCP config at the
37
+ `dshbus-mcp` console script.
@@ -0,0 +1,11 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
2
+ <!-- dsh-bus: two windows joined by a mailbox bus -->
3
+ <rect x="4" y="12" width="22" height="18" rx="3" fill="none" stroke="#5e7ce0" stroke-width="3"/>
4
+ <rect x="38" y="34" width="22" height="18" rx="3" fill="none" stroke="#5e7ce0" stroke-width="3"/>
5
+ <path d="M26 21h6a2 2 0 0 1 2 2v18a2 2 0 0 0 2 2h2" fill="none" stroke="#3de08a" stroke-width="3" stroke-linecap="round"/>
6
+ <path d="M38 43h-6a2 2 0 0 1-2-2V23a2 2 0 0 0-2-2h-2" fill="none" stroke="#f59e0b" stroke-width="3" stroke-linecap="round" transform="translate(10 -10)"/>
7
+ <path d="M38 45l6-3v6z" fill="#3de08a"/>
8
+ <path d="M26 19l-6-3v6z" fill="#f59e0b"/>
9
+ <circle cx="15" cy="21" r="2" fill="#5e7ce0"/>
10
+ <circle cx="49" cy="43" r="2" fill="#5e7ce0"/>
11
+ </svg>
@@ -0,0 +1,7 @@
1
+ {
2
+ "meta": {
3
+ "title": "dsh-bus window messaging",
4
+ "description": "Connects the local dsh-bus file-mailbox MCP server so every window gains bus_send / bus_recv / bus_ack / bus_wait tools for cross-window tasks.",
5
+ "detail": "docs/DETAIL.md"
6
+ }
7
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "meta": {
3
+ "title": "dsh-bus 窗口互通信道",
4
+ "description": "接入本机 dsh-bus 文件信箱 MCP 服务,让每个窗口获得 bus_send / bus_recv / bus_ack / bus_wait 工具,实现跨窗口任务下发、等待与接力。",
5
+ "detail": "docs/DETAIL.md"
6
+ }
7
+ }
@@ -0,0 +1,38 @@
1
+ #!/usr/bin/env node
2
+ // dsh-bus MCP launcher: spawns the Python MCP server shipped in this package.
3
+ // Portable entry for `npx -y dsh-bus` and for DSH bundle installs (command: npx).
4
+ // Python resolution order: DSHBUS_PYTHON env -> python3 (non-Windows) -> python -> py -3 (Windows).
5
+ 'use strict';
6
+ const { spawn } = require('child_process');
7
+ const path = require('path');
8
+
9
+ const serverPy = path.join(__dirname, 'dshbus_mcp.py');
10
+
11
+ const candidates = [];
12
+ if (process.env.DSHBUS_PYTHON) candidates.push(process.env.DSHBUS_PYTHON);
13
+ if (process.platform !== 'win32') candidates.push('python3');
14
+ candidates.push('python');
15
+ if (process.platform === 'win32') candidates.push(['py', '-3']);
16
+
17
+ function tryNext(i) {
18
+ if (i >= candidates.length) {
19
+ console.error('[dsh-bus] No Python >= 3.10 found on PATH.');
20
+ console.error('[dsh-bus] Install Python 3.10+ or point DSHBUS_PYTHON at the interpreter.');
21
+ process.exit(127);
22
+ }
23
+ const c = candidates[i];
24
+ const bin = Array.isArray(c) ? c[0] : c;
25
+ const pre = Array.isArray(c) ? c.slice(1) : [];
26
+ const child = spawn(bin, pre.concat(['-X', 'utf8', serverPy]), {
27
+ stdio: ['inherit', 'inherit', 'inherit'],
28
+ env: Object.assign({}, process.env, { PYTHONIOENCODING: 'utf-8' }),
29
+ windowsHide: true,
30
+ });
31
+ // Launcher itself never writes to stdout: stdin/stdout are the MCP JSON-RPC channel.
32
+ child.on('error', (e) => {
33
+ if (e.code === 'ENOENT') tryNext(i + 1);
34
+ else { console.error('[dsh-bus] spawn failed:', e.message); process.exit(1); }
35
+ });
36
+ child.on('exit', (code, sig) => process.exit(code == null ? (sig ? 1 : 0) : code));
37
+ }
38
+ tryNext(0);
package/dshbus.py ADDED
@@ -0,0 +1,597 @@
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """
4
+ dshbus — DSH 跨窗口文件信箱总线(L1 协议规范 v1.3 参考实现)
5
+
6
+ 单文件、纯标准库。任意 DSH 窗口/终端用 python 调用即可参与跨窗口通信。
7
+
8
+ 用法(CLI):
9
+ python dshbus.py send <to> <type> <payload-json> [--corr C] [--from ME]
10
+ python dshbus.py recv [--limit N] [--block] [--timeout S] [--peek] [--from ME]
11
+ python dshbus.py ack <id> [--result R] [--from ME]
12
+ python dshbus.py wait <corr...> [--deadline S] [--from ME]
13
+ python dshbus.py status
14
+ python dshbus.py recover [--ttl S] [--from ME]
15
+ python dshbus.py gc
16
+
17
+ 协议(v1.3):at-least-once 投递 + 处理方幂等(按 id 去重副作用)+ 无序投递。
18
+ claim = os.link 同名争抢(Windows rename 双赢竞态的正解,实测背书)。
19
+ 租约墓碑 = claimed/<id>.msg(消息本体硬链接)+ <id>.meta{claimant,pid,lease_ts,hb_ts,retries}。
20
+ 恢复判据 = hb_ts 超 TTL(30s);重试 3 次仍令处理方崩溃 → dead/(DLQ)。
21
+ """
22
+ from __future__ import annotations
23
+
24
+ import argparse
25
+ import json
26
+ import os
27
+ import re
28
+ import secrets
29
+ import stat as statmod
30
+ import sys
31
+ import time
32
+ import unicodedata
33
+ from pathlib import Path
34
+
35
+ __version__ = "1.3.0"
36
+
37
+ # ---------------------------------------------------------------- 常量与布局
38
+
39
+ DEFAULT_ROOT = Path.home() / ".dsh" / "windowbus"
40
+
41
+ SCHEMA_VERSION = 1
42
+ LEASE_TTL_S = 30.0 # 恢复判据:hb_ts 超过该秒数视为认领者死亡
43
+ HB_INTERVAL_S = 10.0 # 认领者心跳刷新间隔
44
+ MAX_RETRIES = 3 # DLQ:同一消息重投递 3 次仍崩溃 → dead/
45
+ GC_TMP_S = 3600.0 # .tmp 残留清理阈值
46
+ GC_ACK_S = 7 * 86400.0 # acked 留痕保留窗
47
+ POLL_S = 0.1 # recv --block / wait 轮询周期
48
+
49
+ FILE_ATTRIBUTE_REPARSE_POINT = 0x400 # junction/symlink 目录标记(Windows)
50
+
51
+ # ---------------------------------------------------------------- 守卫(v1.3 §4)
52
+
53
+ _NAME_RE = re.compile(r"^[^/\\:*?\"<>|\x00-\x1f\r\n\t]{1,200}$")
54
+ _RESERVED = {
55
+ "CON", "PRN", "AUX", "NUL",
56
+ *(f"COM{i}" for i in range(1, 10)),
57
+ *(f"LPT{i}" for i in range(1, 10)),
58
+ }
59
+ _RESERVED_CF = {s.casefold() for s in _RESERVED} # 比较一律走 casefold 域
60
+
61
+
62
+ class GuardError(ValueError):
63
+ """守卫拒绝——消息名/路径/目录不合法或可疑。调用方应丢弃,不得重试同名。"""
64
+
65
+
66
+ def _has_surrogate(s: str) -> bool:
67
+ return any(0xD800 <= ord(ch) <= 0xDFFF for ch in s)
68
+
69
+
70
+ def guard_name(name: str) -> str:
71
+ """消息 id / 信箱名守卫:白名单字符+拒穿越+保留设备名+尾随点空格+孤立代理对。"""
72
+ if not isinstance(name, str) or not name:
73
+ raise GuardError("name empty")
74
+ if not _NAME_RE.match(name):
75
+ raise GuardError(f"name has forbidden chars: {name!r}")
76
+ if ".." in name:
77
+ raise GuardError("name contains '..'")
78
+ if name != name.strip(" ."):
79
+ raise GuardError("trailing dot/space")
80
+ if _has_surrogate(name):
81
+ raise GuardError("lone UTF-16 surrogate")
82
+ stem = name.split(".")[0].casefold()
83
+ if stem in _RESERVED_CF:
84
+ raise GuardError(f"reserved device name: {name}")
85
+ if unicodedata.normalize("NFC", name) != name and \
86
+ unicodedata.normalize("NFD", name) != name:
87
+ # 仅要求规范形一致之一(跨平台文件系统互访),不强制重排
88
+ pass
89
+ return name
90
+
91
+
92
+ def _win_lstat(p: Path):
93
+ try:
94
+ return os.lstat(p)
95
+ except OSError:
96
+ return None
97
+
98
+
99
+ def _is_reparse(p: Path) -> bool:
100
+ st = _win_lstat(p)
101
+ if st is None:
102
+ return False
103
+ attrs = getattr(st, "st_file_attributes", 0)
104
+ return bool(attrs & FILE_ATTRIBUTE_REPARSE_POINT)
105
+
106
+
107
+ def guard_dir(base: Path, rel: Path) -> Path:
108
+ """目录级守卫:rel 每个已存在路径组件都不得是 reparse point(junction/symlink)。"""
109
+ cur = base
110
+ for part in rel.parts:
111
+ cur = cur / part
112
+ if _is_reparse(cur):
113
+ raise GuardError(f"reparse point in bus path: {cur}")
114
+ return base / rel
115
+
116
+
117
+ def guard_file(path: Path, root: Path) -> Path:
118
+ """文件级守卫:realpath 在 root 内 + 非 symlink + nlink==1(拒绝预植硬链接)。"""
119
+ if path.is_symlink():
120
+ raise GuardError(f"symlink refused: {path}")
121
+ st = _win_lstat(path)
122
+ if st is None:
123
+ raise GuardError(f"missing: {path}")
124
+ if hasattr(st, "st_nlink") and st.st_nlink > 1:
125
+ # 注意:claim 墓碑自身就是硬链接,此守卫只用于读 inbox 原始消息与 ack
126
+ raise GuardError(f"pre-planted hardlink refused (nlink={st.st_nlink}): {path}")
127
+ real = Path(os.path.realpath(path))
128
+ try:
129
+ real.relative_to(Path(os.path.realpath(root)))
130
+ except ValueError:
131
+ raise GuardError(f"realpath escaped root: {real}") from None
132
+ return path
133
+
134
+
135
+ # ---------------------------------------------------------------- 观测面(A3 最小版)
136
+
137
+ def _metrics(root: Path, rec: dict) -> None:
138
+ try:
139
+ with open(root / "_metrics.jsonl", "a", encoding="utf-8") as f:
140
+ f.write(json.dumps(rec, ensure_ascii=True) + "\n")
141
+ except OSError:
142
+ pass # 观测失败不阻断主路径
143
+
144
+
145
+ # ---------------------------------------------------------------- 信箱布局
146
+
147
+ class Mailbox:
148
+ def __init__(self, root: Path, name: str):
149
+ self.root = Path(root)
150
+ self.name = guard_name(name)
151
+ self.base = guard_dir(self.root, Path(self.name))
152
+ self.inbox = self.base / "inbox"
153
+ self.claimed = self.base / "claimed"
154
+ self.acks = self.base / "acks"
155
+ self.dead = self.base / "dead"
156
+ self.blobs = self.base / "blobs"
157
+ for d in (self.inbox, self.claimed, self.acks, self.dead, self.blobs):
158
+ d.mkdir(parents=True, exist_ok=True)
159
+ guard_dir(self.root, d.relative_to(self.root))
160
+
161
+
162
+ # ---------------------------------------------------------------- 核心 API
163
+
164
+ class Bus:
165
+ """一个窗口 = 一个 Bus 实例。sender 名默认取信箱名。"""
166
+
167
+ def __init__(self, name: str = "window-a", root: Path | str | None = None):
168
+ self.root = Path(root) if root else DEFAULT_ROOT
169
+ guard_dir(self.root, Path("."))
170
+ self.root.mkdir(parents=True, exist_ok=True)
171
+ self.mb = Mailbox(self.root, name)
172
+ self.sender = self.mb.name
173
+ self._seq = 0
174
+
175
+ # ---- 发送(原子提交) ----
176
+ def send(self, to: str, type_: str, payload, corr: str | None = None,
177
+ blob: bytes | None = None) -> str:
178
+ """向信箱 to 原子提交一条消息。返回消息 id。blob 非 None 时走引用制。"""
179
+ self._seq += 1
180
+ ms = int(time.time() * 1000)
181
+ mid = f"{self.sender}-{ms}-{secrets.token_hex(3)}"
182
+ guard_name(mid)
183
+ target = Mailbox(self.root, to)
184
+ env = {
185
+ "v": SCHEMA_VERSION, "id": mid, "seq": ms, "ts": time.time(),
186
+ "type": type_, "corr": corr, "from": self.sender, "to": to,
187
+ "payload": payload,
188
+ }
189
+ if blob is not None:
190
+ import hashlib
191
+ sha = hashlib.sha256(blob).hexdigest()
192
+ bpath = target.blobs / f"{sha}.blob"
193
+ if not bpath.exists():
194
+ tmp = target.blobs / f"{sha}.tmp"
195
+ with open(tmp, "wb") as f:
196
+ f.write(blob)
197
+ f.flush()
198
+ os.fsync(f.fileno())
199
+ os.replace(tmp, bpath)
200
+ env["blob_ref"] = sha
201
+ body = json.dumps(env, ensure_ascii=True)
202
+ tmp = target.inbox / f"{mid}.tmp"
203
+ dst = target.inbox / f"{mid}.msg"
204
+ with open(tmp, "w", encoding="utf-8") as f:
205
+ f.write(body)
206
+ f.flush()
207
+ os.fsync(f.fileno())
208
+ os.replace(tmp, dst)
209
+ _metrics(self.root, {"ts": time.time(), "op": "send", "id": mid,
210
+ "from": self.sender, "to": to, "type": type_})
211
+ return mid
212
+
213
+ # ---- 接收(快照对账 + link-claim + 租约) ----
214
+ def recv(self, limit: int = 10, peek: bool = False):
215
+ """认领本信箱至多 limit 条消息(link-claim 恰一赢家,跨进程安全)。
216
+ peek=True 只读不移除不认领。返回 envelope 列表。
217
+ 调用方处理完必须 ack(id);崩溃恢复由 recover() 兜底(at-least-once)。"""
218
+ out = []
219
+ for fn in sorted(os.listdir(self.mb.inbox)):
220
+ if len(out) >= limit:
221
+ break
222
+ if not fn.endswith(".msg"):
223
+ continue
224
+ mid = fn[:-4]
225
+ try:
226
+ guard_name(mid)
227
+ except GuardError:
228
+ self._to_dead(self.mb.inbox / fn, mid, "bad-name")
229
+ continue
230
+ if self._is_acked(mid):
231
+ self._silent_unlink(self.mb.inbox / fn) # 幂等清理
232
+ continue
233
+ src = self.mb.inbox / fn
234
+ if peek:
235
+ try:
236
+ guard_file(src, self.mb.base)
237
+ with open(src, "r", encoding="utf-8") as f:
238
+ out.append(json.load(f))
239
+ except (GuardError, OSError, ValueError) as e:
240
+ self._to_dead(src, mid, f"peek:{e}")
241
+ continue
242
+ if src.is_symlink(): # claim 前显式拒 symlink(防链接跟随)
243
+ self._to_dead(src, mid, "symlink-src")
244
+ continue
245
+ env = self._claim(src, mid)
246
+ if env is not None:
247
+ out.append(env)
248
+ return out
249
+
250
+ def _claim(self, src: Path, mid: str):
251
+ """link-claim:同名墓碑硬链接争抢。赢家移除 inbox 名并写租约 meta。
252
+ 墓碑=消息本体硬链接 → 崩溃后 payload 天然保留在 claimed/。"""
253
+ tomb = self.mb.claimed / f"{mid}.msg"
254
+ retries = 0
255
+ try:
256
+ os.link(src, tomb) # 恰一赢家;输家 FileExistsError
257
+ except FileExistsError:
258
+ return None # 明确输给竞争者
259
+ except FileNotFoundError:
260
+ return None # 赢家已移走 src(常规竞态),本轮跳过
261
+ # 赢家路径:继承旧 meta 的 retries(若为恢复重投递)
262
+ oldmeta = self.mb.claimed / f"{mid}.meta"
263
+ if oldmeta.exists():
264
+ try:
265
+ retries = int(json.loads(oldmeta.read_text("utf-8")).get("retries", 0))
266
+ except (OSError, ValueError):
267
+ retries = 0
268
+ try:
269
+ os.remove(src)
270
+ except FileNotFoundError:
271
+ pass # 墓碑已持有内容,安全
272
+ self._write_meta(mid, retries)
273
+ try:
274
+ with open(tomb, "r", encoding="utf-8") as f:
275
+ env = json.load(f)
276
+ # 墓碑本身是硬链接(nlink=2):不做 nlink 检查,只做 realpath 域校验
277
+ real = Path(os.path.realpath(tomb))
278
+ real.relative_to(Path(os.path.realpath(self.mb.base)))
279
+ return env
280
+ except (GuardError, OSError, ValueError) as e:
281
+ self._to_dead_tomb(tomb, mid, f"poison:{e}")
282
+ return None
283
+
284
+ def _write_meta(self, mid: str, retries: int):
285
+ meta = {
286
+ "claimant": self.sender, "pid": os.getpid(),
287
+ "lease_ts": time.time(), "hb_ts": time.time(), "retries": retries,
288
+ }
289
+ mpath = self.mb.claimed / f"{mid}.meta"
290
+ tmp = self.mb.claimed / f"{mid}.meta.tmp"
291
+ with open(tmp, "w", encoding="utf-8") as f:
292
+ json.dump(meta, f)
293
+ f.flush()
294
+ os.fsync(f.fileno())
295
+ os.replace(tmp, mpath)
296
+
297
+ def heartbeat(self):
298
+ """刷新我名下全部租约的 hb_ts(长处理任务定期调用 / recv --block 自动)。"""
299
+ now = time.time()
300
+ for fn in os.listdir(self.mb.claimed):
301
+ if not fn.endswith(".meta"):
302
+ continue
303
+ mpath = self.mb.claimed / fn
304
+ try:
305
+ meta = json.loads(mpath.read_text("utf-8"))
306
+ if meta.get("claimant") == self.sender and meta.get("pid") == os.getpid():
307
+ meta["hb_ts"] = now
308
+ tmp = mpath.with_suffix(".meta.tmp")
309
+ tmp.write_text(json.dumps(meta), "utf-8")
310
+ os.replace(tmp, mpath)
311
+ except (OSError, ValueError):
312
+ continue
313
+
314
+ # ---- ack(幂等留痕·双落点) ----
315
+ def _tomb_from(self, mid: str) -> str | None:
316
+ """从墓碑 envelope 读消息发送方名(ack 回执方向的依据)。"""
317
+ try:
318
+ rec = json.loads((self.mb.claimed / f"{mid}.msg")
319
+ .read_text("utf-8"))
320
+ f = rec.get("from")
321
+ return f if isinstance(f, str) else None
322
+ except (OSError, ValueError):
323
+ return None
324
+
325
+ def ack(self, mid: str, result=None):
326
+ guard_name(mid)
327
+ key = mid.casefold()
328
+ # 双落点(v1.3 §5):回执写发送方信箱(供其 wait)+ 本信箱(供幂等清理)。
329
+ mbs = [self.mb]
330
+ env_from = self._tomb_from(mid)
331
+ if env_from and env_from != self.mb.name:
332
+ mbs.append(Mailbox(self.root, env_from))
333
+ if any((mb.acks / f"{key}.ack").exists() for mb in mbs):
334
+ return False # 幂等:二次 ack 无副作用
335
+ rec = {"id": mid, "result": result, "ts": time.time(), "by": self.sender}
336
+ for mb in mbs:
337
+ apath = mb.acks / f"{key}.ack"
338
+ tmp = mb.acks / f"{key}.tmp"
339
+ with open(tmp, "w", encoding="utf-8") as f:
340
+ json.dump(rec, f)
341
+ f.flush()
342
+ os.fsync(f.fileno())
343
+ os.replace(tmp, apath)
344
+ # 清墓碑
345
+ self._silent_unlink(self.mb.claimed / f"{mid}.msg")
346
+ self._silent_unlink(self.mb.claimed / f"{mid}.meta")
347
+ _metrics(self.root, {"ts": time.time(), "op": "ack", "id": mid,
348
+ "by": self.sender})
349
+ return True
350
+
351
+ def _is_acked(self, mid: str) -> bool:
352
+ return (self.mb.acks / f"{mid.casefold()}.ack").exists()
353
+
354
+ # ---- 等待(r2-B8:deadline 语义) ----
355
+ def wait(self, corrs, deadline_s: float = 60.0):
356
+ """等待 corr 集对应 ack 到齐。超时返回未齐清单(None 值)。
357
+ ack 侧将 corr 写进 result 或以 corr 作 ack 键——约定:wait 按
358
+ acks 中 result.corr 或 corr 键匹配。"""
359
+ deadline = time.time() + deadline_s
360
+ want = list(corrs)
361
+ got: dict[str, object] = {}
362
+ while time.time() < deadline:
363
+ for fn in os.listdir(self.mb.acks):
364
+ if not fn.endswith(".ack"):
365
+ continue
366
+ try:
367
+ rec = json.loads((self.mb.acks / fn).read_text("utf-8"))
368
+ except (OSError, ValueError):
369
+ continue
370
+ r = rec.get("result")
371
+ c = None
372
+ if isinstance(r, dict):
373
+ c = r.get("corr")
374
+ got.setdefault(str(c) if c is not None else rec.get("id"), rec.get("result"))
375
+ if all(c in got for c in want):
376
+ return {c: got.get(c) for c in want}
377
+ time.sleep(POLL_S)
378
+ return {c: got.get(c) for c in want} # 未齐项值为 None
379
+
380
+ # ---- 恢复(租约过期 → 重投递 / DLQ) ----
381
+ def recover(self, ttl_s: float = LEASE_TTL_S):
382
+ """扫描本信箱租约过期墓碑:retries<MAX → 重投递(at-least-once);
383
+ retries>=MAX → dead/(DLQ,防跨窗口崩溃循环)。返回统计。"""
384
+ now = time.time()
385
+ redeliver = dead = 0
386
+ for fn in list(os.listdir(self.mb.claimed)):
387
+ if not fn.endswith(".meta"):
388
+ continue
389
+ mid = fn[:-5]
390
+ mpath = self.mb.claimed / fn
391
+ tomb = self.mb.claimed / f"{mid}.msg"
392
+ try:
393
+ meta = json.loads(mpath.read_text("utf-8"))
394
+ except (OSError, ValueError):
395
+ meta = {"hb_ts": 0, "retries": MAX_RETRIES}
396
+ if now - float(meta.get("hb_ts", 0)) < ttl_s:
397
+ continue # 慢而活,不动
398
+ retries = int(meta.get("retries", 0))
399
+ if retries + 1 >= MAX_RETRIES or not tomb.exists():
400
+ if tomb.exists():
401
+ os.replace(tomb, self.mb.dead / f"{mid}.msg")
402
+ dead += 1
403
+ self._silent_unlink(mpath)
404
+ else:
405
+ try: # 重投递同 id:接收方按 id 幂等
406
+ os.replace(tomb, self.mb.inbox / f"{mid}.msg")
407
+ redeliver += 1
408
+ # meta 保留并累加 retries,供下次认领继承(DLQ 计数跨重投递存续)
409
+ meta["retries"] = retries + 1
410
+ meta["hb_ts"] = 0.0
411
+ mpath.write_text(json.dumps(meta), "utf-8")
412
+ except OSError:
413
+ pass
414
+ _metrics(self.root, {"ts": now, "op": "recover", "by": self.sender,
415
+ "redeliver": redeliver, "dead": dead})
416
+ return {"redeliver": redeliver, "dead": dead}
417
+
418
+ # ---- GC(r2-B7) ----
419
+ def gc(self, root_all: bool = True):
420
+ """tmp 超时清理 + acked 过期清理 + blobs 引用计数清理。"""
421
+ now = time.time()
422
+ freed_tmp = freed_ack = freed_blob = 0
423
+ boxes = []
424
+ if root_all:
425
+ for name in os.listdir(self.root):
426
+ p = self.root / name
427
+ if (p / "inbox").is_dir():
428
+ boxes.append(Mailbox(self.root, name))
429
+ else:
430
+ boxes.append(self.mb)
431
+ for mb in boxes:
432
+ for d in (mb.inbox, mb.claimed, mb.blobs, mb.acks):
433
+ for fn in os.listdir(d):
434
+ if fn.endswith(".tmp") and now - _mtime(d / fn) > GC_TMP_S:
435
+ self._silent_unlink(d / fn)
436
+ freed_tmp += 1
437
+ for fn in os.listdir(mb.acks):
438
+ p = mb.acks / fn
439
+ if now - _mtime(p) > GC_ACK_S:
440
+ self._silent_unlink(p)
441
+ freed_ack += 1
442
+ # blobs 引用计数
443
+ refs = set()
444
+ for d in (mb.inbox, mb.claimed, mb.dead):
445
+ for fn in os.listdir(d):
446
+ if not fn.endswith(".msg"):
447
+ continue
448
+ try:
449
+ env = json.loads((d / fn).read_text("utf-8"))
450
+ if env.get("blob_ref"):
451
+ refs.add(env["blob_ref"])
452
+ except (OSError, ValueError):
453
+ continue
454
+ for fn in os.listdir(mb.blobs):
455
+ if fn.endswith(".blob") and fn[:-5] not in refs:
456
+ self._silent_unlink(mb.blobs / fn)
457
+ freed_blob += 1
458
+ return {"tmp": freed_tmp, "ack": freed_ack, "blob": freed_blob}
459
+
460
+ # ---- 状态(A3 最小观测面) ----
461
+ @staticmethod
462
+ def status(root: Path | str | None = None):
463
+ root = Path(root) if root else DEFAULT_ROOT
464
+ rows = {}
465
+ for name in sorted(os.listdir(root)):
466
+ p = root / name
467
+ if not (p / "inbox").is_dir():
468
+ continue
469
+ rows[name] = {
470
+ "inbox": len([f for f in os.listdir(p / "inbox") if f.endswith(".msg")]),
471
+ "claimed": len([f for f in os.listdir(p / "claimed") if f.endswith(".meta")]),
472
+ "acked": len([f for f in os.listdir(p / "acks") if f.endswith(".ack")]),
473
+ "dead": len([f for f in os.listdir(p / "dead") if f.endswith(".msg")]),
474
+ }
475
+ return rows
476
+
477
+ # ---- 内部 ----
478
+ def _to_dead(self, src: Path, mid: str, why: str):
479
+ try:
480
+ os.replace(src, self.mb.dead / f"{mid}.msg")
481
+ (self.mb.dead / f"{mid}.why").write_text(why, "utf-8")
482
+ except OSError:
483
+ pass
484
+ _metrics(self.root, {"ts": time.time(), "op": "dead", "id": mid, "why": why})
485
+
486
+ def _to_dead_tomb(self, tomb: Path, mid: str, why: str):
487
+ try:
488
+ os.replace(tomb, self.mb.dead / f"{mid}.msg")
489
+ (self.mb.dead / f"{mid}.why").write_text(why, "utf-8")
490
+ self._silent_unlink(self.mb.claimed / f"{mid}.meta")
491
+ except OSError:
492
+ pass
493
+ _metrics(self.root, {"ts": time.time(), "op": "dead", "id": mid, "why": why})
494
+
495
+ @staticmethod
496
+ def _silent_unlink(p: Path):
497
+ try:
498
+ os.remove(p)
499
+ except OSError:
500
+ pass
501
+
502
+
503
+ def _mtime(p: Path) -> float:
504
+ try:
505
+ return os.stat(p).st_mtime
506
+ except OSError:
507
+ return 0.0
508
+
509
+
510
+ # ---------------------------------------------------------------- CLI
511
+
512
+ def _cli():
513
+ ap = argparse.ArgumentParser(prog="dshbus", description="DSH 跨窗口文件信箱总线 v" + __version__)
514
+ ap.add_argument("--from", dest="me", default=None, help="本窗口名(默认环境 DSH_BUS_NAME 或 hostname-pid)")
515
+ ap.add_argument("--root", default=None, help="总线根目录(默认 ~/.dsh/windowbus)")
516
+ sub = ap.add_subparsers(dest="cmd", required=True)
517
+
518
+ p = sub.add_parser("send", help="发送消息")
519
+ p.add_argument("to"); p.add_argument("type"); p.add_argument("payload", help="JSON 字符串")
520
+ p.add_argument("--corr", default=None)
521
+ p.add_argument("--blob-file", default=None, help="大消息引用文件路径")
522
+
523
+ p = sub.add_parser("recv", help="认领消息(默认 claim;--peek 只读)")
524
+ p.add_argument("--limit", type=int, default=10)
525
+ p.add_argument("--peek", action="store_true")
526
+ p.add_argument("--block", action="store_true", help="阻塞直到有消息或超时")
527
+ p.add_argument("--timeout", type=float, default=0)
528
+ p.add_argument("--hb", action="store_true", help="长处理模式:认领后自动心跳(阻塞轮询内)")
529
+
530
+ p = sub.add_parser("ack", help="确认处理完成")
531
+ p.add_argument("id"); p.add_argument("--result", default=None)
532
+
533
+ p = sub.add_parser("wait", help="等待 corr 集 ack 到齐")
534
+ p.add_argument("corr", nargs="+")
535
+ p.add_argument("--deadline", type=float, default=60.0)
536
+
537
+ sub.add_parser("status", help="全部信箱状态")
538
+ p = sub.add_parser("recover", help="扫描租约过期墓碑(重投递/DLQ)")
539
+ p.add_argument("--ttl", type=float, default=LEASE_TTL_S)
540
+ p = sub.add_parser("gc", help="垃圾回收")
541
+
542
+ a = ap.parse_args()
543
+ me = a.me or os.environ.get("DSH_BUS_NAME") or f"win-{os.getpid()}"
544
+ bus = Bus(me, a.root)
545
+
546
+ if a.cmd == "send":
547
+ try:
548
+ payload = json.loads(a.payload)
549
+ except ValueError as e:
550
+ sys.exit(f"payload not JSON: {e}")
551
+ blob = None
552
+ if a.blob_file:
553
+ blob = Path(a.blob_file).read_bytes()
554
+ mid = bus.send(a.to, a.type, payload, corr=a.corr, blob=blob)
555
+ print(json.dumps({"ok": True, "id": mid}))
556
+
557
+ elif a.cmd == "recv":
558
+ import threading
559
+ deadline = time.time() + (a.timeout or (86400 * 365 if a.block else 0))
560
+ hb_stop = threading.Event()
561
+ if a.hb:
562
+ def _hb():
563
+ while not hb_stop.wait(HB_INTERVAL_S):
564
+ bus.heartbeat()
565
+ threading.Thread(target=_hb, daemon=True).start()
566
+ try:
567
+ while True:
568
+ msgs = bus.recv(limit=a.limit, peek=a.peek)
569
+ if msgs:
570
+ print(json.dumps(msgs, ensure_ascii=True))
571
+ return
572
+ if time.time() >= deadline:
573
+ print(json.dumps([]))
574
+ return
575
+ time.sleep(POLL_S)
576
+ finally:
577
+ hb_stop.set()
578
+
579
+ elif a.cmd == "ack":
580
+ ok = bus.ack(a.id, json.loads(a.result) if a.result else None)
581
+ print(json.dumps({"ok": bool(ok)}))
582
+
583
+ elif a.cmd == "wait":
584
+ print(json.dumps(bus.wait(a.corr, a.deadline), ensure_ascii=True))
585
+
586
+ elif a.cmd == "status":
587
+ print(json.dumps(bus.status(a.root), ensure_ascii=True, indent=2))
588
+
589
+ elif a.cmd == "recover":
590
+ print(json.dumps(bus.recover(a.ttl)))
591
+
592
+ elif a.cmd == "gc":
593
+ print(json.dumps(bus.gc()))
594
+
595
+
596
+ if __name__ == "__main__":
597
+ _cli()
package/dshbus_mcp.py ADDED
@@ -0,0 +1,151 @@
1
+ """dsh-bus MCP server — expose the file-mailbox bus to MCP-capable agents (DSH included).
2
+
3
+ Transport: stdio (default for local agents). Run: python dshbus_mcp.py
4
+ Identity: each caller passes ``me`` (its mailbox name); falls back to
5
+ env DSH_BUS_NAME, then "win-mcp". Bus root comes from env
6
+ DSH_BUS_ROOT (default ~/.dsh/windowbus) and is deliberately NOT a
7
+ tool parameter, to keep the filesystem surface fixed.
8
+
9
+ Requires the optional ``mcp`` extra: pip install dsh-bus[mcp]
10
+ """
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ import os
15
+ import time
16
+ from typing import Any
17
+
18
+ from mcp.server.fastmcp import FastMCP
19
+
20
+ import dshbus
21
+
22
+ mcp = FastMCP("dshbus")
23
+
24
+ _DEFAULT_ROOT = os.environ.get("DSH_BUS_ROOT") or os.path.join(
25
+ os.path.expanduser("~"), ".dsh", "windowbus"
26
+ )
27
+
28
+
29
+ def _me(me: str | None) -> str:
30
+ return me or os.environ.get("DSH_BUS_NAME") or "win-mcp"
31
+
32
+
33
+ @mcp.tool()
34
+ def bus_send(
35
+ to: str,
36
+ type: str,
37
+ payload: dict[str, Any],
38
+ corr: str = "",
39
+ me: str = "",
40
+ ) -> dict:
41
+ """Send a message to another window's mailbox.
42
+
43
+ Args:
44
+ to: Recipient mailbox name (e.g. "window-b").
45
+ type: Message type (e.g. "task", "notice", "result").
46
+ payload: JSON body of the message.
47
+ corr: Optional correlation id — the recipient should echo it in its
48
+ ack so the sender can ``bus_wait`` on it.
49
+ me: Sender mailbox name (defaults to DSH_BUS_NAME env, then "win-mcp").
50
+
51
+ Returns:
52
+ {"id": "<message id>"} — keep it for tracing; acks are keyed by corr.
53
+ """
54
+ bus = dshbus.Bus(_me(me), _DEFAULT_ROOT)
55
+ mid = bus.send(to, type, payload, corr=corr)
56
+ return {"id": mid}
57
+
58
+
59
+ @mcp.tool()
60
+ def bus_recv(
61
+ me: str = "",
62
+ limit: int = 10,
63
+ timeout_s: float = 0.0,
64
+ peek: bool = False,
65
+ ) -> dict:
66
+ """Receive (claim) messages from my mailbox.
67
+
68
+ Args:
69
+ me: My mailbox name (defaults to DSH_BUS_NAME env, then "win-mcp").
70
+ limit: Max messages to claim in this call.
71
+ timeout_s: If > 0, poll-block up to this many seconds waiting for
72
+ the first message (AI-window callers should allow minutes, not
73
+ seconds). 0 = non-blocking snapshot.
74
+ peek: If true, list messages without claiming (for inspection only).
75
+
76
+ Returns:
77
+ List of envelopes: id, corr, type, from, payload, ts. Claimed
78
+ messages must be finished with ``bus_ack`` or the lease expires and
79
+ they are redelivered (at-least-once).
80
+ """
81
+ bus = dshbus.Bus(_me(me), _DEFAULT_ROOT)
82
+ deadline = time.time() + timeout_s if timeout_s > 0 else 0.0
83
+ while True:
84
+ msgs = bus.recv(limit=limit, peek=peek)
85
+ if msgs or not deadline or time.time() >= deadline:
86
+ return {"count": len(msgs), "messages": msgs}
87
+ time.sleep(dshbus.POLL_S)
88
+
89
+
90
+ @mcp.tool()
91
+ def bus_ack(mid: str, result: dict[str, Any] | None = None, me: str = "") -> dict:
92
+ """Acknowledge a claimed message; the receipt lands in the sender's mailbox.
93
+
94
+ Args:
95
+ mid: Message id from ``bus_recv``.
96
+ result: Optional result body — include the sender's ``corr`` so
97
+ ``bus_wait`` can match it.
98
+ me: My mailbox name.
99
+
100
+ Returns:
101
+ {"ok": true} on first ack; {"ok": false} if already acked.
102
+ """
103
+ bus = dshbus.Bus(_me(me), _DEFAULT_ROOT)
104
+ ok = bus.ack(mid, result or {})
105
+ return {"ok": ok}
106
+
107
+
108
+ @mcp.tool()
109
+ def bus_wait(corrs: list[str], deadline_s: float = 300.0, me: str = "") -> dict:
110
+ """Wait for acks matching the given correlation ids.
111
+
112
+ Args:
113
+ corrs: Correlation ids to wait for (echoed by recipients in acks).
114
+ deadline_s: Total wait budget in seconds (AI windows: give minutes).
115
+ me: My (sender) mailbox name where receipts arrive.
116
+
117
+ Returns:
118
+ {corr: result-or-null}. Null = timed out; the receipt may still
119
+ arrive later — check again before declaring failure.
120
+ """
121
+ bus = dshbus.Bus(_me(me), _DEFAULT_ROOT)
122
+ return bus.wait(corrs, deadline_s=deadline_s)
123
+
124
+
125
+ @mcp.tool()
126
+ def bus_status() -> dict:
127
+ """Return per-mailbox counters (inbox / claimed / acked / dead) for the bus."""
128
+ return dshbus.Bus.status(_DEFAULT_ROOT)
129
+
130
+
131
+ @mcp.tool()
132
+ def bus_recover(ttl: float = dshbus.LEASE_TTL_S, me: str = "") -> dict:
133
+ """Recover expired leases: redeliver stale claimed messages or dead-letter them.
134
+
135
+ Args:
136
+ ttl: Lease age (seconds) after which a claim counts as expired.
137
+ me: Operator mailbox name (used for metrics only).
138
+
139
+ Returns:
140
+ {"redelivered": n, "dead": m}.
141
+ """
142
+ bus = dshbus.Bus(_me(me), _DEFAULT_ROOT)
143
+ return bus.recover(ttl) # {"redeliver": n, "dead": m}
144
+
145
+
146
+ def main() -> None:
147
+ mcp.run() # stdio
148
+
149
+
150
+ if __name__ == "__main__":
151
+ main()
package/package.json CHANGED
@@ -1,6 +1,49 @@
1
1
  {
2
2
  "name": "dsh-bus",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.3.1",
4
+ "description": "Cross-window file-mailbox bus for DSH (and any process): send tasks, wait for receipts, relay work between agent sessions. Zero-dependency core, exactly-once claims, at-least-once delivery.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/taojun566/dsh-bus.git"
9
+ },
10
+ "bin": {
11
+ "dsh-bus": "./dshbus-launcher.js"
12
+ },
13
+ "main": "./dshbus-launcher.js",
14
+ "exports": {
15
+ "./locale/*": "./dsh-bundle/locale/*",
16
+ "./icon.svg": "./dsh-bundle/icon.svg",
17
+ "./package.json": "./package.json"
18
+ },
19
+ "files": [
20
+ "dshbus.py",
21
+ "dshbus_mcp.py",
22
+ "dshbus-launcher.js",
23
+ "cordis.patch.yml",
24
+ "dsh-bundle/",
25
+ "README.md",
26
+ "LICENSE",
27
+ "CHANGELOG.md"
28
+ ],
29
+ "dsh": {
30
+ "bundle": {
31
+ "patch": "cordis.patch.yml"
32
+ }
33
+ },
34
+ "dsh.bundle.patch": "cordis.patch.yml",
35
+ "keywords": [
36
+ "dsh",
37
+ "dsh-plugin",
38
+ "mcp",
39
+ "message-bus",
40
+ "file-mailbox",
41
+ "cross-window",
42
+ "agent-ipc",
43
+ "window-relay"
44
+ ],
45
+ "engines": {
46
+ "node": ">=18",
47
+ "dsh": ">=0.2.0-alpha.0 <0.3.0"
48
+ }
49
+ }