@feng0531/dsh-execution-bus 0.5.1 → 0.6.0

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,13 +1,15 @@
 import { setTimeout } from "node:timers/promises";
-import { LIMITS } from "./product.js";
+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) > LIMITS.diagnosticDelayMs ||
+            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++) {
@@ -17,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 > LIMITS.readPathChars)
-            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 ?? LIMITS.readLines) > LIMITS.readLines)
-            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 ?? LIMITS.readLines }, 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/plugin.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { ADMISSION_DEFAULTS, REQUEST_DESCRIPTION, REQUEST_PARAMETERS, STATE_PARAMETERS, } from "./product.js";
 import { ExecutionOwner } from "./execution.js";
 import { ExecutionBus, parse } from "./bus.js";
+import { ERRORS } from "./error-codes.js";
 import { testHandler, readHandler } from "./handlers.js";
 export const name = "execution-bus";
 export const inject = ["tools", "jobs"];
@@ -21,14 +22,14 @@ export function apply(ctx) {
         },
         async execute(raw, exec) {
             if (executions.phase !== "open")
-                throw Error("CLOSED");
+                throw Error(ERRORS.CLOSED);
             if (!exec.agent)
-                throw Error("OWNING_SESSION_REQUIRED");
+                throw Error(ERRORS.OWNING_SESSION_REQUIRED);
             if (!raw ||
                 typeof raw !== "object" ||
                 Array.isArray(raw) ||
                 Reflect.ownKeys(raw).length)
-                throw Error("INVALID_STATE_QUERY");
+                throw Error(ERRORS.INVALID_STATE_QUERY);
             return bus.inspect({
                 sessionId: String(exec.agent.id),
                 callId: String(exec.callId),
@@ -45,21 +46,25 @@ export function apply(ctx) {
         },
         execute(raw, exec) {
             if (executions.phase !== "open")
-                return Promise.reject(Error("CLOSED"));
+                return Promise.reject(Error(ERRORS.CLOSED));
             return executions.track(dispatch(raw, exec));
         },
     });
     async function dispatch(raw, exec) {
         if (!exec.agent)
-            throw Error("OWNING_SESSION_REQUIRED");
+            throw Error(ERRORS.OWNING_SESSION_REQUIRED);
+        const agent = exec.agent;
         const owner = {
-            sessionId: String(exec.agent.id),
+            sessionId: String(agent.id),
             callId: String(exec.callId),
-        }, m = parse(raw);
+        };
+        const m = parse(raw);
         if (m.type !== "request")
             return bus.command(owner, m);
         let projection;
-        const attached = bus.submit(owner, m, (event) => projection?.progress(event), async (input, signal) => {
+        const attached = bus.submit(owner, m, (event) => projection?.progress(event), 
+        // 宿主 read 能力：出队时重新进入宿主工具管线，沿用宿主权限与工作目录。
+        async (input, signal) => {
             const result = await ctx.tools.execute({
                 name: "read",
                 callId: (String(exec.callId) +
@@ -67,43 +72,62 @@ export function apply(ctx) {
                     randomUUID()),
                 rootCallId: exec.rootCallId,
                 parent: exec.token,
-                agent: exec.agent,
+                agent,
                 arguments: input,
                 signal,
             });
             if (result.isError)
-                throw Error("HOST_READ_FAILED");
+                throw Error(ERRORS.HOST_READ_FAILED);
             return result.value;
         });
-        // Terminal reuse is a read of an existing result, not admission of new work.
-        if (attached.accepted.payload.state !== "queued" &&
-            attached.accepted.payload.state !== "running") {
-            try {
-                const value = await attached.done;
-                attached.returned();
-                return value;
-            }
-            finally {
-                attached.detach();
-            }
+        // 1) 终态复用：已有执行直接读结果，不是新工作受理、不再申请 Job。
+        const terminal = await readTerminal(attached);
+        if (terminal)
+            return terminal;
+        // 2) 新执行：取得或创建宿主 Job 投影。
+        const execution = await projectExecution(owner, m, attached, agent.id, (handle) => (projection = handle));
+        // 3) 挂接取消生命周期，等待投影结算后返回执行快照。
+        return await awaitProjection(exec, attached, execution);
+    }
+    // —— 三个职责单一的拆分函数（闭包内共享 ctx/bus/executions） ——
+    /** accepted 已是终态时直接返回现有结果；否则返回 undefined 走新执行路径。 */
+    async function readTerminal(attached) {
+        const state = attached.accepted.payload.state;
+        if (state === "queued" || state === "running")
+            return undefined;
+        try {
+            const value = await attached.done;
+            attached.returned();
+            return value;
         }
-        const abort = () => attached.cancel();
+        finally {
+            attached.detach();
+        }
+    }
+    /** 命中已存在的共享投影则复用，否则创建投影；创建失败按 HOST_JOB_UNAVAILABLE 结算。 */
+    async function projectExecution(owner, m, attached, ownerId, onProjected) {
         const jobKey = JSON.stringify([owner.sessionId, m.requestId]);
-        let execution = executions.get(jobKey);
-        if (execution)
-            attached.detach(); // only the first attachment projects progress into the shared Job
-        if (!execution) {
-            try {
-                execution = executions.create(jobKey, ctx.jobs, exec.agent.id, attached);
-                projection = execution;
-            }
-            catch {
-                abort();
-                await attached.done;
-                attached.detach();
-                throw Error("HOST_JOB_UNAVAILABLE");
-            }
+        const existing = executions.get(jobKey);
+        if (existing) {
+            // 只让第一个附着把进度投影到共享 Job；后续附着立即解除。
+            attached.detach();
+            return existing;
+        }
+        try {
+            const created = executions.create(jobKey, ctx.jobs, ownerId, attached);
+            onProjected(created);
+            return created;
         }
+        catch {
+            attached.cancel();
+            await attached.done;
+            attached.detach();
+            throw Error(ERRORS.HOST_JOB_UNAVAILABLE);
+        }
+    }
+    /** 把宿主工具调用的取消映射到执行，并等待投影结算后返回快照。 */
+    async function awaitProjection(exec, attached, execution) {
+        const abort = () => attached.cancel();
         exec.signal.addEventListener("abort", abort, { once: true });
         if (exec.signal.aborted)
             abort();

package/dist/preset.js

@@ -4,31 +4,33 @@ import { entryListSchema } from "@deepseek-ai/cordis-plugin-include";
 import { load } from "js-yaml";
 import { setTimeout as pause } from "node:timers/promises";
 import { PRODUCT } from "./product.js";
+import { ERRORS } from "./error-codes.js";
 export const PRESET_ID = PRODUCT.presetId;
+/** 校验派生源组合：拒绝已含总线，以及缺少公开基准地址的相对模块/include 子文件。 */
+function validateDerivation(rows) {
+    for (const row of rows) {
+        if (row.id === "xiao-he-execution-bus" ||
+            row.name?.startsWith("@feng0531/dsh-execution-bus"))
+            throw Error(ERRORS.PTC_PRESET_ALREADY_CONTAINS_BUS);
+        // readDocument 不发布声明方的 baseUrl，不能把相对模块/include
+        // 静默重定位到 registrar 的不同上下文。
+        if (row.name?.startsWith(".") ||
+            row.name === "@deepseek-ai/cordis-plugin-include")
+            throw Error(ERRORS.PTC_PRESET_RELATIVE_BASE_UNSUPPORTED);
+        if (row.group && Array.isArray(row.config))
+            validateDerivation(row.config);
+    }
+}
 /** Capture the host-declared composition without evaluating !!js or changing disabled rows. */
 export function derivePreset(content) {
     if (Buffer.byteLength(content) > 1048576)
-        throw Error("PTC_PRESET_TOO_LARGE");
+        throw Error(ERRORS.PTC_PRESET_TOO_LARGE);
     const plugins = load(content, { schema: entryListSchema });
     const problem = entryListProblem(plugins);
     if (problem)
         throw Error("Invalid PTC preset: " + problem);
     const rows = plugins;
-    const inspect = (entries) => {
-        for (const row of entries) {
-            if (row.id === "xiao-he-execution-bus" ||
-                row.name?.startsWith("@feng0531/dsh-execution-bus"))
-                throw Error("PTC_PRESET_ALREADY_CONTAINS_BUS");
-            // readDocument does not publish the declaring baseUrl. Do not silently
-            // rebase relative modules/includes into the registrar's different context.
-            if (row.name?.startsWith(".") ||
-                row.name === "@deepseek-ai/cordis-plugin-include")
-                throw Error("PTC_PRESET_RELATIVE_BASE_UNSUPPORTED");
-            if (row.group && Array.isArray(row.config))
-                inspect(row.config);
-        }
-    };
-    inspect(rows);
+    validateDerivation(rows);
     return {
         id: PRESET_ID,
         name: PRODUCT.name,
@@ -68,7 +70,7 @@ export default class XiaoHePreset {
             }
         }
         if (!document)
-            throw Error("PTC_PRESET_UNAVAILABLE");
+            throw Error(ERRORS.PTC_PRESET_UNAVAILABLE);
         yield await this.ctx.agentPresets.register(derivePreset(document.content));
     }
 }

package/dist/product.d.ts

@@ -18,7 +18,7 @@ export declare const ADMISSION_DEFAULTS: Readonly<{
     sessionQueueLimit: 16;
     maxQueueWaitMs: 120000;
 }>;
-export declare const LIMITS: Readonly<{
+export declare const HANDLER_LIMITS: Readonly<{
     readLines: 100;
     readPathChars: 2048;
     diagnosticDelayMs: 30000;

package/dist/product.js

@@ -18,7 +18,7 @@ export const ADMISSION_DEFAULTS = Object.freeze({
     sessionQueueLimit: 16,
     maxQueueWaitMs: 120000,
 });
-export const LIMITS = Object.freeze({
+export const HANDLER_LIMITS = Object.freeze({
     readLines: 100,
     readPathChars: 2048,
     diagnosticDelayMs: 30000,