@actiondock/core 2.7.0 → 2.8.0

package/dist/service/remote.js

@@ -0,0 +1,634 @@
+import { parseActionRef } from "../catalog/resolve-action.js";
+import { ActionDockError, ACTION_CANCELLED, CAPABILITY_UNAVAILABLE, INVALID_ARGUMENT, TIMEOUT, } from "../errors.js";
+import { cancelRemoteRun, clearRemoteRuns, clearRemoteState, deleteRemoteConfig, deleteRemoteStateKey, executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteConfig, fetchRemoteInfo, fetchRemotePlaybookShow, fetchRemotePlaybooks, fetchRemoteRun, fetchRemoteRuns, fetchRemoteStateList, getRemoteStateKey, setRemoteConfig, setRemoteStateKey, } from "../profile/client.js";
+import { isRemoteStateKeyNotFound, wrapRemoteError } from "./remote-errors.js";
+import { formatTerminalRunResult, pollRunCompletion } from "./remote-polling.js";
+import { streamRemoteEvents } from "./sse-stream.js";
+import { isTerminalRunStatus } from "../storage/types.js";
+import { ACTIONDOCK_PROTOCOL_VERSION, PROTOCOL_UNSUPPORTED, SERVICE_CLOSED, ServiceError, } from "./types.js";
+/**
+ * 远程 ActionDockService 端口实现。
+ * 封装与远端 ActionDock 服务的 HTTP / SSE 协议交互，
+ * 遵循统一的 Service Ports 契约。
+ */
+export class RemoteActionDockService {
+    serverUrl;
+    token;
+    timeoutMs;
+    baseTimeoutMs;
+    allowInsecureHttp;
+    insecure;
+    dispatcher;
+    isClosed = false;
+    discovery;
+    execution;
+    runs;
+    events;
+    management;
+    constructor(options) {
+        if (!options.serverUrl) {
+            throw new ActionDockError(INVALID_ARGUMENT, "serverUrl is required for RemoteActionDockService");
+        }
+        this.serverUrl = options.serverUrl;
+        this.token = options.token;
+        this.timeoutMs = options.timeoutMs;
+        this.baseTimeoutMs = options.baseTimeoutMs ?? 60000;
+        this.allowInsecureHttp = options.allowInsecureHttp;
+        this.insecure = options.insecure;
+        this.dispatcher = options.dispatcher;
+        const self = this;
+        this.discovery = {
+            async listPackages() {
+                self.assertNotClosed();
+                let raw;
+                try {
+                    raw = await fetchRemoteInfo(self.serverUrl, self.token, {
+                        allowInsecureHttp: self.allowInsecureHttp,
+                        insecure: self.insecure,
+                        dispatcher: self.dispatcher,
+                    });
+                }
+                catch (err) {
+                    wrapRemoteError(err);
+                }
+                const protocolVersion = (raw && typeof raw === "object" && raw.protocolVersion) || ACTIONDOCK_PROTOCOL_VERSION;
+                if (protocolVersion && typeof protocolVersion === "string") {
+                    const [remoteMajor] = protocolVersion.split(".");
+                    const [currentMajor] = ACTIONDOCK_PROTOCOL_VERSION.split(".");
+                    if (remoteMajor !== currentMajor) {
+                        throw new ServiceError(PROTOCOL_UNSUPPORTED, `PROTOCOL_UNSUPPORTED: Remote server protocol version '${protocolVersion}' is incompatible with expected '${ACTIONDOCK_PROTOCOL_VERSION}'`);
+                    }
+                }
+                if (Array.isArray(raw)) {
+                    return raw;
+                }
+                if (raw && typeof raw === "object") {
+                    if (Array.isArray(raw.packages)) {
+                        return raw.packages;
+                    }
+                    if (raw.packages && typeof raw.packages === "object") {
+                        return Object.values(raw.packages);
+                    }
+                }
+                return [];
+            },
+            async listActions(opts) {
+                self.assertNotClosed();
+                const rawList = await fetchRemoteActions(self.serverUrl, self.token, opts?.query, {
+                    allowInsecureHttp: self.allowInsecureHttp,
+                    insecure: self.insecure,
+                    dispatcher: self.dispatcher,
+                });
+                let summaries = rawList.map((item) => ({
+                    id: item.id,
+                    description: item.description,
+                    tags: item.tags,
+                    inputSchema: item.inputSchema,
+                    outputSchema: item.outputSchema,
+                    packageId: item.packageId,
+                }));
+                if (opts?.prefix) {
+                    summaries = summaries.filter((s) => s.id.startsWith(opts.prefix));
+                }
+                if (opts?.tags && opts.tags.length > 0) {
+                    summaries = summaries.filter((s) => opts.tags.every((t) => s.tags?.includes(t)));
+                }
+                return summaries;
+            },
+            async describeAction(ref) {
+                self.assertNotClosed();
+                let parsed;
+                try {
+                    parsed = parseActionRef(ref);
+                }
+                catch {
+                    parsed = typeof ref === "object" ? ref : { actionId: ref };
+                }
+                const actionId = parsed.packageId
+                    ? `${parsed.packageId}/${parsed.actionId}`
+                    : parsed.actionId;
+                const raw = await fetchRemoteActionShow(self.serverUrl, actionId, self.token, {
+                    allowInsecureHttp: self.allowInsecureHttp,
+                    insecure: self.insecure,
+                    dispatcher: self.dispatcher,
+                });
+                return {
+                    id: raw.id,
+                    description: raw.description,
+                    inputSchema: raw.inputSchema,
+                    outputSchema: raw.outputSchema,
+                    tags: raw.tags,
+                    annotations: raw.annotations,
+                    uses: raw.uses,
+                    entry: raw.entry,
+                    filePath: raw.filePath,
+                    packageId: raw.packageId ?? parsed.packageId,
+                };
+            },
+            async listPlaybooks(opts) {
+                self.assertNotClosed();
+                const rawList = await fetchRemotePlaybooks(self.serverUrl, self.token, {
+                    ...opts,
+                    allowInsecureHttp: self.allowInsecureHttp,
+                    insecure: self.insecure,
+                    dispatcher: self.dispatcher,
+                });
+                return rawList.map((item) => ({
+                    id: item.id,
+                    description: item.description,
+                    actions: item.actions,
+                    packageId: item.packageId,
+                    filePath: item.filePath,
+                }));
+            },
+            async describePlaybook(id) {
+                self.assertNotClosed();
+                const raw = await fetchRemotePlaybookShow(self.serverUrl, id, self.token, {
+                    allowInsecureHttp: self.allowInsecureHttp,
+                    insecure: self.insecure,
+                    dispatcher: self.dispatcher,
+                });
+                const parsedPkgId = id.includes("/") ? id.slice(0, id.lastIndexOf("/")) : undefined;
+                return {
+                    id: raw.id,
+                    description: raw.description,
+                    actions: raw.actions,
+                    filePath: raw.filePath,
+                    content: raw.content,
+                    packageId: raw.packageId ?? parsedPkgId,
+                };
+            },
+        };
+        this.execution = {
+            async run(ref, input, opts) {
+                self.assertNotClosed();
+                let parsed;
+                try {
+                    parsed = parseActionRef(ref);
+                }
+                catch {
+                    parsed = typeof ref === "object" ? ref : { actionId: String(ref) };
+                }
+                const actionId = parsed.packageId
+                    ? `${parsed.packageId}/${parsed.actionId}`
+                    : parsed.actionId;
+                return executeRemoteAction(self.serverUrl, actionId, (input ?? {}), {
+                    configOverrides: opts?.config,
+                    token: self.token,
+                    timeoutMs: opts?.timeoutMs ?? self.timeoutMs,
+                    signal: opts?.signal,
+                    requestId: opts?.requestId,
+                    async: false,
+                    allowInsecureHttp: self.allowInsecureHttp,
+                    insecure: self.insecure,
+                    dispatcher: self.dispatcher,
+                });
+            },
+            async start(ref, input, opts) {
+                self.assertNotClosed();
+                let parsed;
+                try {
+                    parsed = parseActionRef(ref);
+                }
+                catch {
+                    parsed = typeof ref === "object" ? ref : { actionId: String(ref) };
+                }
+                const actionId = parsed.packageId
+                    ? `${parsed.packageId}/${parsed.actionId}`
+                    : parsed.actionId;
+                const res = await executeRemoteAction(self.serverUrl, actionId, (input ?? {}), {
+                    configOverrides: opts?.config,
+                    token: self.token,
+                    timeoutMs: opts?.timeoutMs ?? self.timeoutMs,
+                    signal: opts?.signal,
+                    requestId: opts?.requestId,
+                    async: true,
+                    allowInsecureHttp: self.allowInsecureHttp,
+                    insecure: self.insecure,
+                    dispatcher: self.dispatcher,
+                });
+                if (!res.ok) {
+                    return {
+                        runId: res.runId,
+                        status: "failed",
+                        result: Promise.resolve(res),
+                    };
+                }
+                const runId = res.runId || res.data?.runId;
+                const status = res.status || res.data?.status || "running";
+                return {
+                    runId,
+                    status,
+                    result: self.waitForRunCompletion(runId, opts?.signal, opts?.timeoutMs),
+                };
+            },
+        };
+        this.runs = {
+            async list(query) {
+                self.assertNotClosed();
+                try {
+                    const res = await fetchRemoteRuns(self.serverUrl, self.token, {
+                        packageId: query?.packageId,
+                        actionId: query?.actionId,
+                        status: query?.status,
+                        intent: query?.intent,
+                        limit: query?.limit,
+                        allowInsecureHttp: self.allowInsecureHttp,
+                        insecure: self.insecure,
+                        dispatcher: self.dispatcher,
+                    });
+                    return res.items || [];
+                }
+                catch (err) {
+                    wrapRemoteError(err);
+                }
+            },
+            async get(runId) {
+                self.assertNotClosed();
+                try {
+                    return await fetchRemoteRun(self.serverUrl, runId, self.token, {
+                        allowInsecureHttp: self.allowInsecureHttp,
+                        insecure: self.insecure,
+                        dispatcher: self.dispatcher,
+                    });
+                }
+                catch (err) {
+                    const code = String(err?.code || "");
+                    if (code === "RUN_NOT_FOUND" || code === "NOT_FOUND" || err?.status === 404) {
+                        return undefined;
+                    }
+                    throw err;
+                }
+            },
+            async cancel(runId, reason) {
+                self.assertNotClosed();
+                try {
+                    const res = await cancelRemoteRun(self.serverUrl, runId, self.token, reason, {
+                        allowInsecureHttp: self.allowInsecureHttp,
+                        insecure: self.insecure,
+                        dispatcher: self.dispatcher,
+                    });
+                    return { outcome: "requested", runId: res.runId };
+                }
+                catch (err) {
+                    const code = String(err?.code || "");
+                    if (code === "RUN_ALREADY_FINISHED") {
+                        let status = err?.errorData?.status || err?.details?.status;
+                        if (!status) {
+                            try {
+                                const run = await self.runs.get(runId);
+                                if (run?.status) {
+                                    status = run.status;
+                                }
+                            }
+                            catch { }
+                        }
+                        return { outcome: "already_terminal", runId, status: status || "failed" };
+                    }
+                    if (code === "RUN_NOT_FOUND" || code === "NOT_FOUND" || err?.status === 404) {
+                        return { outcome: "not_found", runId };
+                    }
+                    throw err;
+                }
+            },
+            async clear(opts) {
+                self.assertNotClosed();
+                try {
+                    const res = await clearRemoteRuns(self.serverUrl, self.token, {
+                        ...opts,
+                        allowInsecureHttp: self.allowInsecureHttp,
+                        insecure: self.insecure,
+                        dispatcher: self.dispatcher,
+                    });
+                    return res.clearedCount ?? 0;
+                }
+                catch (err) {
+                    wrapRemoteError(err);
+                }
+            },
+        };
+        this.events = {
+            events(runId, opts) {
+                self.assertNotClosed();
+                async function* stream() {
+                    self.assertNotClosed();
+                    for await (const event of streamRemoteEvents(self.serverUrl, runId, self.token, {
+                        ...opts,
+                        allowInsecureHttp: self.allowInsecureHttp,
+                        insecure: self.insecure,
+                        dispatcher: self.dispatcher,
+                    })) {
+                        self.assertNotClosed();
+                        yield event;
+                    }
+                }
+                return stream();
+            },
+        };
+        if (options?.enableManagement !== false) {
+            this.management = {
+                config: {
+                    async get(packageId, key) {
+                        self.assertNotClosed();
+                        try {
+                            const list = await self.management.config.list(packageId);
+                            const found = list.find((c) => c.key === key);
+                            if (found) {
+                                return found;
+                            }
+                            return {
+                                key,
+                                configured: false,
+                                secret: false,
+                                source: "default",
+                                value: undefined,
+                            };
+                        }
+                        catch (err) {
+                            wrapRemoteError(err);
+                        }
+                    },
+                    async set(packageId, key, value) {
+                        self.assertNotClosed();
+                        try {
+                            await setRemoteConfig(self.serverUrl, key, value, self.token, packageId || undefined, {
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                        }
+                        catch (err) {
+                            wrapRemoteError(err);
+                        }
+                    },
+                    async delete(packageId, key) {
+                        self.assertNotClosed();
+                        try {
+                            const res = await deleteRemoteConfig(self.serverUrl, key, self.token, packageId || undefined, {
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                            return Boolean(res?.deleted ?? true);
+                        }
+                        catch (err) {
+                            wrapRemoteError(err);
+                        }
+                    },
+                    async list(packageId) {
+                        self.assertNotClosed();
+                        try {
+                            const res = await fetchRemoteConfig(self.serverUrl, self.token, packageId || undefined, {
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                            if (Array.isArray(res))
+                                return res;
+                            if (Array.isArray(res?.items))
+                                return res.items;
+                            if (Array.isArray(res?.config))
+                                return res.config;
+                            const values = res?.values || {};
+                            const declared = res?.declared || {};
+                            const defaultSource = packageId === "global" ? "global" : "package";
+                            return Object.entries(values).map(([k, v]) => ({
+                                key: k,
+                                configured: v !== undefined,
+                                secret: Boolean(declared[k]?.secret),
+                                source: defaultSource,
+                                value: v,
+                            }));
+                        }
+                        catch (err) {
+                            wrapRemoteError(err);
+                        }
+                    },
+                },
+                state: {
+                    async get(packageId, actionId, key, opts) {
+                        self.assertNotClosed();
+                        try {
+                            const res = await getRemoteStateKey(self.serverUrl, key, self.token, {
+                                package: packageId || undefined,
+                                action: actionId || undefined,
+                                namespace: opts?.namespace,
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                            if (res === undefined)
+                                return undefined;
+                            if (opts?.detail) {
+                                return res;
+                            }
+                            return (res?.value !== undefined ? res.value : res);
+                        }
+                        catch (err) {
+                            if (isRemoteStateKeyNotFound(err)) {
+                                return undefined;
+                            }
+                            wrapRemoteError(err);
+                        }
+                    },
+                    async set(packageId, actionId, key, value, opts) {
+                        self.assertNotClosed();
+                        try {
+                            await setRemoteStateKey(self.serverUrl, key, value, self.token, {
+                                package: packageId || undefined,
+                                action: actionId || undefined,
+                                namespace: opts?.namespace,
+                                ttl: opts?.ttl,
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                        }
+                        catch (err) {
+                            wrapRemoteError(err);
+                        }
+                    },
+                    async delete(packageId, actionId, key, opts) {
+                        self.assertNotClosed();
+                        try {
+                            const res = await deleteRemoteStateKey(self.serverUrl, key, self.token, {
+                                package: packageId || undefined,
+                                action: actionId || undefined,
+                                namespace: opts?.namespace,
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                            return Boolean(res?.deleted ?? true);
+                        }
+                        catch (err) {
+                            if (isRemoteStateKeyNotFound(err)) {
+                                return false;
+                            }
+                            wrapRemoteError(err);
+                        }
+                    },
+                    async list(packageId, actionId, opts) {
+                        self.assertNotClosed();
+                        try {
+                            const res = await fetchRemoteStateList(self.serverUrl, self.token, {
+                                package: packageId || undefined,
+                                action: actionId || undefined,
+                                namespace: opts?.namespace,
+                                prefix: opts?.prefix,
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                            return res.keys || [];
+                        }
+                        catch (err) {
+                            wrapRemoteError(err);
+                        }
+                    },
+                    async clear(packageId, actionId, opts) {
+                        self.assertNotClosed();
+                        try {
+                            const res = await clearRemoteState(self.serverUrl, self.token, {
+                                package: packageId || undefined,
+                                action: actionId || undefined,
+                                namespace: opts?.namespace,
+                                prefix: opts?.prefix,
+                                all: opts?.all,
+                                allowInsecureHttp: self.allowInsecureHttp,
+                                insecure: self.insecure,
+                                dispatcher: self.dispatcher,
+                            });
+                            return res.clearedCount ?? 0;
+                        }
+                        catch (err) {
+                            wrapRemoteError(err);
+                        }
+                    },
+                    async listEntries(_packageId, _opts) {
+                        self.assertNotClosed();
+                        throw new ServiceError(CAPABILITY_UNAVAILABLE, "CAPABILITY_UNAVAILABLE: listStateEntries is not supported on remote service");
+                    },
+                },
+            };
+        }
+    }
+    assertNotClosed() {
+        if (this.isClosed) {
+            throw new ServiceError(SERVICE_CLOSED, "RemoteActionDockService is closed");
+        }
+    }
+    async info() {
+        return this.discovery.listPackages();
+    }
+    async waitForRunCompletion(runId, signal, timeoutMs) {
+        const startTime = Date.now();
+        const maxWaitMs = Math.max(this.baseTimeoutMs, timeoutMs ?? 0);
+        // 服务已关闭时的统一失败结果
+        const closedResult = () => ({
+            ok: false,
+            runId,
+            error: {
+                code: SERVICE_CLOSED,
+                message: "RemoteActionDockService is closed",
+            },
+        });
+        // 外部取消信号已触发时的统一取消结果
+        const cancelledResult = () => ({
+            ok: false,
+            runId,
+            error: {
+                code: ACTION_CANCELLED,
+                message: "Action execution was cancelled",
+            },
+        });
+        if (signal?.aborted) {
+            return cancelledResult();
+        }
+        if (this.isClosed) {
+            return closedResult();
+        }
+        const internalController = new AbortController();
+        let sseTimedOut = false;
+        let timer;
+        if (maxWaitMs > 0 && maxWaitMs !== Infinity) {
+            timer = setTimeout(() => {
+                sseTimedOut = true;
+                internalController.abort();
+            }, maxWaitMs);
+        }
+        const onAbort = () => {
+            internalController.abort();
+        };
+        if (signal) {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        try {
+            for await (const evt of this.events.events(runId, { signal: internalController.signal })) {
+                if (evt.type === "finish") {
+                    const res = evt.result || evt.data || evt;
+                    if (typeof res?.ok === "boolean") {
+                        return res;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (err?.code === SERVICE_CLOSED || this.isClosed) {
+                return closedResult();
+            }
+            if (!signal?.aborted && !sseTimedOut) {
+                console.warn(`[ActionDock] SSE event stream unavailable for run '${runId}', falling back to polling: ${err?.message || String(err)}`);
+            }
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            if (signal) {
+                signal.removeEventListener("abort", onAbort);
+            }
+        }
+        if (signal?.aborted) {
+            return cancelledResult();
+        }
+        const remainingWaitMs = Math.max(0, maxWaitMs - (Date.now() - startTime));
+        if (remainingWaitMs <= 0) {
+            if (this.isClosed) {
+                return closedResult();
+            }
+            try {
+                const run = await this.runs.get(runId);
+                if (run && isTerminalRunStatus(run.status)) {
+                    return formatTerminalRunResult(run, runId);
+                }
+            }
+            catch (err) {
+                if (err?.code === SERVICE_CLOSED || this.isClosed) {
+                    return closedResult();
+                }
+                throw err;
+            }
+            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.runs.get(id),
+        }, runId, signal, remainingWaitMs, startTime, maxWaitMs);
+    }
+    async close(_options) {
+        if (this.isClosed) {
+            return;
+        }
+        this.isClosed = true;
+    }
+}

package/dist/service/sse-stream.d.ts

@@ -0,0 +1,24 @@
+import type { ExecutionEvent } from "@actiondock/sdk";
+import { type SseMessage } from "./sse-parser.js";
+/**
+ * 将 SSE 消息载荷解码为统一执行事件。
+ *
+ * 非 JSON 数据行直接忽略；finish 事件取 data.result 字段，其余事件字段展开合并。
+ */
+export declare function decodeExecutionEvent(msg: SseMessage, runId: string): ExecutionEvent | undefined;
+/**
+ * 订阅远端运行事件流（Server-Sent Events）。
+ *
+ * 候选路由探测与自动回退：优先尝试标准 v2 路由 /api/v2/runs/:runId/events，
+ * 失败时回退至既有路由 /api/v2/runs/:runId/stream；
+ * 全部候选均不可用（网络异常或非流式响应）时抛出携带各候选 URL 与
+ * 失败原因的 REMOTE_STREAM_UNAVAILABLE 聚合错误，严禁以空流伪装正常。
+ */
+export declare function streamRemoteEvents(serverUrl: string, runId: string, token?: string, options?: {
+    after?: number | string;
+    signal?: AbortSignal;
+    maxQueueSize?: number;
+    allowInsecureHttp?: boolean;
+    insecure?: boolean;
+    dispatcher?: unknown;
+}): AsyncIterable<ExecutionEvent>;