@feng0531/dsh-execution-bus 0.5.0 → 0.6.0

package/dist/error-codes.d.ts

@@ -0,0 +1,54 @@
+/** 集中全部固定错误码。值即协议 v1 的稳定错误词汇，不得重命名或改动。
+ *  新增错误码前先更新 docs/protocol.md 的错误词汇表。 */
+export declare const ERRORS: Readonly<{
+    INVALID_OBJECT: "INVALID_OBJECT";
+    UNKNOWN_FIELD: "UNKNOWN_FIELD";
+    UNSUPPORTED_VERSION: "UNSUPPORTED_VERSION";
+    INVALID_ID: "INVALID_ID";
+    UNSUPPORTED_TYPE: "UNSUPPORTED_TYPE";
+    MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE";
+    JSON_LIMIT: "JSON_LIMIT";
+    INVALID_JSON: "INVALID_JSON";
+    CYCLIC_JSON: "CYCLIC_JSON";
+    INVALID_JSON_ARRAY: "INVALID_JSON_ARRAY";
+    INVALID_JSON_OBJECT: "INVALID_JSON_OBJECT";
+    INVALID_JSON_KEY: "INVALID_JSON_KEY";
+    INVALID_JSON_PROPERTY: "INVALID_JSON_PROPERTY";
+    CLOSED: "CLOSED";
+    EXPECTED_REQUEST: "EXPECTED_REQUEST";
+    INVALID_REQUEST: "INVALID_REQUEST";
+    REQUEST_CONFLICT: "REQUEST_CONFLICT";
+    MESSAGE_CONFLICT: "MESSAGE_CONFLICT";
+    MESSAGE_LIMIT: "MESSAGE_LIMIT";
+    UNKNOWN_HANDLER: "UNKNOWN_HANDLER";
+    BACKPRESSURE: "BACKPRESSURE";
+    SESSION_BACKPRESSURE: "SESSION_BACKPRESSURE";
+    WAITER_LIMIT: "WAITER_LIMIT";
+    EXPECTED_CONTROL: "EXPECTED_CONTROL";
+    INVALID_CONTROL: "INVALID_CONTROL";
+    NOT_FOUND: "NOT_FOUND";
+    UNTRUSTED_CONTEXT: "UNTRUSTED_CONTEXT";
+    OWNING_SESSION_REQUIRED: "OWNING_SESSION_REQUIRED";
+    QUEUE_WAIT_TIMEOUT: "QUEUE_WAIT_TIMEOUT";
+    RESULT_NOT_RETAINED: "RESULT_NOT_RETAINED";
+    CANCELLED: "CANCELLED";
+    CANCELLATION_UNCONFIRMED: "CANCELLATION_UNCONFIRMED";
+    HANDLER_FAILED: "HANDLER_FAILED";
+    INVALID_ADMISSION_POLICY: "INVALID_ADMISSION_POLICY";
+    INVALID_OPTIONS: "INVALID_OPTIONS";
+    DUPLICATE_HANDLER: "DUPLICATE_HANDLER";
+    MUTATING_REUSE_DENIED: "MUTATING_REUSE_DENIED";
+    DUPLICATE_EXECUTION_HANDLE: "DUPLICATE_EXECUTION_HANDLE";
+    INVALID_STATE_QUERY: "INVALID_STATE_QUERY";
+    HOST_READ_FAILED: "HOST_READ_FAILED";
+    HOST_JOB_UNAVAILABLE: "HOST_JOB_UNAVAILABLE";
+    PTC_PRESET_TOO_LARGE: "PTC_PRESET_TOO_LARGE";
+    PTC_PRESET_ALREADY_CONTAINS_BUS: "PTC_PRESET_ALREADY_CONTAINS_BUS";
+    PTC_PRESET_RELATIVE_BASE_UNSUPPORTED: "PTC_PRESET_RELATIVE_BASE_UNSUPPORTED";
+    PTC_PRESET_UNAVAILABLE: "PTC_PRESET_UNAVAILABLE";
+    INVALID_TEST_INPUT: "INVALID_TEST_INPUT";
+    INVALID_READ_INPUT: "INVALID_READ_INPUT";
+    READ_LIMIT: "READ_LIMIT";
+    CONTROLLED_FAILURE: "CONTROLLED_FAILURE";
+    HOST_CAPABILITY_REQUIRED: "HOST_CAPABILITY_REQUIRED";
+}>;

package/dist/error-codes.js

@@ -0,0 +1,60 @@
+/** 集中全部固定错误码。值即协议 v1 的稳定错误词汇，不得重命名或改动。
+ *  新增错误码前先更新 docs/protocol.md 的错误词汇表。 */
+export const ERRORS = Object.freeze({
+    // —— 协议解析（protocol） ——
+    INVALID_OBJECT: "INVALID_OBJECT",
+    UNKNOWN_FIELD: "UNKNOWN_FIELD",
+    UNSUPPORTED_VERSION: "UNSUPPORTED_VERSION",
+    INVALID_ID: "INVALID_ID",
+    UNSUPPORTED_TYPE: "UNSUPPORTED_TYPE",
+    MESSAGE_TOO_LARGE: "MESSAGE_TOO_LARGE",
+    // —— 严格 JSON（json） ——
+    JSON_LIMIT: "JSON_LIMIT",
+    INVALID_JSON: "INVALID_JSON",
+    CYCLIC_JSON: "CYCLIC_JSON",
+    INVALID_JSON_ARRAY: "INVALID_JSON_ARRAY",
+    INVALID_JSON_OBJECT: "INVALID_JSON_OBJECT",
+    INVALID_JSON_KEY: "INVALID_JSON_KEY",
+    INVALID_JSON_PROPERTY: "INVALID_JSON_PROPERTY",
+    // —— 总线调度与准入（bus） ——
+    CLOSED: "CLOSED",
+    EXPECTED_REQUEST: "EXPECTED_REQUEST",
+    INVALID_REQUEST: "INVALID_REQUEST",
+    REQUEST_CONFLICT: "REQUEST_CONFLICT",
+    MESSAGE_CONFLICT: "MESSAGE_CONFLICT",
+    MESSAGE_LIMIT: "MESSAGE_LIMIT",
+    UNKNOWN_HANDLER: "UNKNOWN_HANDLER",
+    BACKPRESSURE: "BACKPRESSURE",
+    SESSION_BACKPRESSURE: "SESSION_BACKPRESSURE",
+    WAITER_LIMIT: "WAITER_LIMIT",
+    EXPECTED_CONTROL: "EXPECTED_CONTROL",
+    INVALID_CONTROL: "INVALID_CONTROL",
+    NOT_FOUND: "NOT_FOUND",
+    UNTRUSTED_CONTEXT: "UNTRUSTED_CONTEXT",
+    OWNING_SESSION_REQUIRED: "OWNING_SESSION_REQUIRED",
+    QUEUE_WAIT_TIMEOUT: "QUEUE_WAIT_TIMEOUT",
+    RESULT_NOT_RETAINED: "RESULT_NOT_RETAINED",
+    CANCELLED: "CANCELLED",
+    CANCELLATION_UNCONFIRMED: "CANCELLATION_UNCONFIRMED",
+    HANDLER_FAILED: "HANDLER_FAILED",
+    INVALID_ADMISSION_POLICY: "INVALID_ADMISSION_POLICY",
+    INVALID_OPTIONS: "INVALID_OPTIONS",
+    DUPLICATE_HANDLER: "DUPLICATE_HANDLER",
+    MUTATING_REUSE_DENIED: "MUTATING_REUSE_DENIED",
+    // —— 宿主投影（execution / plugin） ——
+    DUPLICATE_EXECUTION_HANDLE: "DUPLICATE_EXECUTION_HANDLE",
+    INVALID_STATE_QUERY: "INVALID_STATE_QUERY",
+    HOST_READ_FAILED: "HOST_READ_FAILED",
+    HOST_JOB_UNAVAILABLE: "HOST_JOB_UNAVAILABLE",
+    // —— 预设派生（preset） ——
+    PTC_PRESET_TOO_LARGE: "PTC_PRESET_TOO_LARGE",
+    PTC_PRESET_ALREADY_CONTAINS_BUS: "PTC_PRESET_ALREADY_CONTAINS_BUS",
+    PTC_PRESET_RELATIVE_BASE_UNSUPPORTED: "PTC_PRESET_RELATIVE_BASE_UNSUPPORTED",
+    PTC_PRESET_UNAVAILABLE: "PTC_PRESET_UNAVAILABLE",
+    // —— 内置 Handler（handlers） ——
+    INVALID_TEST_INPUT: "INVALID_TEST_INPUT",
+    INVALID_READ_INPUT: "INVALID_READ_INPUT",
+    READ_LIMIT: "READ_LIMIT",
+    CONTROLLED_FAILURE: "CONTROLLED_FAILURE",
+    HOST_CAPABILITY_REQUIRED: "HOST_CAPABILITY_REQUIRED",
+});

package/dist/execution.d.ts

@@ -22,6 +22,10 @@ export declare class ExecutionHandle {
     progress(event: Event): void;
     private absent;
     private waitAndClean;
+    /** 等待宿主 Job 到达终态（离开 running/stopping）。 */
+    private awaitTerminal;
+    /** wait 失败后的有界恢复：清理已终态的 Job，但仍向上保留原始错误可见性。 */
+    private recoverOnWaitError;
 }
 export type ShutdownPhase = "open" | "stopping" | "draining" | "releasing" | "closed";
 /** Owns host projections and active deliveries, not a second execution state machine. */
@@ -56,6 +60,10 @@ export declare class ExecutionOwner {
     get phase(): ShutdownPhase;
     get(key: string): ExecutionHandle | undefined;
     add(key: string, handle: ExecutionHandle): void;
+    /** 拒绝关闭后或重复 key 的准入；create/add 共用这一道守卫。 */
+    private assertAdmittable;
+    /** 登记 handle，并在其结算后从表中移除该登记。 */
+    private attach;
     track<T>(delivery: Promise<T>): Promise<T>;
     close(drainCore: () => Promise<void>): Promise<void>;
 }

package/dist/execution.js

@@ -1,5 +1,17 @@
 import { setTimeout as pause } from "node:timers/promises";
 import { Diagnostics } from "./diagnostics.js";
+import { ERRORS } from "./error-codes.js";
+/** 把执行终态映射为宿主 Job 的结果状态。 */
+function jobOutcome(state) {
+    return {
+        status: state === "succeeded"
+            ? "completed"
+            : state === "cancelled"
+                ? "killed"
+                : "failed",
+        detail: state,
+    };
+}
 /** One host projection of a logical execution. The core completion remains authoritative. */
 export class ExecutionHandle {
     jobs;
@@ -18,14 +30,7 @@ export class ExecutionHandle {
         this.telemetry = telemetry;
         this.trace = telemetry.begin();
         this.completion = execution.done;
-        const outcome = this.completion.then((v) => ({
-            status: v.state === "succeeded"
-                ? "completed"
-                : v.state === "cancelled"
-                    ? "killed"
-                    : "failed",
-            detail: v.state,
-        }));
+        const outcome = this.completion.then((v) => jobOutcome(v.state));
         this.job = jobs.start({
             kind: "execution-bus",
             label: "萧何 / Xiao He",
@@ -58,49 +63,58 @@ export class ExecutionHandle {
     }
     async waitAndClean() {
         try {
-            for (;;) {
-                const view = await this.jobs.wait(this.job, 60000, this.owner);
-                if (view.status !== "running" && view.status !== "stopping")
-                    break;
-            }
+            await this.awaitTerminal();
             this.jobs.remove(this.job, this.owner);
             this.telemetry.record(this.trace, "job_released");
         }
         catch (error) {
             this.telemetry.record(this.trace, "job_error");
-            const removed = this.absent(error);
-            // Retain the original execution, including while its caller/owner is being disposed.
-            await this.completion;
-            if (removed)
-                this.telemetry.record(this.trace, "job_released");
-            if (!removed) {
-                for (let attempt = 0; attempt < 20; attempt++) {
-                    try {
-                        const view = this.jobs
-                            .list(this.owner)
-                            .find((v) => v.id === this.job && v.owner === this.owner);
-                        if (!view) {
-                            this.telemetry.record(this.trace, "job_released");
-                            break;
-                        }
-                        if (view.status !== "running" && view.status !== "stopping") {
-                            this.jobs.remove(this.job, this.owner);
-                            this.telemetry.record(this.trace, "job_released");
-                            break;
-                        }
-                    }
-                    catch {
-                        break;
-                    }
-                    await pause(10);
-                }
-                throw error;
-            }
+            await this.recoverOnWaitError(error);
         }
         finally {
             this.progressHandle = undefined;
         }
     }
+    /** 等待宿主 Job 到达终态（离开 running/stopping）。 */
+    async awaitTerminal() {
+        for (;;) {
+            const view = await this.jobs.wait(this.job, 60000, this.owner);
+            if (view.status !== "running" && view.status !== "stopping")
+                return;
+        }
+    }
+    /** wait 失败后的有界恢复：清理已终态的 Job，但仍向上保留原始错误可见性。 */
+    async recoverOnWaitError(error) {
+        const alreadyRemoved = this.absent(error);
+        // 保留原执行结果，即便其调用者/owner 正在被释放。
+        await this.completion;
+        // Job 已不在列表时仅记录释放，不把 wait 错误视为未处理的清理失败。
+        if (alreadyRemoved) {
+            this.telemetry.record(this.trace, "job_released");
+            return;
+        }
+        for (let attempt = 0; attempt < 20; attempt++) {
+            try {
+                const view = this.jobs
+                    .list(this.owner)
+                    .find((v) => v.id === this.job && v.owner === this.owner);
+                if (!view) {
+                    this.telemetry.record(this.trace, "job_released");
+                    break;
+                }
+                if (view.status !== "running" && view.status !== "stopping") {
+                    this.jobs.remove(this.job, this.owner);
+                    this.telemetry.record(this.trace, "job_released");
+                    break;
+                }
+            }
+            catch {
+                break;
+            }
+            await pause(10);
+        }
+        throw error;
+    }
 }
 /** Owns host projections and active deliveries, not a second execution state machine. */
 export class ExecutionOwner {
@@ -109,12 +123,9 @@ export class ExecutionOwner {
     closing;
     telemetry = new Diagnostics();
     create(key, jobs, owner, execution) {
-        if (this.phase !== "open")
-            throw Error("CLOSED");
-        if (this.handles.has(key))
-            throw Error("DUPLICATE_EXECUTION_HANDLE");
+        this.assertAdmittable(key);
         const handle = new ExecutionHandle(jobs, owner, execution, this.telemetry);
-        this.add(key, handle);
+        this.attach(key, handle);
         return handle;
     }
     diagnostics() {
@@ -133,10 +144,18 @@ export class ExecutionOwner {
         return this.handles.get(key);
     }
     add(key, handle) {
+        this.assertAdmittable(key);
+        this.attach(key, handle);
+    }
+    /** 拒绝关闭后或重复 key 的准入；create/add 共用这一道守卫。 */
+    assertAdmittable(key) {
         if (this.phase !== "open")
-            throw Error("CLOSED");
+            throw Error(ERRORS.CLOSED);
         if (this.handles.has(key))
-            throw Error("DUPLICATE_EXECUTION_HANDLE");
+            throw Error(ERRORS.DUPLICATE_EXECUTION_HANDLE);
+    }
+    /** 登记 handle，并在其结算后从表中移除该登记。 */
+    attach(key, handle) {
         this.handles.set(key, handle);
         const release = () => {
             if (this.handles.get(key) === handle)

package/dist/handlers.js

@@ -1,12 +1,15 @@
 import { setTimeout } from "node:timers/promises";
+import { ERRORS } from "./error-codes.js";
+import { HANDLER_LIMITS } from "./product.js";
 export const testHandler = {
+    idempotent: true,
     validate(input) {
         if (Object.keys(input).some((k) => !["delayMs", "fail"].includes(k)) ||
             !Number.isSafeInteger(input.delayMs) ||
             Number(input.delayMs) < 0 ||
-            Number(input.delayMs) > 30000 ||
+            Number(input.delayMs) > HANDLER_LIMITS.diagnosticDelayMs ||
             typeof input.fail !== "boolean")
-            throw Error("INVALID_TEST_INPUT");
+            throw Error(ERRORS.INVALID_TEST_INPUT);
     },
     async run(input, ctx) {
         for (let i = 1; i <= 5; i++) {
@@ -16,27 +19,28 @@ export const testHandler = {
             ctx.progress(i, i * 20);
         }
         if (input.fail)
-            throw Error("CONTROLLED_FAILURE");
+            throw Error(ERRORS.CONTROLLED_FAILURE);
         return { ok: true };
     },
 };
 export const readHandler = {
+    idempotent: true,
     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");
+            input.file_path.length > HANDLER_LIMITS.readPathChars)
+            throw Error(ERRORS.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");
+                throw Error(ERRORS.INVALID_READ_INPUT);
+        if (Number(input.limit ?? HANDLER_LIMITS.readLines) > HANDLER_LIMITS.readLines)
+            throw Error(ERRORS.READ_LIMIT);
     },
     async run(input, ctx) {
         if (!ctx.invoke)
-            throw Error("HOST_CAPABILITY_REQUIRED");
-        return ctx.invoke({ ...input, limit: input.limit ?? 100 }, ctx.signal);
+            throw Error(ERRORS.HOST_CAPABILITY_REQUIRED);
+        return ctx.invoke({ ...input, limit: input.limit ?? HANDLER_LIMITS.readLines }, ctx.signal);
     },
 };

package/dist/json.d.ts

@@ -1,4 +1,4 @@
 /** Strict JSON tree validation before serialization, cloning or recursive freezing. */
 export declare function assertJson(value: unknown, depth?: number, active?: Set<object>, budget?: {
-    left: number;
+    left: 65536;
 }): void;

package/dist/json.js

@@ -1,7 +1,9 @@
+import { ERRORS } from "./error-codes.js";
+import { LIMITS } from "./limits.js";
 /** Strict JSON tree validation before serialization, cloning or recursive freezing. */
-export function assertJson(value, depth = 0, active = new Set(), budget = { left: 65536 }) {
-    if (--budget.left < 0 || depth > 64)
-        throw Error("JSON_LIMIT");
+export function assertJson(value, depth = 0, active = new Set(), budget = { left: LIMITS.jsonNodeBudget }) {
+    if (--budget.left < 0 || depth > LIMITS.jsonMaxDepth)
+        throw Error(ERRORS.JSON_LIMIT);
     if (value === null || typeof value === "string" || typeof value === "boolean")
         return;
     if (typeof value === "number" &&
@@ -9,32 +11,32 @@ export function assertJson(value, depth = 0, active = new Set(), budget = { left
         !Object.is(value, -0))
         return;
     if (typeof value !== "object" || value === null)
-        throw Error("INVALID_JSON");
+        throw Error(ERRORS.INVALID_JSON);
     if (active.has(value))
-        throw Error("CYCLIC_JSON");
+        throw Error(ERRORS.CYCLIC_JSON);
     const array = Array.isArray(value);
     if (array && Object.getPrototypeOf(value) !== Array.prototype)
-        throw Error("INVALID_JSON_ARRAY");
+        throw Error(ERRORS.INVALID_JSON_ARRAY);
     if (!array &&
         Object.getPrototypeOf(value) !== Object.prototype &&
         Object.getPrototypeOf(value) !== null)
-        throw Error("INVALID_JSON_OBJECT");
+        throw Error(ERRORS.INVALID_JSON_OBJECT);
     active.add(value);
     try {
         const keys = Reflect.ownKeys(value);
         if (array && keys.length !== value.length + 1)
-            throw Error("INVALID_JSON_ARRAY");
+            throw Error(ERRORS.INVALID_JSON_ARRAY);
         for (const key of keys) {
             if (array && key === "length")
                 continue;
             if (typeof key !== "string")
-                throw Error("INVALID_JSON_KEY");
+                throw Error(ERRORS.INVALID_JSON_KEY);
             if (array &&
                 (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length))
-                throw Error("INVALID_JSON_ARRAY");
+                throw Error(ERRORS.INVALID_JSON_ARRAY);
             const descriptor = Object.getOwnPropertyDescriptor(value, key);
             if (!descriptor.enumerable || !("value" in descriptor))
-                throw Error("INVALID_JSON_PROPERTY");
+                throw Error(ERRORS.INVALID_JSON_PROPERTY);
             assertJson(descriptor.value, depth + 1, active, budget);
         }
     }

package/dist/limits.d.ts

@@ -0,0 +1,20 @@
+export declare const LIMITS: Readonly<{
+    /** 单条协议消息 JSON 的最大字节数（parse 拒绝更大消息）。 */
+    messageMaxBytes: 16384;
+    /** messageId / requestId 的最大字符数。 */
+    idMaxLength: 128;
+    /** messageId / requestId 的合法字符集。 */
+    idPattern: RegExp;
+    /** 单个逻辑执行所记账的消息条数上限（含首次、重复请求与查询）。 */
+    messageAccountLimit: 128;
+    /** 单个执行可同时附着的观察者上限。 */
+    waiterLimit: 32;
+    /** inspect() 单次返回的任务元数据条数上限。 */
+    inspectTaskLimit: 50;
+    /** 严格 JSON 树的最大嵌套深度。 */
+    jsonMaxDepth: 64;
+    /** 严格 JSON 树可访问的节点总数预算。 */
+    jsonNodeBudget: 65536;
+    /** 诊断环形轨迹的槽位数量。 */
+    traceRingSize: 128;
+}>;

package/dist/limits.js

@@ -0,0 +1,23 @@
+/** 集中定义跨模块共享的固定数值上限。内部实现约束，非用户可配置项。
+ *  数值相同时语义依然独立，勿为了“省一个常量”而合并。 */
+const ID_MAX_LENGTH = 128;
+export const LIMITS = Object.freeze({
+    /** 单条协议消息 JSON 的最大字节数（parse 拒绝更大消息）。 */
+    messageMaxBytes: 16384,
+    /** messageId / requestId 的最大字符数。 */
+    idMaxLength: ID_MAX_LENGTH,
+    /** messageId / requestId 的合法字符集。 */
+    idPattern: new RegExp(`^[a-zA-Z0-9_.:-]{1,${ID_MAX_LENGTH}}$`),
+    /** 单个逻辑执行所记账的消息条数上限（含首次、重复请求与查询）。 */
+    messageAccountLimit: 128,
+    /** 单个执行可同时附着的观察者上限。 */
+    waiterLimit: 32,
+    /** inspect() 单次返回的任务元数据条数上限。 */
+    inspectTaskLimit: 50,
+    /** 严格 JSON 树的最大嵌套深度。 */
+    jsonMaxDepth: 64,
+    /** 严格 JSON 树可访问的节点总数预算。 */
+    jsonNodeBudget: 65536,
+    /** 诊断环形轨迹的槽位数量。 */
+    traceRingSize: 128,
+});

package/dist/mode.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from "@deepseek-ai/cordis";
+export declare const name: "execution-bus-mode";
+export declare const inject: string[];
+/** An additive preset row: presentation, tool inventory and authority belong to the host PTC composition. */
+export declare function apply(ctx: Context): void;

package/dist/mode.js

@@ -0,0 +1,16 @@
+import { scopeOf } from "@deepseek-ai/dsh-scope";
+import { apply as applyBus } from "./plugin.js";
+import { PRODUCT, MODE_INSTRUCTIONS } from "./product.js";
+export const name = PRODUCT.modePluginName;
+export const inject = ["tools", "jobs", "systemPrompt"];
+/** An additive preset row: presentation, tool inventory and authority belong to the host PTC composition. */
+export function apply(ctx) {
+    if (scopeOf(ctx) === undefined)
+        throw Error("Xiao He mode requires an Agent preset scope");
+    ctx.effect(() => ctx.systemPrompt.section({
+        name: "XIAO_HE_EXECUTION_BUS",
+        order: 1700,
+        text: MODE_INSTRUCTIONS,
+    }));
+    applyBus(ctx);
+}