@actiondock/core 2.5.1 → 2.7.0

package/dist/target/remote-errors.js

@@ -0,0 +1,51 @@
+/**
+ * 远端通信错误翻译层。
+ *
+ * 职责单一：将 profile/client 传输层抛出的底层异常翻译为统一的
+ * TargetError 结构化异常，供 RemoteActionDockTarget 各操作边界复用；
+ * 优先读取传输层透传的结构化错误码，无法识别时原样透传。
+ */
+import { STATE_KEY_NOT_FOUND } from "../errors.js";
+import { TARGET_CAPABILITY_UNAVAILABLE, TARGET_PROTOCOL_UNSUPPORTED, TARGET_RESULT_UNKNOWN, TargetError, } from "./types.js";
+/**
+ * 将远端通信异常包装翻译为统一的 TargetError。
+ *
+ * 无法识别的异常按防御与透明原则原样抛出，严禁静默吞没。
+ */
+export function wrapRemoteError(err) {
+    const msg = String(err?.message || "");
+    const code = err?.code || "";
+    if (code === "CAPABILITY_UNAVAILABLE" ||
+        code === "TARGET_CAPABILITY_UNAVAILABLE" ||
+        msg.includes("CAPABILITY_UNAVAILABLE") ||
+        msg.includes("TARGET_CAPABILITY_UNAVAILABLE") ||
+        msg.includes("Management APIs are not enabled")) {
+        throw new TargetError(TARGET_CAPABILITY_UNAVAILABLE, `TARGET_CAPABILITY_UNAVAILABLE: Management APIs are not enabled on remote target`, { originalMessage: msg });
+    }
+    if (code === "PROTOCOL_UNSUPPORTED" ||
+        code === "TARGET_PROTOCOL_UNSUPPORTED" ||
+        msg.includes("PROTOCOL_UNSUPPORTED") ||
+        msg.includes("TARGET_PROTOCOL_UNSUPPORTED")) {
+        throw new TargetError(TARGET_PROTOCOL_UNSUPPORTED, `TARGET_PROTOCOL_UNSUPPORTED: ${msg}`, { originalMessage: msg });
+    }
+    if (code === "TARGET_RESULT_UNKNOWN" ||
+        code === "RESULT_UNKNOWN" ||
+        msg.includes("TARGET_RESULT_UNKNOWN")) {
+        throw new TargetError(TARGET_RESULT_UNKNOWN, `TARGET_RESULT_UNKNOWN: ${msg}`, { originalMessage: msg });
+    }
+    throw err;
+}
+/**
+ * 判定远端状态键访问异常是否为键不存在。
+ *
+ * 优先读取传输层透传的结构化错误码（fetchRemoteJson 会将响应体 error.code
+ * 附加到抛出异常的 code 字段），仅当旧版服务器未透传 code 时回退到
+ * HTTP 状态与消息文本兼容嗅探。
+ */
+export function isRemoteStateKeyNotFound(err) {
+    if (err?.code === STATE_KEY_NOT_FOUND) {
+        return true;
+    }
+    const msg = String(err?.message || "");
+    return err?.status === 404 || msg.includes("404") || msg.includes("not found");
+}

package/dist/target/remote-polling.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 远端运行轮询兜底。
+ *
+ * 职责单一：SSE 事件流不可用或超时预算仍有剩余时，按指数退避轮询远端
+ * 运行详情直至终态、取消或超时上限；并将终态运行记录翻译为统一
+ * ExecutionResult 结构。不感知 SSE 通道与门面生命周期。
+ */
+import type { ExecutionResult, RunRecord } from "@actiondock/sdk";
+/**
+ * 轮询依赖上下文：由 RemoteActionDockTarget 门面注入自身能力，
+ * 保持本模块与门面实现解耦（子模块不得反向依赖 remote.ts）。
+ */
+export interface RunPollingContext {
+    /** 轮询等待基准底线超时时间（毫秒，默认 60000ms） */
+    baseTimeoutMs: number;
+    /** 目标是否已关闭 */
+    isClosed(): boolean;
+    /** 查询远端运行详情（键不存在时返回 undefined） */
+    getRun(runId: string): Promise<RunRecord | undefined>;
+}
+/**
+ * 将终态运行记录翻译为统一 ExecutionResult 结构。
+ */
+export declare function formatTerminalRunResult(run: RunRecord, runId: string): ExecutionResult;
+/**
+ * 指数退避轮询远端运行详情直至终态、取消或超时上限。
+ *
+ * @param ctx 门面注入的依赖上下文
+ * @param runId 运行标识
+ * @param signal 外部取消信号
+ * @param timeoutMs 运行自身声明的超时（未提供总上限时参与计算等待上限）
+ * @param startTime 等待起点时间戳（缺省当前时间）
+ * @param totalMaxWaitMs 已消耗等待预算对应的总上限（SSE 阶段已等待时传入）
+ */
+export declare function pollRunCompletion(ctx: RunPollingContext, runId: string, signal?: AbortSignal, timeoutMs?: number, startTime?: number, totalMaxWaitMs?: number): Promise<ExecutionResult>;

package/dist/target/remote-polling.js

@@ -0,0 +1,104 @@
+/**
+ * 远端运行轮询兜底。
+ *
+ * 职责单一：SSE 事件流不可用或超时预算仍有剩余时，按指数退避轮询远端
+ * 运行详情直至终态、取消或超时上限；并将终态运行记录翻译为统一
+ * ExecutionResult 结构。不感知 SSE 通道与门面生命周期。
+ */
+import { ACTION_CANCELLED, EXECUTION_FAILED, TIMEOUT } from "../errors.js";
+import { isTerminalRunStatus } from "../storage/types.js";
+import { TARGET_CLOSED } from "./types.js";
+/**
+ * 将终态运行记录翻译为统一 ExecutionResult 结构。
+ */
+export function formatTerminalRunResult(run, runId) {
+    if (run.status === "success") {
+        return { ok: true, runId, data: run.output ?? null };
+    }
+    if (run.status === "interrupted") {
+        return {
+            ok: false,
+            runId,
+            error: run.error || {
+                code: "RUN_INTERRUPTED",
+                message: `Run '${runId}' was interrupted`,
+            },
+        };
+    }
+    return {
+        ok: false,
+        runId,
+        error: run.error || {
+            code: EXECUTION_FAILED,
+            message: `Run finished with status ${run.status}`,
+        },
+    };
+}
+/**
+ * 指数退避轮询远端运行详情直至终态、取消或超时上限。
+ *
+ * @param ctx 门面注入的依赖上下文
+ * @param runId 运行标识
+ * @param signal 外部取消信号
+ * @param timeoutMs 运行自身声明的超时（未提供总上限时参与计算等待上限）
+ * @param startTime 等待起点时间戳（缺省当前时间）
+ * @param totalMaxWaitMs 已消耗等待预算对应的总上限（SSE 阶段已等待时传入）
+ */
+export async function pollRunCompletion(ctx, runId, signal, timeoutMs, startTime = Date.now(), totalMaxWaitMs) {
+    const maxWaitMs = totalMaxWaitMs ?? Math.max(ctx.baseTimeoutMs, timeoutMs ?? 0);
+    const remainingWaitMs = Math.max(0, maxWaitMs - (Date.now() - startTime));
+    let delayMs = Math.min(150, Math.max(10, Math.floor((remainingWaitMs || maxWaitMs) / 4)));
+    const maxDelayMs = 2000;
+    while (Date.now() - startTime < maxWaitMs) {
+        if (ctx.isClosed()) {
+            return {
+                ok: false,
+                runId,
+                error: {
+                    code: TARGET_CLOSED,
+                    message: "RemoteActionDockTarget is closed",
+                },
+            };
+        }
+        if (signal?.aborted) {
+            return {
+                ok: false,
+                runId,
+                error: {
+                    code: ACTION_CANCELLED,
+                    message: "Action execution was cancelled",
+                },
+            };
+        }
+        try {
+            const run = await ctx.getRun(runId);
+            if (run && isTerminalRunStatus(run.status)) {
+                return formatTerminalRunResult(run, runId);
+            }
+        }
+        catch (err) {
+            if (err?.code === TARGET_CLOSED || ctx.isClosed()) {
+                return {
+                    ok: false,
+                    runId,
+                    error: {
+                        code: TARGET_CLOSED,
+                        message: "RemoteActionDockTarget is closed",
+                    },
+                };
+            }
+            throw err;
+        }
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        delayMs = Math.min(delayMs * 2, maxDelayMs);
+    }
+    const waitedMs = Date.now() - startTime;
+    return {
+        ok: false,
+        runId,
+        error: {
+            code: TIMEOUT,
+            message: `Timed out waiting for run '${runId}' completion after ${waitedMs}ms`,
+        },
+    };
+}

package/dist/target/remote.d.ts

@@ -5,6 +5,10 @@ import { type StateEntry } from "../storage/types.js";
 import { type ActionDockTarget, type ConfigValueView, type ListRunsOptions, type RemoteTargetOptions, type StateScopeOptions, type TargetInfo } from "./types.js";
 /**
  * 读取并解析远端 SSE 事件流。
+ *
+ * 候选路由依次尝试：v2 /events -> v2 /stream -> v1 /stream；
+ * 全部候选均不可用（网络异常或非流式响应）时抛出携带各候选 URL 与
+ * 失败原因的 REMOTE_STREAM_UNAVAILABLE 聚合错误，严禁以空流伪装正常。
  */
 export declare function streamRemoteEvents(serverUrl: string, runId: string, token?: string, options?: {
     after?: number | string;

package/dist/target/remote.js

@@ -2,11 +2,19 @@ import { ActionResolver } from "../catalog/action-resolver.js";
 import { cancelRemoteRun, clearRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, assertSecureTransport, } from "../profile/client.js";
 import { normalizeServerUrl } from "../profile/manager.js";
 import { isTerminalRunStatus } from "../storage/types.js";
-import { ACTIONDOCK_PROTOCOL_VERSION, TargetError, TARGET_PROTOCOL_UNSUPPORTED, TARGET_CAPABILITY_UNAVAILABLE, TARGET_RESULT_UNKNOWN, TARGET_CLOSED, } from "./types.js";
-import { ACTION_CANCELLED, EXECUTION_FAILED, STATE_KEY_NOT_FOUND, TIMEOUT } from "../errors.js";
+import { ACTIONDOCK_PROTOCOL_VERSION, TargetError, TARGET_PROTOCOL_UNSUPPORTED, TARGET_CAPABILITY_UNAVAILABLE, TARGET_CLOSED, } from "./types.js";
+import { ACTION_CANCELLED, REMOTE_STREAM_UNAVAILABLE, TIMEOUT } from "../errors.js";
 import { getInsecureDispatcher } from "../server/dispatcher.js";
+import { listProtocolRouteCandidates } from "../profile/client.js";
+import { isRemoteStateKeyNotFound, wrapRemoteError } from "./remote-errors.js";
+import { formatTerminalRunResult, pollRunCompletion } from "./remote-polling.js";
+import { parseSseMessages } from "./sse-parser.js";
 /**
  * 读取并解析远端 SSE 事件流。
+ *
+ * 候选路由依次尝试：v2 /events -> v2 /stream -> v1 /stream；
+ * 全部候选均不可用（网络异常或非流式响应）时抛出携带各候选 URL 与
+ * 失败原因的 REMOTE_STREAM_UNAVAILABLE 聚合错误，严禁以空流伪装正常。
  */
 export async function* streamRemoteEvents(serverUrl, runId, token, options) {
     assertSecureTransport(serverUrl, token, {
@@ -14,10 +22,11 @@ export async function* streamRemoteEvents(serverUrl, runId, token, options) {
         insecure: options?.insecure,
     });
     const base = normalizeServerUrl(serverUrl);
+    const runRoute = `runs/${encodeURIComponent(runId)}`;
+    // 候选优先级：v2 /events -> v2 /stream -> v1 /stream（后两者经共享协议候选工具展开）
     const candidateUrls = [
-        `${base}/api/v2/runs/${encodeURIComponent(runId)}/events`,
-        `${base}/api/v2/runs/${encodeURIComponent(runId)}/stream`,
-        `${base}/api/v1/runs/${encodeURIComponent(runId)}/stream`,
+        `${base}/api/v2/${runRoute}/events`,
+        ...listProtocolRouteCandidates(base, `/api/v2/${runRoute}/stream`),
     ];
     const headers = {
         Accept: "text/event-stream",
@@ -28,9 +37,15 @@ export async function* streamRemoteEvents(serverUrl, runId, token, options) {
     if (options?.after !== undefined) {
         headers["Last-Event-ID"] = String(options.after);
     }
-    let res;
-    for (const url of candidateUrls) {
-        try {
+    /**
+     * 依次尝试全部候选路由，返回首个可用响应。
+     *
+     * 单个候选失败（网络异常或非流式响应）时记录原因继续尝试后续候选；
+     * 所有候选均失败时返回汇总后的失败原因列表供上层抛出聚合错误。
+     */
+    async function resolveStreamCandidate() {
+        const candidateFailures = [];
+        for (const url of candidateUrls) {
             const fetchInit = {
                 headers,
                 signal: options?.signal,
@@ -41,182 +56,63 @@ export async function* streamRemoteEvents(serverUrl, runId, token, options) {
             else if (options?.insecure) {
                 fetchInit.dispatcher = getInsecureDispatcher();
             }
-            const resp = await fetch(url, fetchInit);
-            if (resp.status === 410) {
-                let errJson;
-                try {
-                    errJson = await resp.json();
+            try {
+                const resp = await fetch(url, fetchInit);
+                if (resp.status === 410) {
+                    let errJson;
+                    try {
+                        errJson = await resp.json();
+                    }
+                    catch { }
+                    const err = new Error(errJson?.error?.message || "Event cursor has expired");
+                    err.code = errJson?.error?.code || "EVENT_CURSOR_EXPIRED";
+                    err.details = errJson?.error?.details;
+                    throw err;
                 }
-                catch { }
-                const err = new Error(errJson?.error?.message || "Event cursor has expired");
-                err.code = errJson?.error?.code || "EVENT_CURSOR_EXPIRED";
-                err.details = errJson?.error?.details;
-                throw err;
-            }
-            if (resp.ok && resp.body) {
-                res = resp;
-                break;
-            }
-            if (resp.status !== 404) {
-                res = resp;
-                break;
-            }
-        }
-        catch (err) {
-            if (err?.code === "EVENT_CURSOR_EXPIRED") {
-                throw err;
-            }
-            // 忽略单次网络连接异常并尝试备选路由
-        }
-    }
-    if (!res || !res.ok || !res.body) {
-        return;
-    }
-    const reader = res.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-    let eventType = "message";
-    let eventId;
-    let dataLines = [];
-    function dispatchCurrentEvent() {
-        if (dataLines.length === 0) {
-            eventType = "message";
-            eventId = undefined;
-            dataLines = [];
-            return undefined;
-        }
-        const dataStr = dataLines.join("\n");
-        const currentType = eventType;
-        const currentId = eventId;
-        eventType = "message";
-        eventId = undefined;
-        dataLines = [];
-        if (!dataStr) {
-            return undefined;
-        }
-        try {
-            const data = JSON.parse(dataStr);
-            if (currentType === "finish") {
-                return {
-                    eventId: currentId ?? data.eventId,
-                    type: "finish",
-                    runId,
-                    timestamp: new Date().toISOString(),
-                    result: data.result || data,
-                };
+                if (resp.ok && resp.body) {
+                    return { ok: true, body: resp.body };
+                }
+                candidateFailures.push({
+                    url,
+                    reason: `HTTP ${resp.status} ${resp.statusText || ""}`.trim(),
+                });
             }
-            else {
-                return {
-                    eventId: currentId ?? data.eventId,
-                    type: (currentType || "message"),
-                    runId,
-                    timestamp: new Date().toISOString(),
-                    ...data,
-                };
+            catch (err) {
+                if (err?.code === "EVENT_CURSOR_EXPIRED") {
+                    throw err;
+                }
+                candidateFailures.push({
+                    url,
+                    reason: err?.message ? `${err.name || "Error"}: ${err.message}` : String(err),
+                });
             }
         }
-        catch {
-            // 忽略非 JSON 数据行
-            return undefined;
-        }
+        return { ok: false, candidateFailures };
     }
-    function processLine(line) {
-        // 遇到空行分发事件
-        if (line === "") {
-            return dispatchCurrentEvent();
-        }
-        // 以冒号开头的为注释忽略
-        if (line.startsWith(":")) {
-            return undefined;
-        }
-        let field = line;
-        let value = "";
-        const colonIdx = line.indexOf(":");
-        if (colonIdx !== -1) {
-            field = line.slice(0, colonIdx);
-            const rawVal = line.slice(colonIdx + 1);
-            value = rawVal.startsWith(" ") ? rawVal.slice(1) : rawVal;
-        }
-        if (field === "event") {
-            eventType = value;
-        }
-        else if (field === "data") {
-            dataLines.push(value);
-        }
-        else if (field === "id") {
-            if (!value.includes("\0")) {
-                eventId = value;
-            }
-        }
-        return undefined;
+    /**
+     * 构造全部候选路由均不可用时的聚合错误。
+     */
+    function buildStreamUnavailableError(candidateFailures) {
+        const summary = candidateFailures
+            .map((f) => `${f.url} (${f.reason})`)
+            .join(", ");
+        const err = new Error(`REMOTE_STREAM_UNAVAILABLE: All event stream candidates failed for run '${runId}': ${summary}`);
+        err.code = REMOTE_STREAM_UNAVAILABLE;
+        err.details = {
+            runId,
+            candidates: candidateFailures.map((f) => ({ url: f.url, reason: f.reason })),
+        };
+        return err;
+    }
+    const res = await resolveStreamCandidate();
+    if (!res.ok) {
+        throw buildStreamUnavailableError(res.candidateFailures);
     }
     try {
-        while (true) {
-            if (options?.signal?.aborted)
-                break;
-            const { done, value } = await reader.read();
-            if (value) {
-                buffer += decoder.decode(value, { stream: !done });
-            }
-            else if (done) {
-                buffer += decoder.decode();
-            }
-            let pos = 0;
-            while (pos < buffer.length) {
-                const cr = buffer.indexOf("\r", pos);
-                const lf = buffer.indexOf("\n", pos);
-                let nextSepPos = -1;
-                let sepLen = 0;
-                if (cr !== -1 && (lf === -1 || cr < lf)) {
-                    if (cr === buffer.length - 1) {
-                        if (!done) {
-                            // 遇到未完结的 \r 暂存等待下个 chunk
-                            break;
-                        }
-                        else {
-                            nextSepPos = cr;
-                            sepLen = 1;
-                        }
-                    }
-                    else {
-                        if (buffer[cr + 1] === "\n") {
-                            nextSepPos = cr;
-                            sepLen = 2;
-                        }
-                        else {
-                            nextSepPos = cr;
-                            sepLen = 1;
-                        }
-                    }
-                }
-                else if (lf !== -1 && (cr === -1 || lf < cr)) {
-                    nextSepPos = lf;
-                    sepLen = 1;
-                }
-                else {
-                    break;
-                }
-                const line = buffer.slice(pos, nextSepPos);
-                pos = nextSepPos + sepLen;
-                const evt = processLine(line);
-                if (evt)
-                    yield evt;
-            }
-            buffer = buffer.slice(pos);
-            if (done) {
-                if (buffer.length > 0) {
-                    const line = buffer;
-                    buffer = "";
-                    const evt = processLine(line);
-                    if (evt)
-                        yield evt;
-                }
-                // 流读取完成时若有剩余待分发事件则进行分发
-                const remainingEvt = dispatchCurrentEvent();
-                if (remainingEvt)
-                    yield remainingEvt;
-                break;
-            }
+        for await (const msg of parseSseMessages(res.body, { signal: options?.signal })) {
+            const evt = decodeExecutionEvent(msg, runId);
+            if (evt)
+                yield evt;
         }
     }
     catch (err) {
@@ -225,18 +121,37 @@ export async function* streamRemoteEvents(serverUrl, runId, token, options) {
         }
         throw err;
     }
-    finally {
-        // 防御性取消底层流：仅 releaseLock 会让连接保持挂起，造成连接泄漏
-        try {
-            await reader.cancel();
-        }
-        catch {
-            // 流已自然结束或已被取消时忽略次级异常
+}
+/**
+ * 将 SSE 消息载荷解码为统一执行事件。
+ *
+ * 非 JSON 数据行直接忽略；finish 事件取 data.result 字段，其余事件字段展开合并。
+ */
+function decodeExecutionEvent(msg, runId) {
+    try {
+        const data = JSON.parse(msg.data);
+        if (msg.event === "finish") {
+            return {
+                eventId: msg.id ?? data.eventId,
+                type: "finish",
+                runId,
+                timestamp: new Date().toISOString(),
+                result: data.result || data,
+            };
         }
-        try {
-            reader.releaseLock();
+        else {
+            return {
+                eventId: msg.id ?? data.eventId,
+                type: (msg.event || "message"),
+                runId,
+                timestamp: new Date().toISOString(),
+                ...data,
+            };
         }
-        catch { }
+    }
+    catch {
+        // 忽略非 JSON 数据行
+        return undefined;
     }
 }
 /**
@@ -601,85 +516,14 @@ export class RemoteActionDockTarget {
      * 指数退避轮询远端运行详情直至终态、取消或超时上限。
      */
     async pollRunCompletion(runId, signal, timeoutMs, startTime = Date.now(), totalMaxWaitMs) {
-        const maxWaitMs = totalMaxWaitMs ?? Math.max(this.baseTimeoutMs, timeoutMs ?? 0);
-        const remainingWaitMs = Math.max(0, maxWaitMs - (Date.now() - startTime));
-        let delayMs = Math.min(150, Math.max(10, Math.floor((remainingWaitMs || maxWaitMs) / 4)));
-        const maxDelayMs = 2000;
-        while (Date.now() - startTime < maxWaitMs) {
-            if (this.isClosed) {
-                return {
-                    ok: false,
-                    runId,
-                    error: {
-                        code: TARGET_CLOSED,
-                        message: "RemoteActionDockTarget is closed",
-                    },
-                };
-            }
-            if (signal?.aborted) {
-                return {
-                    ok: false,
-                    runId,
-                    error: {
-                        code: ACTION_CANCELLED,
-                        message: "Action execution was cancelled",
-                    },
-                };
-            }
-            try {
-                const run = await this.getRun(runId);
-                if (run && isTerminalRunStatus(run.status)) {
-                    return this.formatTerminalRunResult(run, runId);
-                }
-            }
-            catch (err) {
-                if (err?.code === TARGET_CLOSED || this.isClosed) {
-                    return {
-                        ok: false,
-                        runId,
-                        error: {
-                            code: TARGET_CLOSED,
-                            message: "RemoteActionDockTarget is closed",
-                        },
-                    };
-                }
-                throw err;
-            }
-            await new Promise((resolve) => setTimeout(resolve, delayMs));
-            delayMs = Math.min(delayMs * 2, maxDelayMs);
-        }
-        const waitedMs = Date.now() - startTime;
-        return {
-            ok: false,
-            runId,
-            error: {
-                code: TIMEOUT,
-                message: `Timed out waiting for run '${runId}' completion after ${waitedMs}ms`,
-            },
-        };
+        return pollRunCompletion({
+            baseTimeoutMs: this.baseTimeoutMs,
+            isClosed: () => this.isClosed,
+            getRun: (id) => this.getRun(id),
+        }, runId, signal, timeoutMs, startTime, totalMaxWaitMs);
     }
     formatTerminalRunResult(run, runId) {
-        if (run.status === "success") {
-            return { ok: true, runId, data: run.output ?? null };
-        }
-        if (run.status === "interrupted") {
-            return {
-                ok: false,
-                runId,
-                error: run.error || {
-                    code: "RUN_INTERRUPTED",
-                    message: `Run '${runId}' was interrupted`,
-                },
-            };
-        }
-        return {
-            ok: false,
-            runId,
-            error: run.error || {
-                code: EXECUTION_FAILED,
-                message: `Run finished with status ${run.status}`,
-            },
-        };
+        return formatTerminalRunResult(run, runId);
     }
     async listRuns(options) {
         this.assertNotClosed();
@@ -972,40 +816,3 @@ export class RemoteActionDockTarget {
         this.isClosed = true;
     }
 }
-/**
- * 判定远端状态键访问异常是否为键不存在。
- *
- * 优先读取传输层透传的结构化错误码（fetchRemoteJson 会将响应体 error.code
- * 附加到抛出异常的 code 字段），仅当旧版服务器未透传 code 时回退到
- * HTTP 状态与消息文本兼容嗅探。
- */
-function isRemoteStateKeyNotFound(err) {
-    if (err?.code === STATE_KEY_NOT_FOUND) {
-        return true;
-    }
-    const msg = String(err?.message || "");
-    return err?.status === 404 || msg.includes("404") || msg.includes("not found");
-}
-function wrapRemoteError(err) {
-    const msg = String(err?.message || "");
-    const code = err?.code || "";
-    if (code === "CAPABILITY_UNAVAILABLE" ||
-        code === "TARGET_CAPABILITY_UNAVAILABLE" ||
-        msg.includes("CAPABILITY_UNAVAILABLE") ||
-        msg.includes("TARGET_CAPABILITY_UNAVAILABLE") ||
-        msg.includes("Management APIs are not enabled")) {
-        throw new TargetError(TARGET_CAPABILITY_UNAVAILABLE, `TARGET_CAPABILITY_UNAVAILABLE: Management APIs are not enabled on remote target`, { originalMessage: msg });
-    }
-    if (code === "PROTOCOL_UNSUPPORTED" ||
-        code === "TARGET_PROTOCOL_UNSUPPORTED" ||
-        msg.includes("PROTOCOL_UNSUPPORTED") ||
-        msg.includes("TARGET_PROTOCOL_UNSUPPORTED")) {
-        throw new TargetError(TARGET_PROTOCOL_UNSUPPORTED, `TARGET_PROTOCOL_UNSUPPORTED: ${msg}`, { originalMessage: msg });
-    }
-    if (code === "TARGET_RESULT_UNKNOWN" ||
-        code === "RESULT_UNKNOWN" ||
-        msg.includes("TARGET_RESULT_UNKNOWN")) {
-        throw new TargetError(TARGET_RESULT_UNKNOWN, `TARGET_RESULT_UNKNOWN: ${msg}`, { originalMessage: msg });
-    }
-    throw err;
-}