@feng0531/dsh-execution-bus 0.12.1 → 1.0.0

package/dist/product.js

@@ -1,165 +1,85 @@
-/** Stable product identities and policy. Historical IDs are compatibility contracts, not display names. */
+/** Stable product identities and model-visible runtime policy. */
 export const PRODUCT = Object.freeze({
     name: "萧何 / Xiao He",
     packageName: "@feng0531/dsh-execution-bus",
-    presetId: "execution-bus-test",
-    presetRowId: "preset-execution-bus-test",
+    presetId: "xiao-he-runtime",
+    presetRowId: "preset-xiao-he-runtime",
     modeEntry: "@feng0531/dsh-execution-bus/mode",
-    modePluginName: "execution-bus-mode",
+    modePluginName: "xiao-he-runtime-mode",
 });
-export const CORE_DEFAULTS = Object.freeze({
-    concurrency: 2,
-    queueLimit: 32,
-    recordLimit: 256,
-    resultBytes: 65536,
-    retentionMs: 3600000,
-});
-export const ADMISSION_DEFAULTS = Object.freeze({
-    sessionQueueLimit: 16,
-    maxQueueWaitMs: 120000,
-});
-export const HANDLER_LIMITS = Object.freeze({
-    readLines: 100,
-    readPathChars: 2048,
-    diagnosticDelayMs: 30000,
-});
-/** 调度策略：类别优先级 + 等待老化 + 长任务诊断阈值。 */
-export const SCHEDULER_POLICY = Object.freeze({
-    longRunningMs: 30000,
-    queueAgingMs: 30000,
-    queueClassOrder: Object.freeze({
-        fs: 0,
-        diagnostic: 1,
-        command: 2,
-        default: 3,
-    }),
-});
-/** 每个 Handler 的模型可见输入声明。只用于工具 schema/SDK 生成；运行时仍由 Handler.validate 严格校验。 */
-const INPUT_SCHEMAS = {
-    test: {
-        type: "object",
-        additionalProperties: false,
-        required: ["delayMs", "fail"],
-        properties: {
-            delayMs: { type: "integer", description: "Diagnostic delay in milliseconds (0-30000)." },
-            fail: { type: "boolean", description: "Settle as a controlled failure when true." },
-        },
-    },
-    "host.read": {
-        type: "object",
-        additionalProperties: false,
-        required: ["file_path"],
-        properties: {
-            file_path: { type: "string", description: "Path resolved against the session working directory." },
-            offset: { type: "integer", description: "1-based first line to read." },
-            limit: { type: "integer", description: "Maximum lines to read (<=100)." },
-        },
-    },
-    "host.glob": {
-        type: "object",
-        additionalProperties: false,
-        required: ["pattern"],
-        properties: {
-            pattern: { type: "string", description: "Glob pattern; a bare pattern matches basenames at any depth." },
-            path: { type: "string", description: "Directory to search; defaults to the session working directory." },
-        },
-    },
-    "host.grep": {
-        type: "object",
-        additionalProperties: false,
-        required: ["pattern"],
-        properties: {
-            pattern: { type: "string", description: "Ripgrep regular expression." },
-            path: { type: "string", description: "File or directory to search; defaults to the session working directory." },
-            include: { type: "string", description: "One positive glob filter; negation and comma lists are rejected." },
-        },
-    },
-    "host.edit": {
-        type: "object",
-        additionalProperties: false,
-        required: ["file_path", "old_string", "new_string"],
-        properties: {
-            file_path: { type: "string", description: "File to edit." },
-            old_string: { type: "string", description: "Literal text to replace." },
-            new_string: { type: "string", description: "Replacement text." },
-            replace_all: { type: "boolean", description: "Replace every occurrence." },
+const RUNTIME_STEP_SCHEMA = {
+    type: "object",
+    properties: {
+        id: { type: "string", description: "步骤唯一 ID（字母开头，可含字母/数字/_-）" },
+        tool: {
+            type: "string",
+            enum: ["read", "glob", "grep", "edit", "write", "pwsh"],
+            description: "允许的宿主工具",
         },
-    },
-    "host.write": {
-        type: "object",
-        additionalProperties: false,
-        required: ["file_path", "content"],
-        properties: {
-            file_path: { type: "string", description: "File to write." },
-            content: { type: "string", description: "Full file content." },
+        input: { type: "object", description: "宿主工具参数，按工具 schema 校验" },
+        depends_on: {
+            type: "array",
+            items: { type: "string" },
+            description: "依赖步骤 ID；全部成功后本步骤才执行",
         },
-    },
-    "host.pwsh": {
-        type: "object",
-        additionalProperties: false,
-        required: ["description", "command"],
-        properties: {
-            description: { type: "string", description: "Clear, concise description of what the command does (shown in the UI)." },
-            command: { type: "string", description: "PowerShell command to execute." },
-            timeoutMs: { type: "number", description: "Positive timeout in milliseconds." },
-            workdir: { type: "string", description: "Working directory; defaults to the session working directory." },
-            run_in_background: { type: "boolean", description: "Return a host Job id immediately instead of waiting." },
-            sandbox_permissions: { type: "string", enum: ["workspace-write", "danger-full-access"], description: "Narrowest wider sandbox mode; must be paired with justification." },
-            justification: { type: "string", description: "Required with sandbox_permissions; one sentence of reason." },
+        retry: {
+            type: "integer",
+            minimum: 0,
+            maximum: 3,
+            description: "仅幂等工具 read/glob/grep 允许 >0；重试次数不含首次",
         },
+        timeout_ms: { type: "integer", minimum: 1000, maximum: 600000 },
     },
+    required: ["id", "tool", "input"],
+    additionalProperties: false,
 };
-/** Handler 名列表同时决定 request payload 的联合分支顺序。 */
-const HANDLER_NAMES = [
-    "host.read",
-    "host.glob",
-    "host.grep",
-    "host.edit",
-    "host.write",
-    "host.pwsh",
-    "test",
-];
-/** 简化调用（0.11.0）：{requestId, handler, input} 或 {requestId, type}；
- *  完整 v1 消息仍被运行时接受，但不再进入模型可见 schema。 */
-const REQUEST_ID_PROP = { type: "string" };
-const MESSAGE_ID_PROP = { type: "string" };
-export const REQUEST_PARAMETERS = {
-    oneOf: [
-        ...HANDLER_NAMES.map((handler) => ({
-            type: "object",
-            additionalProperties: false,
-            required: ["requestId", "handler", "input"],
-            properties: {
-                requestId: REQUEST_ID_PROP,
-                messageId: MESSAGE_ID_PROP,
-                handler: { type: "string", const: handler },
-                input: INPUT_SCHEMAS[handler],
-            },
-        })),
-        {
+export const RUNTIME_RUN_PARAMETERS = {
+    type: "object",
+    properties: {
+        plan: {
             type: "object",
-            additionalProperties: false,
-            required: ["requestId", "type"],
             properties: {
-                requestId: REQUEST_ID_PROP,
-                messageId: MESSAGE_ID_PROP,
-                type: {
-                    type: "string",
-                    enum: ["status", "result", "cancel"],
-                    description: "Read the saved snapshot or request cancellation for this requestId.",
+                goal: { type: "string", maxLength: 500 },
+                concurrency: { type: "integer", minimum: 1, maximum: 4 },
+                steps: {
+                    type: "array",
+                    items: RUNTIME_STEP_SCHEMA,
+                    minItems: 1,
+                    maxItems: 32,
                 },
             },
+            required: ["steps"],
+            additionalProperties: false,
+        },
+        async: {
+            type: "boolean",
+            description: "true 时立即返回 runId，用 runtime_status/runtime_result 取回",
         },
-    ],
+    },
+    required: ["plan"],
+    additionalProperties: false,
+};
+export const RUNTIME_RUN_ID_PARAMETERS = {
+    type: "object",
+    properties: {
+        runId: { type: "string", description: "runtime_run 返回的运行 ID" },
+    },
+    required: ["runId"],
+    additionalProperties: false,
 };
-export const STATE_PARAMETERS = {
+export const RUNTIME_STATUS_PARAMETERS = {
     type: "object",
-    properties: {},
+    properties: {
+        runId: {
+            type: "string",
+            description: "可选：指定运行 ID；省略时列出最近运行",
+        },
+    },
     additionalProperties: false,
 };
-export const REQUEST_DESCRIPTION = "萧何 / Xiao He. Submit a request and WAIT for its terminal snapshot; the simplified call takes {requestId, handler, input} (messageId optional) and control calls take {requestId, type:\"status\"|\"result\"|\"cancel\"}. Use only when coordination helps: the same logical operation may be retried or deduplicated (reuse requestId), work must outlive a run_code budget end, or multiple steps must await one execution. Duration alone is not a reason — for a one-off long command use the original tool or its background Job. A PTC program end only stops waiting: accepted work continues and the same requestId can be retrieved with type:\"result\" or cancelled. Do not poll status inside the same run_code program as an unfinished request: end that program and retrieve in a later step. The snapshot may contain reused:true when this call attached to an existing execution. The full v1 envelope is still accepted. Diagnostic handler only: test {delayMs:0..30000,fail:boolean}; never use it for real work. Acceptance is volatile, not success. No polling or restart resume.";
-export const MODE_INSTRUCTIONS = "你正在萧何模式中。这不是角色扮演。保留宿主 PTC 的日常工具能力与权限规则。普通编辑、搜索、命令、安装和其他工作使用原工具，不要声称此模式只读。execution_bus 只在能获得协调收益时使用：① 同一逻辑操作可能重复提交或需要重试核对（沿用同一 requestId，只执行一次）；② 任务需要在 run_code 时间预算结束后继续或跨步骤取回；③ 多个步骤/等待者需要同一执行结果。仅\"操作耗时长\"不是理由：一次性长命令用原工具或宿主后台 Job。其余普通任务直接用原工具，不要为简单调用增加包装。实际业务 Handler 为 host.read、host.glob、host.grep（只读，可复用终态结果）与 host.edit、host.write、host.pwsh（有副作用，终态结果不可复用）；test 仅用于用户明确要求的诊断，不做真实工作。简化调用示例：await tools.execution_bus({requestId:\"<逻辑操作编号>\", handler:\"host.pwsh\", input:{description:\"运行测试\", command:\"pnpm test\", timeoutMs:120000}})；预算中断后用 await tools.execution_bus({requestId:\"<同一编号>\", type:\"result\"}) 取回；同一逻辑操作重发沿用 requestId，messageId 可省略（自动生成）。返回快照出现 reused:true 表示本次调用复用了已有执行。注意：同一 run_code 程序内，未完成的 request 会阻塞后发工具调用的结果提交；跨步骤取回请让启动步骤尽早结束程序，下一步再用同一 requestId 的 status/result 或重发 request；不要在同一程序里对未完成请求轮询状态。通过 run_code 调用，受原有时间预算约束。每会话排队上限 " +
-    ADMISSION_DEFAULTS.sessionQueueLimit +
-    "，排队超过 " +
-    ADMISSION_DEFAULTS.maxQueueWaitMs / 1000 +
-    " 秒且未执行会返回 QUEUE_WAIT_TIMEOUT，不自动重试。execution_bus_state 只用于用户明确诊断本会话元数据，不循环查询。请求只提交一次并等待结果，同一逻辑操作重发沿用 requestId。PTC 程序结束或 run_code 时间预算到期时，已受理请求只停止等待、继续执行；用同一 requestId 的 status/result 取回，或用 cancel 取消；用户/会话中断仍会请求取消执行。cancelRequested 不等于已取消，unknown 不代表执行失败，不承诺跨重启恢复。后台命令返回 Job ID 不代表已经完成。";
+export const RUNTIME_RUN_DESCRIPTION = "萧何声明式运行时：提交 DAG 计划（steps：id/tool/input/depends_on/retry/timeout_ms），由程序按依赖并行执行、对只读步骤重试、逐步落盘。默认等待完成返回步骤状态；async:true 立即返回 runId，用 runtime_status/runtime_result 取回，runtime_cancel 取消。仅允许 read/glob/grep/edit/write/pwsh；副作用步骤不重试、崩溃后在途步骤标记 unknown（不做 exactly-once 回滚）。简单一次调用请直接用原工具。";
+export const RUNTIME_STATUS_DESCRIPTION = "读取本会话的运行元数据：不带 runId 列出最近运行，带 runId 返回指定运行与步骤状态（不含结果）。不要轮询正在等待的 runtime_run。";
+export const RUNTIME_RESULT_DESCRIPTION = "读取指定运行已保存的步骤结果（单步结果超过 64KiB 时只返回 truncated/bytes 标记）。";
+export const RUNTIME_CANCEL_DESCRIPTION = "请求取消指定运行：停止调度、向后发步骤传播取消；已开始的副作用步骤状态可能为 unknown。";
+export const RUNTIME_RESUME_DESCRIPTION = "恢复 interrupted 运行：只读步骤重新排队，副作用在途步骤标记 failed（RUNTIME_INTERRUPTED）；不自动执行，需显式调用。";
+export const RUNTIME_INSTRUCTIONS = "萧何声明式运行时：当任务能写成稳定的 DAG（读取/搜索/编辑/写入/命令，步骤间有明确依赖）时，用 runtime_run 提交计划，而不是在 run_code 里写循环或反复等待。独立步骤会并行；只读步骤可 retry；运行记录落盘，可用 runtime_status/runtime_result/runtime_cancel/runtime_resume。副作用步骤不重试、崩溃后在途步骤可能 unknown，不保证 exactly-once；简单一次性操作仍用原工具或宿主后台 Job，不要为包装而包装。";

package/dist/runtime/executor.d.ts

@@ -0,0 +1,18 @@
+import type { Plan } from "./plan.js";
+import type { RunRecord } from "./store.js";
+import type { RunStore } from "./store.js";
+export type Invoke = (tool: string, input: Record<string, unknown>, signal: AbortSignal) => Promise<unknown>;
+/** 按 DAG 执行声明式计划：独立步骤并行、幂等步骤可重试、逐步落盘、可取消/恢复。 */
+export declare class RuntimeExecutor {
+    private readonly store;
+    private readonly invoke;
+    constructor(store: RunStore, invoke: Invoke);
+    createRun(ownerSessionId: string, plan: Plan): RunRecord;
+    execute(run: RunRecord, signal?: AbortSignal): Promise<RunRecord>;
+    /** 只恢复 interrupted 运行：幂等步骤重排，副作用步骤保持 unknown/failed。 */
+    resume(run: RunRecord, signal?: AbortSignal): Promise<RunRecord>;
+    cancel(run: RunRecord, reason?: "RUNTIME_CANCELLED"): void;
+    private spec;
+    private runStep;
+    private touch;
+}

package/dist/runtime/executor.js

@@ -0,0 +1,239 @@
+import { ERRORS } from "../error-codes.js";
+import { IDEMPOTENT_TOOLS, RUNTIME_LIMITS } from "./plan.js";
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** 按 DAG 执行声明式计划：独立步骤并行、幂等步骤可重试、逐步落盘、可取消/恢复。 */
+export class RuntimeExecutor {
+    store;
+    invoke;
+    constructor(store, invoke) {
+        this.store = store;
+        this.invoke = invoke;
+    }
+    createRun(ownerSessionId, plan) {
+        const now = Date.now();
+        const runId = "run-" +
+            now.toString(36) +
+            "-" +
+            Math.random().toString(36).slice(2, 10);
+        const run = {
+            version: 1,
+            runId,
+            ownerSessionId,
+            ...(plan.goal === undefined ? {} : { goal: plan.goal }),
+            plan,
+            state: "running",
+            steps: plan.steps.map((step) => ({
+                id: step.id,
+                tool: step.tool,
+                state: "pending",
+                attempts: 0,
+            })),
+            results: {},
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.store.save(run);
+        return run;
+    }
+    async execute(run, signal) {
+        if (run.state === "succeeded" || run.state === "failed" || run.state === "cancelled")
+            return run;
+        run.state = "running";
+        run.error = undefined;
+        run.finishedAt = undefined;
+        this.touch(run);
+        this.store.save(run);
+        while (true) {
+            if (signal?.aborted) {
+                this.cancel(run);
+                return run;
+            }
+            const pending = run.steps.filter((step) => step.state === "pending");
+            if (pending.length === 0)
+                break;
+            const done = new Set(run.steps.filter((step) => step.state === "succeeded").map((step) => step.id));
+            const ready = pending.filter((record) => {
+                const spec = this.spec(run, record.id);
+                return spec !== undefined && spec.dependsOn.every((dep) => done.has(dep));
+            });
+            if (ready.length === 0) {
+                run.state = "failed";
+                run.error = ERRORS.RUNTIME_INVALID_STATE;
+                break;
+            }
+            const batch = ready.slice(0, run.plan.concurrency);
+            for (const record of batch) {
+                record.state = "running";
+                record.startedAt = Date.now();
+                record.attempts++;
+            }
+            this.touch(run);
+            this.store.save(run);
+            await Promise.allSettled(batch.map((record) => this.runStep(run, record, signal)));
+            this.touch(run);
+            this.store.save(run);
+            const failedStep = batch.find((record) => record.state === "failed");
+            if (failedStep) {
+                run.state = "failed";
+                run.error = failedStep.error ?? ERRORS.RUNTIME_STEP_FAILED;
+                break;
+            }
+            if (batch.some((record) => record.state === "unknown" || record.state === "cancelled")) {
+                run.state = "cancelled";
+                break;
+            }
+        }
+        if (run.state === "running") {
+            const failed = run.steps.find((step) => step.state === "failed");
+            if (failed) {
+                run.state = "failed";
+                run.error = failed.error ?? ERRORS.RUNTIME_STEP_FAILED;
+            }
+            else if (run.steps.some((step) => step.state === "unknown")) {
+                run.state = "cancelled";
+            }
+            else {
+                run.state = "succeeded";
+            }
+        }
+        run.finishedAt = Date.now();
+        this.touch(run);
+        this.store.save(run);
+        return run;
+    }
+    /** 只恢复 interrupted 运行：幂等步骤重排，副作用步骤保持 unknown/failed。 */
+    async resume(run, signal) {
+        if (run.state !== "interrupted")
+            throw Error(ERRORS.RUNTIME_INVALID_STATE);
+        for (const record of run.steps) {
+            if (record.state !== "running" && record.state !== "unknown")
+                continue;
+            const spec = this.spec(run, record.id);
+            if (spec && IDEMPOTENT_TOOLS.has(spec.tool)) {
+                record.state = "pending";
+                record.error = undefined;
+            }
+            else {
+                record.state = "failed";
+                record.error = ERRORS.RUNTIME_INTERRUPTED;
+            }
+        }
+        run.state = "running";
+        run.error = undefined;
+        run.finishedAt = undefined;
+        this.touch(run);
+        this.store.save(run);
+        return this.execute(run, signal);
+    }
+    cancel(run, reason = ERRORS.RUNTIME_CANCELLED) {
+        if (run.state === "succeeded" ||
+            run.state === "failed" ||
+            run.state === "cancelled")
+            return;
+        run.state = "cancelled";
+        run.error = reason;
+        run.finishedAt = Date.now();
+        for (const record of run.steps) {
+            if (record.state === "pending") {
+                record.state = "cancelled";
+                record.error = reason;
+                record.finishedAt = Date.now();
+            }
+            else if (record.state === "running") {
+                record.state = "unknown";
+                record.error = reason;
+                record.finishedAt = Date.now();
+            }
+        }
+        this.touch(run);
+        this.store.save(run);
+    }
+    spec(run, id) {
+        return run.plan.steps.find((step) => step.id === id);
+    }
+    async runStep(run, record, runSignal) {
+        const spec = this.spec(run, record.id);
+        if (!spec) {
+            record.state = "failed";
+            record.error = ERRORS.RUNTIME_INVALID_STATE;
+            record.finishedAt = Date.now();
+            return;
+        }
+        const attemptsAllowed = spec.retry + 1;
+        for (let attempt = 1; attempt <= attemptsAllowed; attempt++) {
+            if (runSignal?.aborted) {
+                record.state = IDEMPOTENT_TOOLS.has(spec.tool) ? "cancelled" : "unknown";
+                record.error = ERRORS.RUNTIME_CANCELLED;
+                record.finishedAt = Date.now();
+                return;
+            }
+            const controller = new AbortController();
+            const onAbort = () => controller.abort();
+            runSignal?.addEventListener("abort", onAbort, { once: true });
+            let timer;
+            try {
+                const timeout = new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        controller.abort();
+                        reject(Error(ERRORS.RUNTIME_STEP_TIMEOUT));
+                    }, spec.timeoutMs);
+                });
+                const value = await Promise.race([
+                    this.invoke(spec.tool, spec.input, controller.signal),
+                    timeout,
+                ]);
+                record.state = "succeeded";
+                record.error = undefined;
+                record.finishedAt = Date.now();
+                run.results[spec.id] = boundedResult(value);
+                return;
+            }
+            catch (error) {
+                const aborted = runSignal?.aborted === true;
+                const message = error instanceof Error ? error.message : "";
+                record.error = aborted
+                    ? ERRORS.RUNTIME_CANCELLED
+                    : message === ERRORS.RUNTIME_STEP_TIMEOUT
+                        ? ERRORS.RUNTIME_STEP_TIMEOUT
+                        : ERRORS.RUNTIME_STEP_FAILED;
+                if (aborted) {
+                    record.state = IDEMPOTENT_TOOLS.has(spec.tool)
+                        ? "cancelled"
+                        : "unknown";
+                    record.finishedAt = Date.now();
+                    return;
+                }
+                if (attempt < attemptsAllowed) {
+                    record.attempts++;
+                    await delay(100 * attempt);
+                    continue;
+                }
+                record.state = "failed";
+                record.finishedAt = Date.now();
+                return;
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                runSignal?.removeEventListener("abort", onAbort);
+            }
+        }
+    }
+    touch(run) {
+        run.updatedAt = Date.now();
+    }
+}
+function boundedResult(value) {
+    try {
+        const json = JSON.stringify(value);
+        if (json === undefined)
+            return { value: null, bytes: 0 };
+        const bytes = Buffer.byteLength(json);
+        if (bytes > RUNTIME_LIMITS.resultBytes)
+            return { truncated: true, bytes };
+        return { value: JSON.parse(json), bytes };
+    }
+    catch {
+        return { truncated: true };
+    }
+}

package/dist/runtime/plan.d.ts

@@ -0,0 +1,30 @@
+/** 声明式运行时只允许调用这些宿主工具；新增工具需同时更新幂等性判断。 */
+export declare const RUNTIME_TOOLS: readonly ["read", "glob", "grep", "edit", "write", "pwsh"];
+export type RuntimeTool = (typeof RUNTIME_TOOLS)[number];
+export declare const IDEMPOTENT_TOOLS: ReadonlySet<string>;
+export interface PlanStep {
+    id: string;
+    tool: RuntimeTool;
+    input: Record<string, unknown>;
+    dependsOn: string[];
+    /** 仅幂等工具允许 >0；重试次数（不含首次）。 */
+    retry: number;
+    timeoutMs: number;
+}
+export interface Plan {
+    goal?: string;
+    steps: PlanStep[];
+    concurrency: number;
+}
+export declare const RUNTIME_LIMITS: Readonly<{
+    steps: 32;
+    planBytes: number;
+    idChars: 64;
+    retry: 3;
+    timeoutMinMs: 1000;
+    timeoutMaxMs: 600000;
+    concurrencyMax: 4;
+    goalChars: 500;
+    resultBytes: number;
+}>;
+export declare function parsePlan(raw: unknown): Plan;