@botlearn-course/daemon 0.0.1 → 0.0.3

package/dist/runtimes/deepseek-tui.js

@@ -2,7 +2,10 @@ import { spawn } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import path from "node:path";
 import net from "node:net";
+import { MAX_PROGRESS_EVENTS_PER_ATTEMPT } from "../mcp/report-progress.js";
+import { runtimeChildEnv, runtimeChildIdentity } from "../runtime-env.js";
 import { readCommandVersion, resolveCommandOnPath } from "./probe.js";
+import { adaptDeepseekProgressStarted, cleanupProgressMcpConfig, createDeepseekProgressState, createProgressMcpConfig, deepseekProgressDispositions, isDeepseekProgressCompletion, progressMcpAutoInjectionSupported, progressSystemContext, } from "./progress.js";
 import { consoleLogger, wrapEngineAdapter, } from "./engine.js";
 const log = consoleLogger;
 const DEEPSEEK_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
@@ -14,6 +17,7 @@ const PROCESS_POOL = new Map();
 /** 单 daemon、单套 env 配置：池里最多一个 server。 */
 const POOL_KEY = "default";
 let exitCleanupHookInstalled = false;
+const DEEPSEEK_TURN_QUEUES = new Map();
 /**
  * daemon 退出时杀掉池中 deepseek server。池是内存态的，没有这个钩子
  * daemon 重启会留下孤儿 server。首次 spawn 时惰性安装，保持模块导入无副作用。
@@ -64,6 +68,8 @@ export class DeepseekTuiAdapter {
     explicitAuthToken;
     fetchFn;
     spawnFn;
+    progressEventMappingEnabled;
+    progressPromptInjectionEnabled;
     resolvedBinary = null;
     constructor(deps = {}) {
         this.explicitBinary = deps.binary ?? process.env.BOTLEARN_DEEPSEEK_TUI_BIN;
@@ -71,6 +77,11 @@ export class DeepseekTuiAdapter {
         this.explicitAuthToken = deps.authToken ?? process.env.BOTLEARN_DEEPSEEK_TUI_TOKEN;
         this.fetchFn = deps.fetchFn ?? fetch;
         this.spawnFn = deps.spawnFn ?? spawn;
+        this.progressPromptInjectionEnabled =
+            !this.explicitServerUrl && progressMcpAutoInjectionSupported();
+        this.progressEventMappingEnabled = this.explicitServerUrl
+            ? deps.progressEventMapping === true
+            : this.progressPromptInjectionEnabled;
     }
     async run(opts) {
         if (opts.signal.aborted) {
@@ -80,14 +91,28 @@ export class DeepseekTuiAdapter {
                 error: "deepseek-tui aborted before start",
             };
         }
-        const handle = await this.acquireHandle(opts);
-        handle.inFlight += 1;
-        if (handle.idleTimer)
-            clearTimeout(handle.idleTimer);
         const turnAbort = new AbortController();
         const onAbort = () => turnAbort.abort();
         opts.signal.addEventListener("abort", onAbort, { once: true });
+        if (opts.signal.aborted)
+            turnAbort.abort();
+        let handle;
+        let countedInFlight = false;
+        let releaseTurn;
         try {
+            // The local server has a process-level kill fallback when turn-scoped interrupt
+            // fails. Serialize turns so cancelling one run can never terminate another run.
+            const turnQueueKey = this.explicitServerUrl
+                ? `external:${trimTrailingSlash(this.explicitServerUrl)}`
+                : POOL_KEY;
+            releaseTurn = await acquireDeepseekTurn(turnQueueKey, turnAbort.signal);
+            handle = await this.acquireHandle(opts, turnAbort.signal);
+            if (turnAbort.signal.aborted)
+                throw abortReason(turnAbort.signal);
+            handle.inFlight += 1;
+            countedInFlight = true;
+            if (handle.idleTimer)
+                clearTimeout(handle.idleTimer);
             const headers = authHeaders(handle.token);
             let threadId = opts.sessionId?.trim() || "";
             if (threadId && !isValidThreadId(threadId)) {
@@ -109,12 +134,16 @@ export class DeepseekTuiAdapter {
                 threadId,
                 opts,
                 signal: turnAbort.signal,
+                handle,
             });
             const text = runResult.text;
             const error = runResult.error ?? (text === "" ? emptyCompletionError(handle.stderrTail) : undefined);
             return {
                 text,
                 newSessionId: threadId,
+                ...(runResult.progressDispositions
+                    ? { progressDispositions: runResult.progressDispositions }
+                    : {}),
                 ...(error ? { error } : {}),
             };
         }
@@ -130,9 +159,12 @@ export class DeepseekTuiAdapter {
         }
         finally {
             opts.signal.removeEventListener("abort", onAbort);
-            handle.inFlight -= 1;
-            if (!this.explicitServerUrl)
-                resetIdle(handle, POOL_KEY);
+            if (handle && countedInFlight) {
+                handle.inFlight = Math.max(0, handle.inFlight - 1);
+                if (!this.explicitServerUrl)
+                    resetIdle(handle, POOL_KEY);
+            }
+            releaseTurn?.();
         }
     }
     resolveBinary() {
@@ -143,7 +175,7 @@ export class DeepseekTuiAdapter {
         this.resolvedBinary = resolveDeepseekCommand() ?? "deepseek";
         return this.resolvedBinary;
     }
-    async acquireHandle(opts) {
+    async acquireHandle(opts, signal) {
         if (this.explicitServerUrl) {
             return {
                 child: nullChild(),
@@ -158,16 +190,38 @@ export class DeepseekTuiAdapter {
         if (existing && !existing.closed)
             return existing;
         const port = await findFreePort();
+        if (signal.aborted)
+            throw abortReason(signal);
         const token = randomToken();
         const baseUrl = `http://127.0.0.1:${port}`;
-        const child = this.spawnFn(this.resolveBinary(), ["serve", "--http", "--host", "127.0.0.1", "--port", String(port), "--auth-token", token], {
-            cwd: opts.cwd,
-            env: this.spawnEnv(),
-            stdio: ["ignore", "pipe", "pipe"],
-            // 自成进程组：解析到的二进制可能是会再 spawn 真实 deepseek-tui
-            // server 的 dispatcher，shutdown 必须对整组发信号而非仅直接子进程。
-            detached: true,
-        });
+        const progressMcpConfig = this.progressPromptInjectionEnabled
+            ? createProgressMcpConfig()
+            : undefined;
+        let child;
+        try {
+            child = this.spawnFn(this.resolveBinary(), [
+                "serve",
+                "--http",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                String(port),
+                "--auth-token",
+                token,
+            ], {
+                cwd: opts.cwd,
+                env: this.spawnEnv(opts, progressMcpConfig?.path),
+                ...runtimeChildIdentity(),
+                stdio: ["ignore", "pipe", "pipe"],
+                // 自成进程组：解析到的二进制可能是会再 spawn 真实 deepseek-tui
+                // server 的 dispatcher，shutdown 必须对整组发信号而非仅直接子进程。
+                detached: true,
+            });
+        }
+        catch (error) {
+            cleanupProgressMcpConfig(progressMcpConfig);
+            throw error;
+        }
         installExitCleanupHook();
         const handle = {
             child,
@@ -176,6 +230,7 @@ export class DeepseekTuiAdapter {
             closed: false,
             inFlight: 0,
             stderrTail: "",
+            progressMcpConfig,
         };
         child.stderr?.setEncoding("utf8");
         child.stderr?.on("data", (chunk) => {
@@ -183,13 +238,25 @@ export class DeepseekTuiAdapter {
         });
         child.on("close", () => {
             handle.closed = true;
-            PROCESS_POOL.delete(POOL_KEY);
+            if (PROCESS_POOL.get(POOL_KEY) === handle)
+                PROCESS_POOL.delete(POOL_KEY);
+            cleanupProgressMcpConfig(handle.progressMcpConfig);
+            handle.progressMcpConfig = undefined;
         });
         child.on("error", () => {
             handle.closed = true;
-            PROCESS_POOL.delete(POOL_KEY);
+            if (PROCESS_POOL.get(POOL_KEY) === handle)
+                PROCESS_POOL.delete(POOL_KEY);
+            cleanupProgressMcpConfig(handle.progressMcpConfig);
+            handle.progressMcpConfig = undefined;
         });
-        await waitForHealth(baseUrl, this.fetchFn, child, STARTUP_TIMEOUT_MS);
+        try {
+            await waitForHealth(baseUrl, this.fetchFn, child, STARTUP_TIMEOUT_MS, signal);
+        }
+        catch (error) {
+            shutdownHandle(handle, "startup-failed");
+            throw error;
+        }
         PROCESS_POOL.set(POOL_KEY, handle);
         resetIdle(handle, POOL_KEY);
         return handle;
@@ -198,12 +265,15 @@ export class DeepseekTuiAdapter {
      * 不设置 DEEPSEEK_RUNTIME_DIR：server 跨 run 池化共享，per-run 目录不成立；
      * BYOA 直接用用户本机 deepseek 自身的默认状态目录（含已登录凭据）。
      */
-    spawnEnv() {
-        return {
-            ...process.env,
+    spawnEnv(opts, progressMcpConfigPath) {
+        const env = {
+            ...runtimeChildEnv(opts.env ?? process.env),
             FORCE_COLOR: "0",
             NO_COLOR: "1",
         };
+        if (progressMcpConfigPath)
+            env.DEEPSEEK_MCP_CONFIG = progressMcpConfigPath;
+        return env;
     }
     async createThread(baseUrl, headers, opts, signal) {
         const body = {
@@ -219,8 +289,11 @@ export class DeepseekTuiAdapter {
             body.model = selection.model;
         if (selection.reasoningEffort)
             body.reasoning_effort = selection.reasoningEffort;
-        if (opts.systemContext)
-            body.system_prompt = opts.systemContext;
+        const systemContext = this.progressPromptInjectionEnabled
+            ? progressSystemContext(opts.systemContext)
+            : opts.systemContext;
+        if (systemContext)
+            body.system_prompt = systemContext;
         const res = await this.requestJson(`${baseUrl}/v1/threads`, {
             method: "POST",
             headers,
@@ -236,16 +309,37 @@ export class DeepseekTuiAdapter {
         await this.requestJson(`${baseUrl}/v1/threads/${encodeURIComponent(threadId)}`, {
             method: "PATCH",
             headers,
-            body: JSON.stringify({ system_prompt: systemContext ?? "" }),
+            body: JSON.stringify({
+                system_prompt: this.progressPromptInjectionEnabled
+                    ? progressSystemContext(systemContext)
+                    : (systemContext ?? ""),
+            }),
             signal,
         });
     }
     async startTurnAndReadEvents(args) {
-        const { baseUrl, headers, threadId, opts, signal } = args;
+        const { baseUrl, headers, threadId, opts, signal, handle } = args;
         // 事件流必须先于 turn 打开，否则 turn 早期事件会丢。
         const eventsUrl = `${baseUrl}/v1/threads/${encodeURIComponent(threadId)}/events?since_seq=0`;
         const eventsAbort = new AbortController();
-        const onAbort = () => eventsAbort.abort();
+        let turnId = "";
+        let interruptPromise;
+        const interrupt = () => {
+            if (!turnId)
+                return Promise.resolve();
+            interruptPromise ??= this.interruptTurn(baseUrl, headers, threadId, turnId).catch((error) => {
+                log.warn("deepseek-tui turn interrupt failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                if (!this.explicitServerUrl)
+                    shutdownHandle(handle, "turn-interrupt-failed");
+            });
+            return interruptPromise;
+        };
+        const onAbort = () => {
+            eventsAbort.abort();
+            void interrupt();
+        };
         signal.addEventListener("abort", onAbort, { once: true });
         let eventsError;
         const eventsReaderPromise = this.readEvents(eventsUrl, headers, opts, eventsAbort.signal).catch((err) => {
@@ -265,23 +359,44 @@ export class DeepseekTuiAdapter {
                 body.model = selection.model;
             if (selection.reasoningEffort)
                 body.reasoning_effort = selection.reasoningEffort;
+            if (signal.aborted)
+                throw abortReason(signal);
             const started = await this.requestJson(`${baseUrl}/v1/threads/${encodeURIComponent(threadId)}/turns`, {
                 method: "POST",
                 headers,
                 body: JSON.stringify(body),
-                signal,
+                // Once the request is sent, keep a short independent timeout so we can obtain
+                // turnId and explicitly interrupt it even if the outer run is cancelled.
+                signal: AbortSignal.timeout(5_000),
             });
-            const turnId = stringField(started?.turn, "id") ?? stringField(started, "turn_id") ?? "";
+            turnId = stringField(started?.turn, "id") ?? stringField(started, "turn_id") ?? "";
+            if (signal.aborted)
+                await interrupt();
             const eventsReader = await eventsReaderPromise;
             if (!eventsReader)
                 throw eventsError ?? new Error("events stream failed");
             return await eventsReader(turnId);
         }
         finally {
+            if (signal.aborted) {
+                if (turnId)
+                    await interrupt();
+                else if (!this.explicitServerUrl)
+                    shutdownHandle(handle, "cancelled-before-turn-id");
+            }
             eventsAbort.abort();
             signal.removeEventListener("abort", onAbort);
         }
     }
+    async interruptTurn(baseUrl, headers, threadId, turnId) {
+        const res = await this.fetchFn(`${baseUrl}/v1/threads/${encodeURIComponent(threadId)}/turns/${encodeURIComponent(turnId)}/interrupt`, {
+            method: "POST",
+            headers,
+            signal: AbortSignal.timeout(2_000),
+        });
+        if (!res.ok)
+            throw new Error(`interrupt failed HTTP ${res.status}`);
+    }
     async readEvents(url, headers, opts, signal) {
         const res = await this.fetchFn(url, { method: "GET", headers, signal });
         if (!res.ok)
@@ -296,6 +411,7 @@ export class DeepseekTuiAdapter {
             let text = "";
             let errorText = "";
             let capped = false;
+            const progressState = createDeepseekProgressState();
             const append = (chunk) => {
                 if (!chunk || capped)
                     return;
@@ -317,10 +433,30 @@ export class DeepseekTuiAdapter {
                 if (turnId && eventTurnId && eventTurnId !== turnId)
                     return false;
                 seq += 1;
-                const block = normalizeDeepseekEvent(eventName, payload, seq);
+                const toolStarted = eventName === "tool.started" || isToolStarted(eventName, payload);
+                const toolCompleted = eventName === "tool.completed" || isToolCompleted(eventName, payload);
+                const progressStarted = toolStarted && this.progressEventMappingEnabled
+                    ? adaptDeepseekProgressStarted(payload, seq, progressState)
+                    : { matched: false };
+                if (progressStarted.limitExceeded) {
+                    log.warn("deepseek-tui progress event limit exceeded", {
+                        limit: MAX_PROGRESS_EVENTS_PER_ATTEMPT,
+                    });
+                }
+                const suppressProgressResult = this.progressEventMappingEnabled &&
+                    toolCompleted &&
+                    isDeepseekProgressCompletion(payload, progressState);
+                const block = progressStarted.matched
+                    ? (progressStarted.block ?? null)
+                    : suppressProgressResult
+                        ? null
+                        : normalizeDeepseekEvent(eventName, payload, seq);
                 if (block)
                     opts.onBlock?.(block);
-                const extractedError = extractDeepseekError(eventName, payload);
+                // report_progress is non-authoritative telemetry: its tool failure never fails the task.
+                const extractedError = suppressProgressResult
+                    ? undefined
+                    : extractDeepseekError(eventName, payload);
                 if (extractedError)
                     errorText = extractedError;
                 if (eventName === "message.delta") {
@@ -332,7 +468,7 @@ export class DeepseekTuiAdapter {
                 if (eventName === "turn.started" || embeddedDeepseekEvent(payload) === "turn.started") {
                     opts.onStatus?.({ kind: "thinking", phase: "started", label: "Thinking" });
                 }
-                else if (eventName === "tool.started" || isToolStarted(eventName, payload)) {
+                else if (toolStarted && !progressStarted.matched) {
                     const label = stringField(payload, "name") ??
                         stringField(payload?.tool, "name") ??
                         stringField(payload?.payload?.tool, "name") ??
@@ -359,7 +495,12 @@ export class DeepseekTuiAdapter {
                         continue;
                     if (emit(frame.event, frame.data)) {
                         await reader.cancel().catch(() => undefined);
-                        return { text: text.trim(), ...(errorText ? { error: errorText } : {}) };
+                        const progressDispositions = deepseekProgressDispositions(progressState);
+                        return {
+                            text: text.trim(),
+                            ...(errorText ? { error: errorText } : {}),
+                            ...(progressDispositions ? { progressDispositions } : {}),
+                        };
                     }
                 }
             }
@@ -368,7 +509,12 @@ export class DeepseekTuiAdapter {
                 if (frame)
                     emit(frame.event, frame.data);
             }
-            return { text: text.trim(), ...(errorText ? { error: errorText } : {}) };
+            const progressDispositions = deepseekProgressDispositions(progressState);
+            return {
+                text: text.trim(),
+                ...(errorText ? { error: errorText } : {}),
+                ...(progressDispositions ? { progressDispositions } : {}),
+            };
         };
     }
     async requestJson(url, init) {
@@ -395,6 +541,7 @@ export function __resetDeepseekTuiPoolForTests() {
         shutdownHandle(handle, "test-reset");
         PROCESS_POOL.delete(key);
     }
+    DEEPSEEK_TURN_QUEUES.clear();
 }
 function normalizeDeepseekEvent(eventName, payload, seq) {
     if (eventName === "message.delta") {
@@ -490,11 +637,11 @@ function extractDeepseekError(eventName, payload) {
             stringField(payload?.payload, "message") ??
             stringField(payload?.payload, "error"));
     }
-    if (eventName === "item.failed") {
-        return (stringField(payload?.payload?.item, "detail") ??
-            stringField(payload?.payload?.item, "summary") ??
-            stringField(payload?.payload, "error"));
-    }
+    // An item failure is a tool result inside an otherwise live turn. DeepSeek may use it
+    // to correct the arguments, choose another tool, and still complete the turn. Treating
+    // its detail as a sticky runtime error would discard that recovery and fail the run
+    // even after a later assistant message or successful turn completion. Only provider
+    // errors and terminal turn failures are run-level errors here.
     if (isDeepseekTerminalEvent(eventName, payload)) {
         const turn = payload?.payload?.turn ?? payload?.turn;
         const status = stringField(turn, "status");
@@ -564,6 +711,47 @@ function nextArgValue(args, index) {
         return next;
     return /^-\d/.test(next) ? next : undefined;
 }
+async function acquireDeepseekTurn(key, signal) {
+    let released = false;
+    let releaseGate;
+    const gate = new Promise((resolve) => {
+        releaseGate = resolve;
+    });
+    const previous = DEEPSEEK_TURN_QUEUES.get(key) ?? Promise.resolve();
+    const tail = previous.then(() => gate);
+    DEEPSEEK_TURN_QUEUES.set(key, tail);
+    void tail.then(() => {
+        if (DEEPSEEK_TURN_QUEUES.get(key) === tail)
+            DEEPSEEK_TURN_QUEUES.delete(key);
+    });
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        releaseGate();
+    };
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        rejectAbort = reject;
+    });
+    const onAbort = () => rejectAbort(abortReason(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+        onAbort();
+    try {
+        await Promise.race([previous, aborted]);
+        if (signal.aborted)
+            throw abortReason(signal);
+        return release;
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+    }
+}
 function resetIdle(handle, key) {
     if (handle.idleTimer)
         clearTimeout(handle.idleTimer);
@@ -584,6 +772,8 @@ function shutdownHandle(handle, reason) {
     handle.closed = true;
     if (handle.idleTimer)
         clearTimeout(handle.idleTimer);
+    cleanupProgressMcpConfig(handle.progressMcpConfig);
+    handle.progressMcpConfig = undefined;
     try {
         const pid = handle.child.pid;
         if (typeof pid === "number" && pid > 0) {
@@ -614,20 +804,24 @@ function shutdownHandle(handle, reason) {
     }
     log.debug("deepseek-tui.shutdown", { reason });
 }
-async function waitForHealth(baseUrl, fetchFn, child, timeoutMs) {
+async function waitForHealth(baseUrl, fetchFn, child, timeoutMs, signal) {
     const deadline = Date.now() + timeoutMs;
     let lastError = "";
     while (Date.now() < deadline) {
+        if (signal.aborted)
+            throw abortReason(signal);
         if (child.exitCode !== null) {
             throw new Error(`deepseek serve exited with code ${child.exitCode}`);
         }
         try {
-            const res = await fetchFn(`${baseUrl}/health`, { method: "GET" });
+            const res = await fetchFn(`${baseUrl}/health`, { method: "GET", signal });
             if (res.ok)
                 return;
             lastError = `HTTP ${res.status}`;
         }
         catch (err) {
+            if (signal.aborted)
+                throw abortReason(signal);
             lastError = err instanceof Error ? err.message : String(err);
         }
         await sleep(STARTUP_POLL_MS);
@@ -655,6 +849,9 @@ function randomToken() {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function abortReason(signal) {
+    return signal.reason instanceof Error ? signal.reason : new Error("deepseek-tui aborted");
+}
 function stringField(obj, key) {
     const v = obj?.[key];
     return typeof v === "string" ? v : undefined;

package/dist/runtimes/engine.d.ts

@@ -1,15 +1,23 @@
-import { type CourseRuntime, type RuntimeFailureSummary } from "../types.js";
+import { type CourseRuntime, type RuntimeFailureSummary, type RuntimeProgressDispositions } from "../types.js";
 import type { Logger } from "../log.js";
+import type { ProgressReport } from "../mcp/report-progress.js";
 /**
  * 内部引擎契约：CLI/ACP 基类实现的是 pull-style options + 回调，
  * 由 wrapEngineAdapter 折叠成对外的 CourseRuntime（sink 语义）。
  */
-/** 底层 CLI 逐事件归一化出的块。seq 为本轮 1-based 单调递增。 */
-export interface StreamBlock {
+export interface ContentStreamBlock {
     raw: unknown;
     kind: "assistant_text" | "tool_use" | "tool_result" | "system" | "thinking" | "other";
     seq: number;
 }
+/** provider 已严格校验的进度块；禁止携带原始 tool envelope。 */
+export interface ProgressStreamBlock {
+    kind: "progress";
+    seq: number;
+    progress: ProgressReport;
+}
+/** 底层 CLI 逐事件归一化出的块。seq 为本轮 1-based 单调递增。 */
+export type StreamBlock = ContentStreamBlock | ProgressStreamBlock;
 export type RuntimeStatusEvent = {
     kind: "typing";
     phase: "started" | "stopped";
@@ -29,11 +37,14 @@ export interface EngineRunOptions {
     systemContext?: string;
     onBlock?: (block: StreamBlock) => void;
     onStatus?: (event: RuntimeStatusEvent) => void;
+    env?: NodeJS.ProcessEnv;
 }
 export interface EngineRunResult {
     text: string;
     newSessionId: string;
     costUsd?: number;
+    /** adapter 自身在 emit 前丢弃的进度计数；不包含 accepted，避免 dispatcher 重复计数。 */
+    progressDispositions?: RuntimeProgressDispositions;
     /** 非空表示硬失败；由包装层折叠为 RuntimeExecutionError。 */
     error?: string;
     runtimeFailure?: Partial<RuntimeFailureSummary>;

package/dist/runtimes/engine.js

@@ -100,24 +100,51 @@ export function wrapEngineAdapter(id, engine, opts) {
                 ...(model ? modelArgs(model) : []),
                 ...selectionArgs,
             ];
+            let blockChain = Promise.resolve();
+            let progressBlockFailed = false;
+            let progressBlockError;
+            const queueBlock = (block, propagateFailure = false) => {
+                blockChain = blockChain.then(() => sink.block(block)).catch((err) => {
+                    if (propagateFailure && !progressBlockFailed) {
+                        progressBlockFailed = true;
+                        progressBlockError = err;
+                    }
+                    consoleLogger.debug(`${id} sink.block failed`, { err: String(err) });
+                });
+            };
             const result = await engine.run({
                 text,
-                sessionId: null,
+                sessionId: run.nativeSessionId ?? null,
                 cwd: run.workspaceDir,
                 signal,
+                ...(run.runtimeEnv ? { env: run.runtimeEnv } : {}),
                 ...(extraArgs.length > 0 ? { extraArgs } : {}),
                 ...(systemContext !== undefined ? { systemContext } : {}),
                 onBlock: (block) => {
+                    if (block.kind === "progress") {
+                        queueBlock({
+                            kind: "progress",
+                            runtime: id,
+                            summary: block.progress.summary,
+                            status: block.progress.status,
+                        }, true);
+                        return;
+                    }
                     const kind = BLOCK_KIND_MAP[block.kind] ?? "status";
-                    // 上报失败不打断 runtime 执行。
-                    void sink.block({ kind, raw: block.raw }).catch((err) => {
-                        consoleLogger.debug(`${id} sink.block failed`, { err: String(err) });
-                    });
+                    queueBlock({ kind, raw: block.raw });
                 },
                 onStatus: (event) => {
                     consoleLogger.debug(`${id} status`, { kind: event.kind, phase: event.phase });
                 },
             });
+            // Preserve provider event order through durable run.block before the final run.message.
+            await blockChain;
+            if (progressBlockFailed)
+                throw progressBlockError;
+            if (result.progressDispositions) {
+                await sink.progressDispositions?.(result.progressDispositions);
+            }
+            await sink.runtimeSession?.(result.newSessionId);
             if (result.error) {
                 throw new RuntimeExecutionError(result.error, "runtime_error", result.runtimeFailure);
             }

package/dist/runtimes/hermes-agent.d.ts

@@ -41,7 +41,7 @@ export declare class HermesAgentAdapter extends AcpRuntimeAdapter {
      * 用户 `~/.hermes` 的 `.env` / config.yaml 里。
      */
     protected buildArgs(_opts: EngineRunOptions): string[];
-    protected spawnEnv(_opts: EngineRunOptions): NodeJS.ProcessEnv;
+    protected spawnEnv(opts: EngineRunOptions): NodeJS.ProcessEnv;
     /** spawn 前把 systemContext 原子写入 `<cwd>/AGENTS.md`（tmp 0600 + rename）。 */
     protected prepareTurn(opts: EngineRunOptions): void;
     /**

package/dist/runtimes/hermes-agent.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { AcpRuntimeAdapter, } from "./acp-stream.js";
 import { firstExistingPath, readCommandVersion, resolveCommandOnPath, resolveHomePath, } from "./probe.js";
 import { wrapEngineAdapter, } from "./engine.js";
+import { runtimeChildEnv } from "../runtime-env.js";
 /**
  * `hermes-acp` 不在 PATH 上时的已知绝对位置。上游 `scripts/install.sh`
  * （curl|bash 安装器）把私有 virtualenv 装到 `~/.hermes/hermes-agent/venv/`，
@@ -80,9 +81,9 @@ export class HermesAgentAdapter extends AcpRuntimeAdapter {
     buildArgs(_opts) {
         return [];
     }
-    spawnEnv(_opts) {
+    spawnEnv(opts) {
         return {
-            ...process.env,
+            ...runtimeChildEnv(opts.env ?? process.env),
             // 保持 ACP stdout 无 ANSI 码。
             NO_COLOR: "1",
             // 危险工具调用走 ACP request_permission。

package/dist/runtimes/ndjson-stream.d.ts

@@ -46,6 +46,6 @@ export declare abstract class NdjsonStreamAdapter implements EngineAdapter {
     protected abstract buildArgs(opts: EngineRunOptions): string[];
     protected abstract handleEvent(obj: unknown, ctx: NdjsonEventCtx): void;
     /** 覆盖以调整 env（FORCE_COLOR=0、NO_COLOR=1 等）。 */
-    protected spawnEnv(_opts: EngineRunOptions): NodeJS.ProcessEnv;
+    protected spawnEnv(opts: EngineRunOptions): NodeJS.ProcessEnv;
     run(opts: EngineRunOptions): Promise<EngineRunResult>;
 }

package/dist/runtimes/ndjson-stream.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { runtimeChildEnv, runtimeChildIdentity } from "../runtime-env.js";
 import { safeCommand, sanitizeRuntimeFailureText, tailText } from "../redaction.js";
 import { sliceUtf8Bytes, utf8ByteLength } from "./text-cap.js";
 import { consoleLogger, } from "./engine.js";
@@ -21,8 +22,8 @@ export class NdjsonStreamAdapter {
         this.log = logger ?? consoleLogger;
     }
     /** 覆盖以调整 env（FORCE_COLOR=0、NO_COLOR=1 等）。 */
-    spawnEnv(_opts) {
-        return { ...process.env };
+    spawnEnv(opts) {
+        return runtimeChildEnv(opts.env ?? process.env);
     }
     async run(opts) {
         if (opts.signal.aborted) {
@@ -43,6 +44,7 @@ export class NdjsonStreamAdapter {
         const child = spawn(binary, args, {
             cwd: opts.cwd,
             env: this.spawnEnv(opts),
+            ...runtimeChildIdentity(),
             stdio: ["ignore", "pipe", "pipe"],
         });
         // spawn 是同步的，但若在 spawn 与稍后挂监听之间发生 abort 会被漏掉，