@feng0531/dsh-execution-bus 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,42 @@
+Execution Bus 非商业源码公开许可证 1.0
+Execution Bus Non-Commercial Source Available License 1.0
+
+Copyright (c) 2026 f-e-n-g-0531 及各贡献者。
+项目：https://github.com/f-e-n-g-0531/dsh-execution-bus
+
+1. 适用范围
+本许可证适用于本项目中由上述权利人有权授权且未另行标明许可的代码、文档及其修改版本（“本软件”）。本许可证是自定义的源码公开许可证，不是 OSI 认可的开源许可证。中文正文为具有约束力的文本，英文名称仅供识别。
+
+2. 非商业授权
+在遵守全部条款的前提下，权利人授予您全球范围、非独占、免许可费的权利，仅为非商业目的使用、复制、研究、修改和分发本软件的源码及编译版本。非商业目的指不主要旨在或用于获取商业利益、营业收入或金钱报酬的活动；个人非商业学习、无商业目的的教学、研究及公益使用可以适用。组织的营利或非营利身份本身不决定用途是否符合本条。
+
+3. 商业用途限制
+未经有关权利人另行明确书面授权，不得将本软件或其修改版本用于商业用途，包括但不限于：
+(a) 销售、付费许可、出租本软件，或以其提供收费托管、SaaS、服务及付费产品；
+(b) 集成到商业产品、收费分发包或以广告、订阅等方式获利的服务中；
+(c) 在公司、组织或个人经营活动中，内部使用本软件开发、测试、维护或运营商业项目，即使本软件本身不对外分发或收费；
+(d) 为客户提供有偿开发、咨询或其他商业交付时使用本软件。
+免费提供、仅内部使用或修改名称，不构成商业用途豁免。用途不明确时，应先取得书面授权。
+
+4. 复制、修改与分发条件
+每份分发的源码或编译版本均须附带完整许可证及适用版权和第三方声明；不得删除或隐瞒这些声明。
+修改版须清楚注明已修改、修改者及主要修改内容，不得冒充官方版本或暗示权利人背书。
+您对本软件及基于本软件的修改部分的分发必须遵守本许可证，不得向接收者授予超出本许可证的商业使用权；接收者对原有部分的权利直接来自有关权利人。独立且非衍生的作品不因与本软件一同分发而自动适用本许可证。
+本许可证不强制公开未分发的修改，也不要求分发编译版本时同时提供源码。所有分发仍须满足非商业条件。
+
+5. 第三方材料与保留权利
+依赖项及其他明确标注第三方许可的材料，仍各自适用其原许可证。本许可证不收回或限制第三方许可证已经授予的权利；仅独立使用这些材料时无需取得本项目的商业授权。
+除明确授予的权利外，其余权利保留。本许可证不授予商标使用权，也不授予明示专利许可；不限制适用法律规定的不可排除权利。
+
+6. 贡献与另行授权
+贡献者保留其贡献的版权。主动向本项目提交并明确接受本许可证的贡献，按本许可证授权，不构成版权转让或额外商业再许可授权。维护者如为包含他人贡献的版本提供商业许可，须确保已取得所有必要权利；不得仅凭维护者身份授权不属于自己的权利。
+商业授权请求可通过项目仓库联系维护者协商；沉默、公开源码或接受问题反馈不等于授权。
+
+7. 终止
+违反本许可证时，违约者依据本许可证取得的权利自动终止，应停止相关使用与分发。恢复授权须取得相关权利人的书面同意。终止不影响此前已合法取得副本并持续遵守本许可证的其他接收者，也不影响已经产生的责任。
+
+8. 无担保与责任限制
+在适用法律允许的最大范围内，本软件按“现状”提供，不提供任何明示或默示担保，包括适销性、特定用途适用性及不侵权担保。权利人和贡献者不对使用或无法使用本软件所致的损失、索赔或其他责任承担责任，无论基于合同、侵权或其他事由。法律不允许排除的担保或责任不受本条排除。
+
+9. 其他
+本许可证的任何条款不可执行时，其余条款在法律允许的范围内继续有效。后续发布的新许可版本不自动替换您依据本版本已合法取得副本所适用的条款。另行书面协议可对特定权利另作约定。

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# 执行总线 / Execution Bus
 
-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.
+DSH 独立插件 **@feng0531/dsh-execution-bus 0.1.1**，用于让模型提出一次执行请求后，由程序排队、等待和收集结果，而不是反复询问是否完成。
+
+**当前是第一阶段可运行原型、部分完成，不是完整生产验收。只做插件，不修改 DSH。** 不增加模型或 Agent，不是工作流引擎、PTC 包装或任意命令执行服务，也不会改动其他插件。它不能解决模型理解错误、不断改变方案等所有推理问题。
+
+## 已实现
+
+- 版本化协议和运行时校验；有界 FIFO、并发限制、请求冲突检测、同请求执行复用。
+- 原工具调用异步等待终态；复用宿主 Job 进度、取消和等待，无模型轮询。
+- test：延迟、百分比、成功、失败、合作取消。
+- host.read：出队时通过宿主工具注册表调用现有 read，保留当前身份、工作目录、权限及输出限制，不自行读文件或启动进程。
+- 内存结果保存、大小限制、清理和关闭；失败日志不包含异常原文。
+
+## 明确不支持 / 未验证
+
+- 不持久化，不支持重启保留队列或恢复原工具调用，不自动重跑。
+- 真实 AgentLoop 内存会话提交/继续已通过脚本适配器验证；GUI 实际展示、真实模型继续推理、磁盘会话提交与 PTC 完整链路未验证。
+- 没有外部 Handler 传输、跨插件 Handler 服务、非幂等执行对账；不是全要求验收完成版。
+
+详见 [宿主调用链与兼容性](docs/host-compatibility.md)、[协议和状态](docs/protocol.md)、[验证记录](docs/validation.md)。
+
+## 构建与测试
+
+需要 Node.js >=22（本次使用 24.21.0）和 npm。开发环境依赖安装限定本仓库，不触及日常 DSH。
+
+```powershell
+npm ci --ignore-scripts
+npm test
+npm run build
+npm pack --ignore-scripts
+npm run verify:package
+npm run test:install
+```
+
+标签 CI、四矩阵测试与受控发布见 [发布流程](docs/RELEASING.md)。采用[非商业源码公开许可证](LICENSE)，非 OSI 开源许可证；正式发布必须通过同标签 CI 和工作流门禁。发布不安装或重启 DSH。
+
+测试会在隔离 Cordis 上下文运行真实宿主组件；Agent 身份为夹具，不调用真实模型。安装包只含编译入口、类型与文档，不包含宿主源码快照、测试环境或 node_modules。源码构建需要整个仓库。
+
+## 安装：仅在你明确决定的隔离 DSH 配置中
+
+本次**未安装到你的 DSH**。兼容目标精确为 DSH 0.2.0-rc.2 / Cordis 4.0.4；先确认你要操作的配置目录和宿主实际版本。不要向运行时安装目录复制文件或修改 ASAR。
+
+1. 备份目标配置文件、依赖声明和 lockfile，记录当前插件清单。先停止目标隔离实例的工作，不动日常会话。
+2. 在隔离配置的依赖目录安装本地 tgz，禁用生命周期脚本；避免升级宿主依赖。若 peer 不匹配，停止安装，不用 force/legacy-peer-deps 绕过。
+3. 在目标实例已有的插件加载配置中加入包名。必须位于可见 tools、jobs、现有 tool-jobs controller 和 read 的组合内。包导出标准 Cordis name / inject / apply；不提供未验证的全局配置键。
+4. 由使用者自行启动/重载隔离实例，确认 execution_bus 工具可见。配置结构随宿主组合而异，不承诺“一条配置适用于所有版本”。
+
+## 使用
+
+直接工具入口 execution_bus 的请求参数：
+
+```json
+{
+  "protocolVersion": 1,
+  "messageId": "message-001",
+  "requestId": "operation-001",
+  "type": "request",
+  "payload": {"handler": "test", "input": {"delayMs": 1000, "fail": false}}
+}
+```
+
+调用会等待约一秒，再返回 succeeded 等终态，不需要 status 循环。真实只读任务把 payload 改为 {"handler":"host.read","input":{"file_path":"README.md","limit":20}}，路径相对于可信宿主会话工作目录。
+
+若当前 DSH 是 PTC 模式，在 run_code 内 await tools.execution_bus(同上对象)，而非直接工具调用；这不会解除 run_code 的时间预算。PTC 端到端尚未验收。
+
+手工查询/重取/取消：保留 requestId，换新 messageId，type 改为 status / result / cancel，payload 为 {}。不同会话无法读取或取消其他会话请求。cancelRequested 不等于已取消；读取执行状态字段判断。不要因为等待或通信超时就换 requestId 重新执行。
+
+## 卸载与回滚
+
+先停止新请求并等待已有操作终态，或请求合作取消。然后从目标隔离实例插件加载配置移除包名，按宿主正常生命周期卸载；卸载会取消并等待本插件受理的任务。不要强杀并假定外部操作已回滚。
+
+若首次试用失败，恢复前述配置/依赖/锁文件备份，再由使用者自行启动目标实例。tgz 不写宿主文件、系统服务、全局命令或磁盘任务库，无专属磁盘数据迁移。进程关闭会丢失内存结果；宿主已有会话日志不在插件卸载范围内，不删除它们。
+
+## 减少反复的验证
+
+真实模型参与轮次、主动状态查询次数、重复执行次数和总耗时对照：**未验证**，不提供提升比例。自动化测试只证明等待和状态机制，不替代同条件真实模型对比。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,5 @@
+# 第三方说明
+
+本包没有捆绑 DSH、Cordis、TypeScript、测试依赖或宿主源码快照。DSH 与 Cordis 作为宿主 peer 使用，其独立包分别受原许可证约束，本项目非商业许可证不限制第三方已授予的权利。开发依赖不进入本项目 tgz。
+
+CI 与发布组织方式参考 dsh-vcs，并按本项目执行能力重新实现；本包不含 Monaco、React 或 SVN 实现。

package/dist/bus.d.ts

@@ -0,0 +1,85 @@
+export type State = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "unknown";
+export type Owner = {
+    sessionId: string;
+    callId: string;
+};
+export type Message = {
+    protocolVersion: 1;
+    messageId: string;
+    requestId: string;
+    type: "request" | "status" | "result" | "cancel";
+    payload: Record<string, unknown>;
+};
+export type Event = {
+    protocolVersion: 1;
+    messageId: string;
+    requestId: string;
+    correlationId: string;
+    sequence: number;
+    type: string;
+    payload: Record<string, unknown>;
+};
+export type Capability = (input: Record<string, unknown>, signal: AbortSignal) => Promise<unknown>;
+export interface Handler {
+    validate(input: Record<string, unknown>): void;
+    run(input: Record<string, unknown>, ctx: {
+        signal: AbortSignal;
+        progress: (sequence: number, percent: number) => void;
+        requestId: string;
+        invoke?: Capability;
+    }): Promise<unknown>;
+}
+export interface RecordView {
+    requestId: string;
+    state: State;
+    sequence: number;
+    cancelRequested: boolean;
+    delivery: "pending" | "returned";
+    result?: unknown;
+    error?: string;
+    progress?: number;
+}
+export declare function object(v: unknown): Record<string, unknown>;
+export declare function parse(raw: unknown): Message;
+/** Volatile single-process bus; no acceptance durability or automatic execution retry. */
+export declare class ExecutionBus {
+    readonly options: {
+        concurrency: number;
+        queueLimit: number;
+        recordLimit: number;
+        resultBytes: number;
+        retentionMs: number;
+    };
+    private entries;
+    private handlers;
+    private queue;
+    private running;
+    private closed;
+    constructor(options?: {
+        concurrency: number;
+        queueLimit: number;
+        recordLimit: number;
+        resultBytes: number;
+        retentionMs: number;
+    });
+    register(name: string, handler: Handler): () => void;
+    private key;
+    private emit;
+    private view;
+    private get;
+    sweep(now?: number): void;
+    submit(owner: Owner, raw: unknown, onEvent?: (e: Event) => void, invoke?: Capability): {
+        accepted: Event;
+        done: Promise<RecordView>;
+        cancel: () => void;
+        detach: () => void;
+        returned: () => void;
+    };
+    private attachment;
+    command(owner: Owner, raw: unknown): RecordView;
+    private cancel;
+    private finish;
+    private pump;
+    private run;
+    close(): Promise<void>;
+}

package/dist/bus.js

@@ -0,0 +1,328 @@
+import { randomUUID, createHash } from "node:crypto";
+export function object(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw Error("INVALID_OBJECT");
+    return v;
+}
+function canonical(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return "[" + v.map(canonical).join(",") + "]";
+    return ("{" +
+        Object.keys(v)
+            .sort()
+            .map((k) => JSON.stringify(k) +
+            ":" +
+            canonical(v[k]))
+            .join(",") +
+        "}");
+}
+export function parse(raw) {
+    const m = object(raw);
+    if (Object.keys(m).some((k) => ![
+        "protocolVersion",
+        "messageId",
+        "requestId",
+        "type",
+        "payload",
+    ].includes(k)))
+        throw Error("UNKNOWN_FIELD");
+    if (m.protocolVersion !== 1)
+        throw Error("UNSUPPORTED_VERSION");
+    for (const k of ["messageId", "requestId"])
+        if (typeof m[k] !== "string" ||
+            !/^[a-zA-Z0-9_.:-]{1,128}$/.test(m[k]))
+            throw Error("INVALID_ID");
+    if (!["request", "status", "result", "cancel"].includes(m.type))
+        throw Error("UNSUPPORTED_TYPE");
+    object(m.payload);
+    if (Buffer.byteLength(JSON.stringify(m)) > 16384)
+        throw Error("MESSAGE_TOO_LARGE");
+    return structuredClone(m);
+}
+function freezeJson(value) {
+    if (value && typeof value === "object") {
+        for (const child of Object.values(value))
+            freezeJson(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+const terminal = (s) => !["queued", "running"].includes(s);
+/** Volatile single-process bus; no acceptance durability or automatic execution retry. */
+export class ExecutionBus {
+    options;
+    entries = new Map();
+    handlers = new Map();
+    queue = [];
+    running = 0;
+    closed = false;
+    constructor(options = {
+        concurrency: 2,
+        queueLimit: 32,
+        recordLimit: 256,
+        resultBytes: 65536,
+        retentionMs: 3600000,
+    }) {
+        this.options = options;
+        for (const v of Object.values(options))
+            if (!Number.isSafeInteger(v) || v < 1)
+                throw Error("INVALID_OPTIONS");
+    }
+    register(name, handler) {
+        if (this.handlers.has(name))
+            throw Error("DUPLICATE_HANDLER");
+        this.handlers.set(name, handler);
+        return () => {
+            this.handlers.delete(name);
+        };
+    }
+    key(o, id) {
+        if (!o.sessionId || !o.callId)
+            throw Error("UNTRUSTED_CONTEXT");
+        return JSON.stringify([o.sessionId, id]);
+    }
+    emit(e, type, payload, correlationId = "") {
+        e.view.sequence++;
+        const event = {
+            protocolVersion: 1,
+            messageId: randomUUID(),
+            requestId: e.view.requestId,
+            correlationId: correlationId || e.correlationId,
+            sequence: e.view.sequence,
+            type,
+            payload,
+        };
+        for (const f of e.listeners)
+            try {
+                f(event);
+            }
+            catch {
+                /* Observers cannot alter execution. */
+            }
+    }
+    view(e) {
+        return structuredClone(e.view);
+    }
+    get(o, id) {
+        const e = this.entries.get(this.key(o, id));
+        if (!e)
+            throw Error("NOT_FOUND");
+        return e;
+    }
+    sweep(now = Date.now()) {
+        for (const [k, e] of this.entries)
+            if (terminal(e.view.state) && now - e.created > this.options.retentionMs)
+                this.entries.delete(k);
+    }
+    submit(owner, raw, onEvent, invoke) {
+        if (this.closed)
+            throw Error("CLOSED");
+        const m = parse(raw);
+        if (m.type !== "request")
+            throw Error("EXPECTED_REQUEST");
+        const p = m.payload;
+        if (Object.keys(p).some((k) => !["handler", "input"].includes(k)) ||
+            typeof p.handler !== "string")
+            throw Error("INVALID_REQUEST");
+        const input = object(p.input);
+        const key = this.key(owner, m.requestId), fp = createHash("sha256").update(canonical(p)).digest("hex");
+        this.sweep();
+        let e = this.entries.get(key);
+        if (e) {
+            if (e.fingerprint !== fp)
+                throw Error("REQUEST_CONFLICT");
+            const previous = e.messages.get(m.messageId);
+            if (previous && previous !== canonical(m))
+                throw Error("MESSAGE_CONFLICT");
+            if (!previous) {
+                if (e.messages.size >= 128)
+                    throw Error("MESSAGE_LIMIT");
+                e.messages.set(m.messageId, canonical(m));
+            }
+            return this.attachment(e, onEvent, m.messageId);
+        }
+        const handler = this.handlers.get(p.handler);
+        if (!handler)
+            throw Error("UNKNOWN_HANDLER");
+        handler.validate(input);
+        if (this.entries.size >= this.options.recordLimit ||
+            this.queue.length >= this.options.queueLimit)
+            throw Error("BACKPRESSURE");
+        let resolve;
+        const done = new Promise((r) => (resolve = r));
+        e = {
+            invoke,
+            correlationId: m.messageId,
+            owner: owner.sessionId,
+            fingerprint: fp,
+            handler,
+            input: structuredClone(input),
+            view: {
+                requestId: m.requestId,
+                state: "queued",
+                sequence: 0,
+                cancelRequested: false,
+                delivery: "pending",
+            },
+            controller: new AbortController(),
+            done,
+            resolve,
+            listeners: new Set(),
+            sourceSequence: 0,
+            created: Date.now(),
+            messages: new Map([[m.messageId, canonical(m)]]),
+        };
+        this.entries.set(key, e);
+        const attached = this.attachment(e, onEvent, m.messageId);
+        this.queue.push(e);
+        queueMicrotask(() => this.pump());
+        return attached;
+    }
+    attachment(e, onEvent, id) {
+        if (onEvent && !terminal(e.view.state)) {
+            if (e.listeners.size >= 32)
+                throw Error("WAITER_LIMIT");
+            e.listeners.add(onEvent);
+        }
+        const accepted = {
+            protocolVersion: 1,
+            messageId: randomUUID(),
+            requestId: e.view.requestId,
+            correlationId: id,
+            sequence: e.view.sequence,
+            type: "accepted",
+            payload: { state: e.view.state, durable: false },
+        };
+        return {
+            accepted,
+            done: e.done,
+            cancel: () => this.cancel(e),
+            detach: () => {
+                if (onEvent)
+                    e.listeners.delete(onEvent);
+            },
+            returned: () => {
+                e.view.delivery = "returned";
+            },
+        };
+    }
+    command(owner, raw) {
+        const m = parse(raw);
+        if (m.type === "request")
+            throw Error("EXPECTED_CONTROL");
+        if (Object.keys(m.payload).length)
+            throw Error("INVALID_CONTROL");
+        this.sweep();
+        const e = this.get(owner, m.requestId);
+        const previous = e.messages.get(m.messageId), fingerprint = canonical(m);
+        if (previous && previous !== fingerprint)
+            throw Error("MESSAGE_CONFLICT");
+        if (!previous) {
+            if (e.messages.size >= 128)
+                throw Error("MESSAGE_LIMIT");
+            e.messages.set(m.messageId, fingerprint);
+            if (m.type === "cancel")
+                this.cancel(e);
+        }
+        return this.view(e);
+    }
+    cancel(e) {
+        if (terminal(e.view.state) || e.view.cancelRequested)
+            return;
+        e.view.cancelRequested = true;
+        e.controller.abort();
+        this.emit(e, "cancel_requested", {});
+        if (e.view.state === "queued") {
+            this.queue = this.queue.filter((x) => x !== e);
+            this.finish(e, "cancelled");
+        }
+    }
+    finish(e, state, result, error) {
+        if (terminal(e.view.state))
+            return;
+        e.created = Date.now();
+        e.view.state = state;
+        if (result !== undefined)
+            e.view.result = result;
+        if (error)
+            e.view.error = error;
+        this.emit(e, state, { state });
+        e.resolve(freezeJson(this.view(e)));
+        e.listeners.clear();
+    }
+    pump() {
+        while (!this.closed &&
+            this.running < this.options.concurrency &&
+            this.queue.length) {
+            const e = this.queue.shift();
+            if (e.view.state !== "queued")
+                continue;
+            this.running++;
+            e.view.state = "running";
+            this.emit(e, "started", {});
+            void this.run(e).finally(() => {
+                this.running--;
+                this.pump();
+            });
+        }
+    }
+    async run(e) {
+        try {
+            const result = await e.handler.run(e.input, {
+                invoke: e.invoke,
+                signal: e.controller.signal,
+                requestId: e.view.requestId,
+                progress: (seq, pct) => {
+                    if (e.view.state !== "running" ||
+                        !Number.isSafeInteger(seq) ||
+                        seq <= e.sourceSequence ||
+                        !Number.isFinite(pct) ||
+                        pct < 0 ||
+                        pct > 100)
+                        return;
+                    e.sourceSequence = seq;
+                    e.view.progress = pct;
+                    this.emit(e, "progress", { percent: pct });
+                },
+            });
+            let json;
+            try {
+                json = JSON.stringify(result);
+            }
+            catch {
+                this.finish(e, "unknown", undefined, "RESULT_NOT_RETAINED");
+                return;
+            }
+            if (json === undefined ||
+                Buffer.byteLength(json) > this.options.resultBytes) {
+                this.finish(e, "unknown", undefined, "RESULT_NOT_RETAINED");
+                return;
+            }
+            this.finish(e, "succeeded", JSON.parse(json));
+        }
+        catch (err) {
+            const cancelled = e.controller.signal.aborted &&
+                err instanceof Error &&
+                err.name === "AbortError";
+            this.finish(e, cancelled
+                ? "cancelled"
+                : e.controller.signal.aborted
+                    ? "unknown"
+                    : "failed", undefined, cancelled
+                ? "CANCELLED"
+                : e.controller.signal.aborted
+                    ? "CANCELLATION_UNCONFIRMED"
+                    : "HANDLER_FAILED");
+        }
+    }
+    async close() {
+        this.closed = true;
+        for (const e of this.entries.values())
+            this.cancel(e);
+        await Promise.all([...this.entries.values()].map((e) => e.done));
+        this.handlers.clear();
+        this.entries.clear();
+    }
+}

package/dist/handlers.d.ts

@@ -0,0 +1,3 @@
+import type { Handler } from "./bus.js";
+export declare const testHandler: Handler;
+export declare const readHandler: Handler;

package/dist/handlers.js

@@ -0,0 +1,42 @@
+import { setTimeout } from "node:timers/promises";
+export const testHandler = {
+    validate(input) {
+        if (Object.keys(input).some((k) => !["delayMs", "fail"].includes(k)) ||
+            !Number.isSafeInteger(input.delayMs) ||
+            Number(input.delayMs) < 0 ||
+            Number(input.delayMs) > 30000 ||
+            typeof input.fail !== "boolean")
+            throw Error("INVALID_TEST_INPUT");
+    },
+    async run(input, ctx) {
+        for (let i = 1; i <= 5; i++) {
+            await setTimeout(Number(input.delayMs) / 5, undefined, {
+                signal: ctx.signal,
+            });
+            ctx.progress(i, i * 20);
+        }
+        if (input.fail)
+            throw Error("CONTROLLED_FAILURE");
+        return { ok: true };
+    },
+};
+export const readHandler = {
+    validate(input) {
+        if (Object.keys(input).some((k) => !["file_path", "offset", "limit"].includes(k)) ||
+            typeof input.file_path !== "string" ||
+            !input.file_path ||
+            input.file_path.length > 2048)
+            throw Error("INVALID_READ_INPUT");
+        for (const k of ["offset", "limit"])
+            if (input[k] !== undefined &&
+                (!Number.isSafeInteger(input[k]) || Number(input[k]) < 1))
+                throw Error("INVALID_READ_INPUT");
+        if (Number(input.limit ?? 100) > 100)
+            throw Error("READ_LIMIT");
+    },
+    async run(input, ctx) {
+        if (!ctx.invoke)
+            throw Error("HOST_CAPABILITY_REQUIRED");
+        return ctx.invoke({ ...input, limit: input.limit ?? 100 }, ctx.signal);
+    },
+};

package/dist/plugin.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from "@deepseek-ai/cordis";
+declare module "@deepseek-ai/dsh-jobs" {
+    interface JobKindMap {
+        executionBus: "execution-bus";
+    }
+}
+export declare const name = "execution-bus";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/dist/plugin.js

@@ -0,0 +1,131 @@
+import { randomUUID } from "node:crypto";
+import { ExecutionBus, parse } from "./bus.js";
+import { testHandler, readHandler } from "./handlers.js";
+export const name = "execution-bus";
+export const inject = ["tools", "jobs"];
+export function apply(ctx) {
+    const bus = new ExecutionBus();
+    bus.register("test", testHandler);
+    bus.register("host.read", readHandler);
+    const sharedJobs = new Map();
+    ctx.effect(() => async () => {
+        await bus.close();
+        await Promise.allSettled(sharedJobs.values());
+        sharedJobs.clear();
+    });
+    ctx.tools.register({
+        name: "execution_bus",
+        description: "执行总线 / Execution Bus. Submit a version 1 request and WAIT for its terminal result in this tool call. Reuse requestId only for the same logical operation. Handlers: test {delayMs:0..30000,fail:boolean}, host.read {file_path,offset?,limit?<=100}. Control types status/result/cancel use empty payload. Acceptance is volatile, not execution success. No polling needed; no restart resume.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+                "protocolVersion",
+                "messageId",
+                "requestId",
+                "type",
+                "payload",
+            ],
+            properties: {
+                protocolVersion: { type: "integer", const: 1 },
+                messageId: { type: "string" },
+                requestId: { type: "string" },
+                type: {
+                    type: "string",
+                    enum: ["request", "status", "result", "cancel"],
+                },
+                payload: { type: "object" },
+            },
+        },
+        output: {
+            schema: {},
+            render: (_a, v) => [{ type: "text", text: JSON.stringify(v) }],
+        },
+        async execute(raw, exec) {
+            if (!exec.agent)
+                throw Error("OWNING_SESSION_REQUIRED");
+            const owner = {
+                sessionId: String(exec.agent.id),
+                callId: String(exec.callId),
+            }, m = parse(raw);
+            if (m.type !== "request")
+                return bus.command(owner, m);
+            let handle;
+            const attached = bus.submit(owner, m, (event) => handle?.updateProgress(event.type === "progress"
+                ? String(event.payload.percent) + "%"
+                : event.type), async (input, signal) => {
+                const result = await ctx.tools.execute({
+                    name: "read",
+                    callId: (String(exec.callId) +
+                        ":bus:" +
+                        randomUUID()),
+                    rootCallId: exec.rootCallId,
+                    parent: exec.token,
+                    agent: exec.agent,
+                    arguments: input,
+                    signal,
+                });
+                if (result.isError)
+                    throw Error("HOST_READ_FAILED");
+                return result.value;
+            });
+            const abort = () => attached.cancel();
+            const jobKey = JSON.stringify([owner.sessionId, m.requestId]);
+            let settled = sharedJobs.get(jobKey);
+            if (!settled) {
+                try {
+                    const job = ctx.jobs.start({
+                        kind: "execution-bus",
+                        label: "执行总线 / Execution Bus",
+                        owner: exec.agent.id,
+                        run(h) {
+                            handle = h;
+                            return {
+                                done: attached.done.then((v) => ({
+                                    status: v.state === "succeeded"
+                                        ? "completed"
+                                        : v.state === "cancelled"
+                                            ? "killed"
+                                            : "failed",
+                                    detail: v.state,
+                                })),
+                                cancel: abort,
+                            };
+                        },
+                    });
+                    const ownerId = exec.agent.id;
+                    // One registered host waiter suppresses extra completion messages for every attachment.
+                    settled = (async () => {
+                        for (;;) {
+                            const view = await ctx.jobs.wait(job, 60000, ownerId);
+                            if (view.status !== "running" && view.status !== "stopping")
+                                break;
+                        }
+                        ctx.jobs.remove(job, ownerId);
+                    })();
+                    sharedJobs.set(jobKey, settled);
+                    void settled.then(() => sharedJobs.delete(jobKey), () => sharedJobs.delete(jobKey));
+                }
+                catch {
+                    abort();
+                    await attached.done;
+                    attached.detach();
+                    throw Error("HOST_JOB_UNAVAILABLE");
+                }
+            }
+            exec.signal.addEventListener("abort", abort, { once: true });
+            if (exec.signal.aborted)
+                abort();
+            try {
+                await settled;
+                const value = await attached.done;
+                attached.returned();
+                return value;
+            }
+            finally {
+                exec.signal.removeEventListener("abort", abort);
+                attached.detach();
+            }
+        },
+    });
+}

package/docs/FLOW-TEST.md

@@ -0,0 +1,38 @@
+# 不安装插件的流程测试
+
+## 本次执行方式与边界
+
+当前会话没有 execution_bus 工具，桌面配置未安装本插件。本次由当前会话运行测试命令，在独立进程中加载本仓库编译产物及真实 DSH npm 组件；不修改日常配置、不热注入运行宿主、不重启 DSH。
+
+这能验证真实 AgentLoop、SessionStore、ToolRuntime、Job 与 read 组件路径；不等于本会话实际调用 execution_bus，不验证真实桌面 UI、PTC 进程或真实模型。真实 AgentLoop 测试使用脚本模型适配器，read 组件测试使用测试 Agent 身份。两条测试不能合称当前会话端到端通过。
+
+## 重复运行
+
+1. npm ci --include=dev --ignore-scripts
+2. npm run test:flow：流程回归、真实宿主执行组件、真实 AgentLoop 原调用结果关联。
+3. npm run check：包含核心队列、安全和发布门禁的全部测试。
+4. npm run verify:package：包白名单。
+
+流程包括：正常成功/失败、读文件、权限拒绝、匿名请求拒绝、重复请求只新增一个 Job、工具取消、插件关闭、进度不作为聊天消息、原调用只提交一次后才继续下一模型适配器请求。
+
+## 本次可复现问题
+
+| 问题 | 修复前证据 | 本地修复 | 影响范围 |
+|---|---|---|---|
+| core 返回的 done 结果对象共享且可修改 | 第一个消费者将 state/result 改写后，第二次同请求取得被修改值 | 深度冻结终态快照 | core 扩展接入；不能据此声称模型能修改宿主冻结结果 |
+| Handler 完成但结果 JSON.stringify 抛错被记为 failed | 返回 BigInt 的一次执行被误记 failed | 保存异常为 unknown / RESULT_NOT_RETAINED，不重跑 | 当前内置只读/测试返回值正常；扩展 Handler 有风险 |
+| 结果超期查询未检查 TTL | 无新 request 时，过期 result 仍可读 | command 查询前 sweep | 查询/重取/取消均遵守结果保存期 |
+
+三个测试在修复前均失败；修复后全量 24/24 通过。这些修复归入 0.1.1 补丁发布；不改变已有 0.1.0 标签或公开包。发布状态以 GitHub Release 和 npm 公开结果为准。
+
+## 优化建议
+
+1. 已优化：终态结果不可变；保存失败明确区分执行失败；查询触发 TTL 回收，无常驻清理定时器。
+2. 后续可优化：完成请求重取无需新建短暂 Job；现在不会重复执行，但会产生不必要的 UI 生命周期事件。
+3. 后续可优化：每个重复附着仍注册一个空进度监听器；可将进度观察者绑定到共享逻辑请求，避免消耗 32 个监听者限额。
+4. 后续可优化：宿主 read 取消错误仍统一映射 HOST_READ_FAILED，保守归为 unknown。应保留经过白名单验证的取消类型，而不泄露原始异常文本。
+5. 不建议盲目改动：取消一个附着工具会请求取消整个逻辑执行，是当前明确语义；改成仅取消等待者需要单独设计宿主 drain、Job 通知和结果留存，不能只 Promise.race 后抛弃原执行。
+
+## 真实当前会话测试前提
+
+只有宿主通过正常插件加载向当前 Agent 注册工具后，才可能真正执行 await tools.execution_bus。当前没有暴露可用的临时插件注册工具，不能用额外 Node 进程、伪造 sessionId 或追加聊天结果来替代。若后续要测试真实当前会话，需要另行授权安装/加载并确认工具可见；本次未执行安装。

package/docs/RELEASING.md

@@ -0,0 +1,29 @@
+# 测试与发布流程
+
+参考 dsh-vcs 的标签 CI 与联合发布流程，针对纯后端执行总线适配。没有复制 SVN、Monaco 或浏览器 layout 检查，因为本项目没有这些依赖和前端。
+
+## 触发策略
+
+普通分支 push 和 pull_request 不触发 CI。仅 vX.Y.Z 标签 push 和手动 workflow_dispatch 触发 CI；Windows/Ubuntu × Node 22/24 四项矩阵运行相同的构建、测试、包白名单、候选打包和生产依赖隔离安装。手动分支 CI 不能替代正式发布所需的同标签 push CI。
+
+## 本地验证
+
+依次运行 npm ci --include=dev --ignore-scripts、npm run check、npm run verify:package、npm run pack:candidate、npm run test:install。test:install 默认新打包，也允许传入一个本地 tgz。安装目录在系统临时目录中，结束后清理，不操作用户 DSH 配置。
+
+每个版本必须有独立中文发布说明 docs/releases/X.Y.Z.md，注明实际模型/桌面/跨重启等未验证项。package.json、package-lock.json 根版本及标签必须一致。不移动已有标签。
+
+## 发布门禁
+
+用户已授权 0.1.0 正式发布，并确认沿用 dsh-vcs 的非商业源码公开许可证。该许可不是 OSI 开源许可证，限制商业项目内部使用与有偿交付，具体以 LICENSE 为准。用户已持续授权本项目每轮改动完成并验证通过后主动正式发布，无需逐次提醒；仍必须通过工作流确认与完整门禁，不表示实际模型验收通过。版本采用 vX.Y.Z：X 大版本、Y 小版本/新增功能、Z BUG 修复；发布不自动安装或重启 DSH。
+
+准备正式发布前：由用户明确授权；确定 LICENSE 与包 license 字段；检查公开材料、第三方许可和敏感信息；更新版本、锁文件与发布说明；提交并推送已批准的版本标签；等待四矩阵通过。
+
+从 main 手动运行 Publish GitHub and npm，输入已存在标签及确认词 publish-execution-bus。推荐为 npm-release environment 配置必须审批的维护者及适当分支限制，并配置 NPM_AUTOMATION_TOKEN。仓库环境审批和 token 均需要维护者配置，本次没有配置远端。
+
+工作流重新检查标签版本与许可证，运行本地检查，生成候选，查询该精确标签/提交的最新 push CI 为 success，下载四个矩阵候选并逐字节核对。然后隔离安装同一候选、保留制品，仅 npm 上传步骤取得凭据。npm 公开元数据 integrity 与实际下载字节必须一致，才创建 GitHub Release；附件是同一个 tgz 与 SHA256SUMS.txt。不自动覆盖已有 Release。
+
+npm 与 GitHub 不是原子发布。如果上传后公开包 404，不盲目重传；先只读对账，再重跑原工作流。已有 npm 同版本必须 integrity 相同才跳过上传；不匹配立即停止。发布过程没有自动重试上传，公开可见性最多查询十次。
+
+## 验证边界
+
+本地 Windows/Node 24 的脚本验证不等于 GitHub 四平台已成功。远端工作流、token、environment 审批、上传和两端公开包核验在执行前都属于未验证。CI 中的脚本模型适配器不是实际模型评测，包入口夹具不是桌面安装验收。发布不自动安装或重启 DSH。

package/docs/host-compatibility.md

@@ -0,0 +1,44 @@
+# 宿主调查与兼容性
+
+## 结论：只做插件
+
+调查日期：2026-10-15。当前桌面安装的 runtime 和各 DSH 组件均为 **0.2.0-rc.2**，Cordis 4.0.4。源码来自安装 ASAR，只读提取到项目开发证据目录；未改安装文件。插件针对这个精确版本编译。不能据此推断旧版、新版均兼容。
+
+**A. 纯插件可实现**：注册工具、同进程异步等待原调用、可信 Agent 归属、排队及幂等请求、调用现有 read 工具全管线、Job 进度与取消。无需模型参与等待。
+
+**B. 当前缺少的能力（仅记录，不修改宿主）**：跨进程重新认领原工具调用的公开契约，以及工具结果写入会话日志的持久化确认。若将来宿主提供，至少需要以 session + call-event-seq + callId 进行 CAS 认领、单次提交和可查询提交凭证，且必须在中断恢复合成结果前参与恢复。现在不实现、不伪造这些 API。
+
+**C. 本版降级**：受理、队列、结果与交付标记均为内存态。停止/崩溃后不可续接；不会自动重跑。新调用查询只能在当前插件实例的保存期内重取，不能当作恢复原调用。整体交付属于第一阶段、部分完成，不是完整跨重启总线。
+
+## 实际调用链和源码位置
+
+以下均为本机只读提取的**实际发布构建源码**，不是臆测的源码仓库路径。安装归档无法直接被普通文件工具当目录访问，提取脚本只向本项目写入。
+
+1. [Agent 调度器:506–532](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-agent-loop/lib/index.js#L506-L532)：requireInitiator 得到 Agent，产生 callId、arguments、agent、signal；runGroup 调度且等待结果。不在等待期间请求模型。
+2. [工具注册:2878–2886](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L2878-L2886)：ctx.tools.register 是作用域 effect，卸载自动移除。工具 execute 可以返回 Promise。
+3. [可信执行身份:3131–3175](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3131-L3175)：注册表生成 token，保留 callId、rootCallId、agent、signal，快照参数。
+4. [前置策略:3225](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3225) → [执行 waterfall 与工具体:3294–3331](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3294-L3331) → [后置策略:3504](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3504) → [最终 tools/result:3417](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L3417)。插件只调用公开 execute，不直接调用 read 的定义体，不跳过这些策略。
+5. [可选 PTC:1294–1307](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tools/lib/index.js#L1294-L1307)：子调用继承 agent、rootCallId，带 parent token；在原 run_code 时间预算内等待。[超时策略:4–6](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tool-call-timeout-policy/lib/index.js#L4-L6) 是协作式取消并 drain，不代表外部副作用失败。插件不改全局工具呈现、不拦截其他工具。
+6. [宿主 read:174](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tool-fs/lib/index.js#L174)：cwd 来自 exec.agent.session.header；[实际读取和输出限制:348](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tool-fs/lib/index.js#L348)。嵌套 read 在出队时重新进工具管线，沿用当时宿主权限和 fs 实现；插件没有独立 shell、spawn 或文件读取能力。read 的只读访问边界由宿主实际组合的 fs/权限实现决定，不能把 cwd 当作沙箱。隔离测试的 LocalFS 不等于桌面沙箱验证。
+7. [Job start:412–491](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-jobs-local/lib/index.js#L412-L491)：已有 owner 校验、controller admission、输出环、进度句柄、首终态约束；[等待:510](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-jobs-local/lib/index.js#L510)、[进度:717–729](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-jobs-local/lib/index.js#L717-L729)。插件只补排队、请求冲突和结果复用，不再造通用 Job 注册表。
+8. [完成通知抑制:268–270](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-tool-jobs/lib/index.js#L268-L270)：awaited 为 true 时不追加完成通知；插件先注册 wait 再等待终态，并移除已收集 Job。每 60 秒等待窗口续等由程序执行，不调用模型，不把超时改为失败。
+9. [原调用结果提交:680–706](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-agent-loop/lib/index.js#L680-L706)：宿主将结果关联原 callId 和 call-event-seq；插件只 return，不追加 tool/result 或聊天消息。
+10. [中断恢复:717–730](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-session/lib/index.js#L717-L730) 和 [interruptedTurnClosers:904](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-session/lib/index.js#L904)：为未保存结果生成 outcome unknown，不会复活内存中的 Promise。[Agent 恢复:1950](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-agent-loop/lib/index.js#L1950) 使用这个保守闭合机制。
+
+## 插件扩展方式
+
+- 工具：ctx.tools.register；服务：Cordis Service 的标准构造注册（例如 [JobRegistry:106–110](../dev/host-snapshot/node_modules/@deepseek-ai/dsh-jobs/lib/index.js#L106-L110)）。本插件没有替换宿主服务。
+- 事件：ctx.on / ctx.waterfall / ctx.emit；副作用生命周期 ctx.effect，异步 disposer 用于取消并等待处理中的任务。本插件未注册全局工具拦截器。
+- 界面：本版不注册自定义前端，复用现有 Jobs 进度事件和默认工具卡片。宿主原有客户端插件体系不是必需依赖；尚未完成该体系全部入口调查，不能提供未核实的 UI 注册示例。
+- 持久化：宿主会话日志有持久化；本地 Job 注册表注释明确是 process-local。二者不能混同为插件可恢复执行权。
+
+## 名称核对
+
+- [npm 官方接口](https://registry.npmjs.org/@feng0531%2Fdsh-execution-bus) 在调查时返回 404：未发现可见同名包，不代表预留成功或拥有发布权限。
+- 现有本地 origin 是 https://github.com/f-e-n-g-0531/dsh-execution-bus.git ，git ls-remote 读取 HEAD 为 06299e9425d6ba197c0d2e04bf8818ddfe471edf。仓库名称已经存在，与当前工作区既有 remote 一致，未创建、推送或修改远程；GitHub API 限流未拿到账户所有权证明。
+- 中文“执行总线”和英文“Execution Bus”是描述性显示名称，不是唯一名称或商标授权结论。
+
+## 验证分层
+
+真实 npm 宿主组件隔离冒烟：已运行（真实 ToolRuntime / LocalJobs / read / LocalFS，测试 Agent 夹具）。
+真实 AgentLoop + AgentRegistry + SessionStore 内存会话：脚本 LlmAdapter 隔离测试已通过，原工具成功结果只提交一次，再进入下一适配器请求。不是实际模型评测。真实桌面 GUI、磁盘会话持久化提交、真实模型推理续接、PTC 进程端到端：**未验证**。没有安装日常环境，也没有重启或使用模型凭据。组件测试不能替代这些结论。

package/docs/protocol.md

@@ -0,0 +1,52 @@
+# 协议 v1、状态与投递
+
+## 输入
+
+严格 JSON，最大 16 KiB，不接受额外顶层字段。messageId / requestId 为 1–128 位字母、数字、下划线、点、冒号或短横线。
+
+
+type 为 request 时 payload 为 {handler,input}；type 为 status / result / cancel 时 payload 必须为 {}。不支持其他类型或版本。sessionId、权限、工作目录不能出现在输入中，可信归属只能由宿主工具上下文绑定。
+
+- messageId 标识一条消息；同请求内同 messageId 不同内容拒绝。消息记账最多 128 条，超过拒绝新消息，不自动遗忘取消记账。
+- requestId 是一次逻辑操作的稳定幂等键；作用域为当前插件实例 + 宿主 session。相同 requestId 不同 handler/input 拒绝冲突，相同输入使用新 requestId 仍是新操作。
+- 输入规范排序后的摘要仅用于同 requestId 冲突比较，不作永久参数去重。保存期后旧键会失效，调用者不得因此盲目重跑有副作用操作。
+- callId / rootCallId / Agent / parent token 来自宿主；通过工具原本的 Promise 关联结果，不依赖模型提供的身份。
+
+## 输出
+
+核心 submit 返回 accepted 事件和 done Promise。受理只意味着已进入内存记录和队列，durable:false；不是成功。事件包含 protocolVersion、messageId、requestId、correlationId（首次请求 messageId）、sequence、type、payload。每请求 sequence 单调递增，accepted 是当前序号的快照，不占新增序号。
+
+事件类型：accepted、started、progress、cancel_requested、succeeded、failed、cancelled、unknown。进度只接受 Handler 正整数序号递增的百分比，重复、乱序、终态后进度丢弃。进程内投递，无外部消息接收端，也不支持任意远端终态注入；终态只由总线持有的执行 Promise 结算。
+
+工具的 request 保持 pending，最终返回 RecordView（requestId,state,sequence,cancelRequested,delivery,result?,error?,progress?）；status/result/cancel 返回同一种当前快照。工具不会提前返回 accepted 或 taskId，也不会用聊天进度消息唤醒模型。Job 的 UI progress 只含状态/百分比。
+
+## 状态转换
+
+queued → running → succeeded / failed / cancelled / unknown。
+queued → cancelled。终态不可变；取消终态任务只返回原状态。
+
+运行中取消先置 cancelRequested 并触发 AbortSignal，不立即声称 cancelled。Handler 用 AbortError 确认取消后才 cancelled；收到取消仍成功返回则 success 获胜；取消后其他异常为 unknown。Handler 必须合作取消并等待自身资源停止，不能把部分副作用当作已撤销。初版内置 Handler 仅为受控测试和只读宿主 read，没有非幂等写操作。
+
+异常是固定错误码，不将异常堆栈/原文写日志。过大或不可保存的结果进入 unknown / RESULT_NOT_RETAINED，不因结果传输失败自动执行一次。执行结束不等于交付，delivery 单独记录 pending / returned；returned 仅代表插件已走到工具返回路径，**不是会话持久化提交确认**。done 快照保留当时的 pending，后续查询可见 returned。宿主可能因取消/后置策略改变最终工具结果，插件不声称已确认模型收到。
+
+## 容量和清理
+
+默认并发 2，待分发队列 32，记录 256，单结果 JSON 64 KiB；所有请求先经上限检查，满则 BACKPRESSURE，不自动重试。Job 仍受宿主自己的每 owner 容量限制。队列不提供公平性 SLA，单会话可占满实例。
+
+终态自完成后保存一小时；新受理时惰性清理，可通过 core.sweep 主动清理。无定时器常驻、无磁盘结果存储、无日志输出。插件关闭先停止受理，取消队列与运行任务，等待合作 Handler，清理内存；不合作的 Handler 会阻碍关闭，插件无法安全硬杀同进程代码。
+
+敏感文件结果仍可能进入宿主原有工具会话日志，本插件不具备任意文本秘密识别能力。只请求确实需要的内容；不将敏感内容放入请求标识。结果长度检查发生在 Handler 返回后，扩展 Handler 自身也必须限制分配，不可把此检查当成防止超大对象构造的内存沙箱。
+
+## 投递语义、超时和恢复
+
+在同一个存活实例/保存期内，同 session + requestId 多次投递共用一次执行；每个实际工具调用独立取得一次响应。这不是端到端 exactly-once，同一请求重复调用仍会增加宿主工具调用记录。终态状态和结算锁避免一次执行被重复完成；不会额外主动提交会话结果。
+
+无网络传输层，因此自动通信重试次数为 **0**，也不自动重试执行。宿主 Job 60 秒窗口超时只是程序续等，不改变执行状态、不触发模型查询。PTC 外层仍有自己的时限和取消语义。
+
+本版不做持久化：受理/运行/结果/交付任一阶段进程崩溃都会丢失插件记录。宿主日志可能记录请求和结果，不代表插件恢复了执行。跨重启需人工结合宿主 outcome unknown 和外部实际状态处理；不能自动重跑非幂等操作。本版不实现对账钩子或跨进程重试，扩展有副作用 Handler 前必须另行设计这些能力。
+
+## 扩展 Handler
+
+core 导出 ExecutionBus、Handler 和 Capability 类型。register(name,handler) 返回注销函数；同名拒绝。Handler 提供 validate 和 async run，执行上下文仅有 requestId、signal、progress 与最小执行 capability，不传聊天历史。注销不影响已受理任务捕获的 Handler；关闭时等待它们。
+
+当前插件内置注册 test 与 host.read。尚未公开 Cordis Handler 注册服务，其他插件不能假定存在 ctx.executionBus；跨插件动态注册属于后续事项。

package/docs/releases/0.1.0.md

@@ -0,0 +1,17 @@
+# 执行总线 0.1.0
+
+## 本版变化
+
+第一阶段纯插件原型：版本化协议、有界队列、请求复用与冲突检查、原工具异步等待、宿主 Job 进度、受控测试 Handler 和宿主只读 read 接入。测试与发布流程参考 dsh-vcs，标签触发四矩阵 CI，正式发布独立手动门禁。
+
+## 安装
+
+提供 npm 包 @feng0531/dsh-execution-bus@0.1.0 和同包 GitHub Release 安装制品；发布过程不安装到日常 DSH。兼容目标 DSH 0.2.0-rc.2。请先阅读 README 和宿主兼容说明，选择隔离配置。
+
+## 限制
+
+非持久化、不支持跨重启原调用恢复，不提供任意命令执行。真实模型、GUI、桌面沙箱、PTC 全链路尚未验证。采用非商业源码公开许可证，非 OSI 开源许可；商业项目内部使用及有偿交付需要另行书面授权。
+
+## 验证
+
+真实宿主组件与 AgentLoop 内存会话采用脚本模型隔离测试；不能当作真实模型端到端通过。具体本地测试数与检查结果见 docs/validation.md。2026-10-15 正式发布完成：Windows/Ubuntu × Node 22/24 四项标签 CI 全部通过，发布工作流成功。npm latest 为 0.1.0；npm 与 GitHub 实际下载包均为 22,017 字节，与候选逐字节一致，SHA-256 为 9b5f57d829c2238d0bed8548e17633a67b15a5358b792df0d492071a261529ce。

package/docs/releases/0.1.1.md

@@ -0,0 +1,18 @@
+# 执行总线 0.1.1
+
+## 本版变化
+
+本版为 BUG 修复，无新增业务执行能力。
+
+- 修复 core 多个结果消费者共享可修改终态快照，可能污染后续重复请求结果的问题；终态快照改为深度冻结。
+- 修复 Handler 已完成但返回值无法 JSON 序列化时被误记执行失败的问题；记录为 unknown / RESULT_NOT_RETAINED，不自动重跑。
+- 修复没有新请求时过期结果仍能查询/重取的问题；控制消息入口补上 TTL 清理。
+- 增加不安装插件的可复用流程测试命令 npm run test:flow，以及三项修复前失败、修复后通过的回归测试。
+
+## 安装与许可
+
+npm 包 @feng0531/dsh-execution-bus@0.1.1，兼容目标 DSH 0.2.0-rc.2；建议先用隔离配置。非商业源码公开许可，具体以 LICENSE 为准。发布不自动安装、升级或重启日常 DSH。
+
+## 验证与限制
+
+本地全量 24/24 测试通过；真实宿主组件、AgentLoop 内存会话均为隔离测试，模型侧使用脚本适配器，不等于当前会话直接调用 execution_bus。真实模型、GUI、PTC 和桌面沙箱未验收；不持久化、不支持跨重启恢复。正式发布仍需同标签四矩阵 CI、包白名单、候选一致性、隔离安装与公开 npm 包核验全部通过。

package/docs/validation.md

@@ -0,0 +1,61 @@
+# 验证记录与交付状态
+
+日期：2026-10-15。Node 24.21.0，Windows，宿主精确兼容目标 0.2.0-rc.2。全部开发改动仅在当前独立仓库，未修改/重启 DSH，未发布 npm、未推送远程、未安装用户日常配置。
+
+## 自动化测试
+
+npm test：**21/21 通过**。本地 tgz 已在 artifacts/package-check 独立目录完成 npm 安装及入口 import 验证（不是 DSH 插件管理器安装）。测试名称是断言集合，不等于 21 项完整产品验收。
+
+- 正常请求、受理不冒充成功、原 Promise 等待、终态只有一次、交付标记分离。
+- 两个 session 同 requestId 结果独立，第三会话查询/取消拒绝。
+- 同请求共用执行，同键不同输入冲突；同参数新键为不同操作。
+- 重复/乱序/迟到进度丢弃，观察者抛错不影响执行。
+- 等待时间短于执行时仍保持运行，不生成失败。
+- 排队取消、运行取消、晚取消、完成竞争；取消未确认为 unknown；unknown 不自动重跑。
+- 队列/记录容量背压、并发为一时第二任务保持 queued、控制消息上限。
+- Handler 异常、未知 Handler、未知消息类型/版本、伪造身份字段、输入越界、结果过大、异常敏感文本不泄漏。
+- 关闭合作任务并拒绝新受理；终态 TTL 清理，不误清理运行任务。
+
+真实宿主**组件**隔离测试使用 npm 原版 Cordis + ToolRuntime + LocalJobs + LocalFS + tool-fs。Agent/agents 注册表是夹具，没有运行真实 AgentLoop 或模型。测试通过实际 read 工具读取本仓库包声明，通过真实 pre-execute 拒绝读操作，确认权限管线仍在；测试进度事件、awaited 终态、Job 移除、重复请求并发、调用中断、插件作用域卸载和工具注销。
+
+## 真实宿主循环隔离验证
+
+另有独立测试运行真实 AgentLoop、AgentRegistry、SessionStore、ToolRuntime 和 Jobs；模型侧是确定性 Scripted LlmAdapter，不访问网络或凭据。适配器先产生一次 execution_bus 请求，宿主等待成功终态并记录一次 tool/result，toolCallId 为 original-call，随后才进行第二次适配器调用并完成回答。无模型轮询、无额外聊天进度消息。这是实际宿主循环和内存会话闭环，不是实际模型评测，也没有验证磁盘持久化。
+
+## 未验证（不是通过）
+
+| 项目 | 状态与原因 |
+|---|---|
+| 当前桌面真实模型 → 原调用 → 结果 → 模型继续 | 未验证；未安装到日常宿主，也未启用真实模型凭据 |
+| GUI Jobs 实际可视展示 | 未验证；仅证明进度事件进入真实 Job 注册表 |
+| 当前 Windows 授权提示和文件沙箱集成 | 未验证；测试使用 LocalFS 和前置拒绝策略，不代表桌面沙箱 |
+| PTC 完整进程入口和超时 | 源码核查/类型兼容；未执行真实 PTC 冒烟 |
+| 真实模型面对重复终态的继续行为 | 真实循环的单次结果提交已验证；真实模型及外部终态重投链路未验证 |
+| 跨重启恢复原调用 | 不支持，不能用新消息冒充 |
+| 受理/运行/结果/交付四阶段持久化崩溃注入 | 未实现持久化，不声称通过；当前实例丢失的边界测试通过 |
+| 模型轮次、主动查询、重复执行、总耗时对照 | 全部未验证；不捏造提升比例 |
+| 插件管理器完整安装、卸载与回滚 | 未验证；仅包构建/内容检查及 Cordis effect 注销 |
+
+## CI 与发布流程检查
+
+参考 dsh-vcs 配置标签/手动 CI：Windows/Ubuntu × Node 22/24；普通分支和 PR 不触发。新增版本/锁文件/标签一致性、包严格白名单、全新临时目录生产依赖安装、工作流 YAML 契约和许可证缺失拒绝测试。本地 Windows/Node 24 的 check、verify:package、pack:candidate、test:install 通过，npm audit 为 0 漏洞。
+
+发布仅手动确认后运行，需精确标签 CI 成功且四份候选与重建包逐字节一致；先 npm 上传并验证公开实际字节，再创建 GitHub Release。用户已确认非商业许可证并授权正式发布；预检仍验证明确确认词及完整 LICENSE。2026-10-15：v0.1.0 标签 CI 四矩阵成功（运行 38705851984），联合发布成功（38706021548）。GitHub Release 非草稿、非预发布；npm latest 为 0.1.0。公开 npm/GitHub 包均为 22,017 字节，与候选逐字节一致，SHA-256：9b5f57d829c2238d0bed8548e17633a67b15a5358b792df0d492071a261529ce。npm-release 环境此前不存在，未配置维护者保护审批，发布使用用户授权及工作流明确确认门禁。
+
+## 已完成 / 部分完成 / 后续
+
+已完成：可编译独立插件、协议/状态核心、测试 Handler、真实只读执行管线适配、宿主 Job 进度事件、自动化测试和中文文档。
+
+部分完成：会话闭环已验证到真实 AgentLoop/内存 Session，使用脚本适配器；真实模型与磁盘会话仍未验证。显示名称体现在工具说明和 Job 标签，未提供插件市场 UI 元数据。Handler core 可扩展，尚无跨插件服务。
+
+未实现：持久化、跨重启重关联、非幂等 Handler 对账、远端传输与通信重试（当前零重试）、自定义 UI。只做插件的约束保持不变。
+
+下一步应先在用户明确授权的隔离 DSH 配置进行真实模型/AgentLoop/PTC/GUI 冒烟，再决定持久化范围。不应先上线任意命令或有副作用执行 Handler。
+
+## 已知限制
+
+- 并发重复附着现在共享一个宿主 Job 和程序等待者；回归测试断言只新增一个 Job。Job admission 首次失败会取消尚未执行的受理请求。保存期内已完成请求的再次重取可能建立短暂 Job，但不会重新执行 Handler。
+- 同一逻辑请求的任一等待工具被取消，会请求取消共享执行；这是本版明确的请求级取消规则，不是独立等待者取消。
+- returned 不证明宿主已经持久化或模型已经消费，取消/后置策略仍可能改变最终宿主结果。
+- 核心不是独立安全边界；可信插件可以注册 Handler，恶意同进程插件不在威胁模型内。
+- 本地源码证据快照不包含在 npm 包中；文档相对证据链接适用于开发仓库提取后阅读，安装包读者应使用所列组件名及构建行号查对应版本。

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@feng0531/dsh-execution-bus",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "private": false,
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "repository": { "type": "git", "url": "git+https://github.com/f-e-n-g-0531/dsh-execution-bus.git" },
+  "description": "执行总线 / Execution Bus: bounded DSH handler dispatch with original-call waiting",
+  "main": "dist/plugin.js",
+  "exports": {
+    ".": "./dist/plugin.js",
+    "./core": "./dist/bus.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "README.md",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "pack": "npm pack",
+    "check": "npm test",
+    "test:flow": "npm run build && node --test test/flow-regression.test.mjs test/host.test.mjs test/agent-loop.test.mjs",
+    "prepack": "npm run check && npm run verify:package",
+    "verify:package": "node scripts/verify-package.mjs",
+    "test:install": "node scripts/test-install.mjs",
+    "pack:candidate": "node scripts/pack.mjs",
+    "verify:release": "node scripts/release-preflight.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-jobs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent-loop": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-fs-local": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-jobs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-jobs-local": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-fs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tool-jobs": "0.2.0-rc.2",
+    "@types/node": "^22",
+    "prettier": "3.6.2",
+    "typescript": "~5.9.3",
+    "yaml": "2.9.1"
+  }
+}