@actiondock/core 2.9.1 → 2.11.0

package/README.md

@@ -56,7 +56,7 @@ Service -> Resolution -> PackageRuntime -> ExecutionService -> ActionRunner -> A
 
 - 发现端口 `DiscoveryPort`：负责包与动作的元数据发现、清单检索、全文过滤与规程查询。
 - 执行端口 `ExecutionPort`：负责动作的同步阻塞执行（`run`）与异步启动执行（`start`）。
-- 运行端口 `RunsPort`：负责任务运行历史列表、单次详情查询、协同取消（`cancel`）以及历史记录清理与保留策略淘汰（`clearRuns`、`cleanExpiredRuns`）。
+- 运行端口 `RunsPort`：负责任务运行历史列表（含幂等请求标识反查）、单次详情查询、读取链路取消信号（`signal`）、协同取消（`cancel`）以及历史记录清理与保留策略淘汰（`clearRuns`、`cleanExpiredRuns`）。
 - 事件端口 `EventsPort`：负责任务执行实时事件流订阅。
 - 配置端口 `ConfigPort`：负责运行时分层配置读取、持久化配置管理与环境变量满足度体检。
 - 状态端口 `StatePort`：负责包级与动作级持久化键值存取、前缀列举与过期清理。
@@ -83,7 +83,6 @@ ActionDock 2.x 全面贯彻单一事实源设计，彻底杜绝各模块私自
 - 受管进程平台驱动 `NodeProcessDriver`：实现完整的受管进程治理体系。基于管道彻底切断子进程与宿主标准流的物理连通；支持跨平台独立进程组管理与信号派发；提供独占控制权租约、逐流增量读取与优雅终止。
 - 原生网络服务容器 `NodeHttpServer`：基于 Node.js 原生 `node:http` 承载 RESTful 微服务与 Server-Sent Events 事件流。
 - 原生模块加载器 `NodeModuleLoader`：基于 Node.js 原生类型擦除机制直接加载 TypeScript 源码，免除前置编译转译开销。
-- 原生文件系统抽象 `NodeFileSystem`：提供跨平台文件读写与原子文件事务保障。
 
 ---
 

package/dist/catalog/action-catalog.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { parseActionRef } from "./resolve-action.js";
 /**
@@ -75,7 +75,7 @@ export class DefaultActionCatalog {
         for (const node of graph.packages.values()) {
             const packageId = node.identity.id;
             const manifest = node.manifest;
-            // 1. 清单显式 actions 声明优先索引
+            // - 清单显式 actions 声明优先索引
             if (manifest?.actions && typeof manifest.actions === "object") {
                 for (const [actionId, item] of Object.entries(manifest.actions)) {
                     const entry = item?.entry || inferActionEntry(node.root, manifest, actionId);
@@ -98,7 +98,7 @@ export class DefaultActionCatalog {
                     this.addCandidate(candidate);
                 }
             }
-            // 2. 内存动态注入动作索引（测试或 Host 注册场景）
+            // - 内存动态注入动作索引（测试或 Host 注册场景）
             if (actionsProvider) {
                 const dynActions = actionsProvider(packageId);
                 if (dynActions && typeof dynActions.entries === "function") {
@@ -119,36 +119,6 @@ export class DefaultActionCatalog {
                     }
                 }
             }
-            // 3. actions 目录回退扫描
-            const actionsDir = join(node.root, manifest?.actionsDir || "actions");
-            if (existsSync(actionsDir)) {
-                try {
-                    const files = readdirSync(actionsDir);
-                    for (const file of files) {
-                        if (file.endsWith(".ts") || file.endsWith(".js")) {
-                            if (file.endsWith(".d.ts") || file.endsWith(".test.ts") || file.endsWith(".spec.ts")) {
-                                continue;
-                            }
-                            const actionId = file.replace(/\.(ts|js)$/, "");
-                            const qualifiedKey = `${packageId}/${actionId}`;
-                            if (!this.byPackageAndAction.has(qualifiedKey)) {
-                                const candidate = {
-                                    packageId,
-                                    packageIdentity: node.identity,
-                                    actionId,
-                                    contract: { id: actionId },
-                                    entry: join(manifest?.actionsDir || "actions", file),
-                                    packageRoot: node.root,
-                                };
-                                this.addCandidate(candidate);
-                            }
-                        }
-                    }
-                }
-                catch {
-                    // 忽略扫描目录异常
-                }
-            }
         }
     }
     find(ref) {

package/dist/catalog/discovery.d.ts

@@ -1,5 +1,4 @@
 import type { ActionDockManifest } from "../project/types.js";
-import { type RegistryStore } from "../registry/store.js";
 import type { PackageIdentity } from "../runtime/identity.js";
 /**
  * 发现的包基本信息规范。
@@ -28,8 +27,6 @@ export interface PackageDiscoveryOptions {
     currentProjectRoot?: string;
     /** 自定义 ActionDock 主目录路径（用于定位注册表） */
     customHome?: string;
-    /** 显式注入的注册表存储实例（可选，默认使用 DefaultRegistryStore） */
-    registryStore?: RegistryStore;
     /** 附加显式包根目录集合 */
     packageRoots?: string[];
     /** 附加显式工作区根目录集合 */

package/dist/catalog/discovery.js

@@ -2,8 +2,9 @@ import { existsSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { loadProjectConfig } from "../project/loader.js";
 import { loadManifest } from "../project/manifest.js";
-import { DefaultRegistryStore } from "../registry/store.js";
+import { loadRegistry } from "../registry/registry.js";
 import { discoverProjectConfigs } from "../registry/scan.js";
+import { ActionDockError, PACKAGE_ID_CONFLICT } from "../errors.js";
 /**
  * 包发现单一事实源 PackageDiscovery。
  * 负责聚合当前工程、用户显式注册包位置与工作区根目录，输出已发现包集合。
@@ -22,7 +23,6 @@ export class PackageDiscovery {
     discoverSync() {
         const packages = new Map();
         this.idRealPaths.clear();
-        const registryStore = this.options.registryStore || new DefaultRegistryStore(this.options.customHome);
         const scanLinked = this.options.scanLinkedPackages !== false;
         const registerPackage = (pathOrRoot, flags) => {
             const abs = resolve(pathOrRoot);
@@ -51,7 +51,7 @@ export class PackageDiscovery {
             const idRealPaths = this.idRealPaths;
             const existingReal = idRealPaths.get(manifest.id);
             if (existingReal !== undefined && existingReal !== real) {
-                throw new Error(`PACKAGE_ID_CONFLICT: Package ID '${manifest.id}' is declared by multiple directories: '${existingReal}' and '${abs}'`);
+                throw new ActionDockError(PACKAGE_ID_CONFLICT, `PACKAGE_ID_CONFLICT: Package ID '${manifest.id}' is declared by multiple directories: '${existingReal}' and '${abs}'`);
             }
             idRealPaths.set(manifest.id, real);
             packages.set(real, {
@@ -74,7 +74,7 @@ export class PackageDiscovery {
         // 3. 注册表登记位置
         if (scanLinked) {
             try {
-                const regData = registryStore.load();
+                const regData = loadRegistry(this.options.customHome);
                 if (regData.packages) {
                     for (const pkg of Object.values(regData.packages)) {
                         if (pkg.path) {

package/dist/catalog/graph.d.ts

@@ -183,8 +183,4 @@ export declare class PackageGraphBuilder {
      * 同步构建包依赖拓扑图。
      */
     buildSync(): PackageGraph;
-    /**
-     * 异步构建包依赖拓扑图。
-     */
-    build(): Promise<PackageGraph>;
 }

package/dist/catalog/graph.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
-import { ActionDockError, ACTION_PACKAGE_VERSION_CONFLICT, PACKAGE_NOT_FOUND, UNDECLARED_ACTION_DEPENDENCY, } from "../errors.js";
+import { ActionDockError, ACTION_PACKAGE_VERSION_CONFLICT, MANIFEST_DIGEST_MISMATCH, MANIFEST_NOT_FOUND, MANIFEST_READ_FAILED, PACKAGE_NOT_FOUND, UNDECLARED_ACTION_DEPENDENCY, } from "../errors.js";
 import { computeManifestDigest, parseJsonWithoutDuplicates } from "../project/digest.js";
 import { loadLockfile } from "../project/lockfile.js";
 import { loadPlaybooks, loadProjectConfig } from "../project/loader.js";
@@ -42,8 +42,8 @@ export class ActionPackageVersionConflictError extends ActionDockError {
     packageId;
     conflicts;
     constructor(packageId, conflicts) {
-        const details = conflicts.map((c) => `'${c.requester}' 要求 '${c.rangeOrVersion}'`).join(", ");
-        super(ACTION_PACKAGE_VERSION_CONFLICT, `ACTION_PACKAGE_VERSION_CONFLICT: 逻辑包 '${packageId}' 存在不可收敛的版本冲突: ${details}`);
+        const details = conflicts.map((c) => `'${c.requester}' requires '${c.rangeOrVersion}'`).join(", ");
+        super(ACTION_PACKAGE_VERSION_CONFLICT, `ACTION_PACKAGE_VERSION_CONFLICT: Package '${packageId}' has irreconcilable version conflicts: ${details}`);
         this.name = "ActionPackageVersionConflictError";
         this.packageId = packageId;
         this.conflicts = conflicts;
@@ -57,10 +57,13 @@ export class UndeclaredActionDependencyError extends ActionDockError {
     targetRef;
     caller;
     constructor(targetRef, caller, reason) {
+        const hint = caller
+            ? `Hint: Add '${targetRef}' to the 'uses' array of action '${caller}' in actiondock.json, then run 'ad validate'.`
+            : undefined;
         const msg = caller
-            ? `UNDECLARED_ACTION_DEPENDENCY: Action '${caller}' 未在 'uses' 中声明对 '${targetRef}' 的跨包依赖`
-            : `UNDECLARED_ACTION_DEPENDENCY: 根调用 Action '${targetRef}' 被拒绝: 目标包既非 actiondock.json 直接依赖，亦未被可见 Playbook 委托${reason ? ` (${reason})` : ""}`;
-        super(UNDECLARED_ACTION_DEPENDENCY, msg);
+            ? `UNDECLARED_ACTION_DEPENDENCY: Action '${caller}' has not declared cross-package dependency on '${targetRef}' in 'uses'${hint ? `\n${hint}` : ""}`
+            : `UNDECLARED_ACTION_DEPENDENCY: Root invocation of action '${targetRef}' was rejected: target package is neither a direct dependency in actiondock.json nor delegated by a visible Playbook${reason ? ` (${reason})` : ""}`;
+        super(UNDECLARED_ACTION_DEPENDENCY, msg, hint ? { hint } : undefined, undefined, hint);
         this.name = "UndeclaredActionDependencyError";
         this.targetRef = targetRef;
         this.caller = caller;
@@ -493,19 +496,19 @@ export class PackageGraphBuilder {
                 }
                 const manifestPath = join(pkgDir, MANIFEST_FILE_NAME);
                 if (!existsSync(manifestPath)) {
-                    throw new Error(`Action package '${item.pkgId}' at '${pkgDir}' misses required manifest 'actiondock.json'`);
+                    throw new ActionDockError(MANIFEST_NOT_FOUND, `Action package '${item.pkgId}' at '${pkgDir}' misses required manifest 'actiondock.json'`);
                 }
                 let manifestRaw;
                 try {
                     manifestRaw = readFileSync(manifestPath, "utf-8");
                 }
                 catch (err) {
-                    throw new Error(`Failed to read manifest for '${item.pkgId}': ${err.message}`);
+                    throw new ActionDockError(MANIFEST_READ_FAILED, `Failed to read manifest for '${item.pkgId}': ${err.message}`);
                 }
                 const depManifest = parseJsonWithoutDuplicates(manifestRaw);
                 const actualDigest = computeManifestDigest(depManifest);
                 if (locked?.manifestDigest && locked.manifestDigest !== actualDigest) {
-                    throw new Error(`Manifest digest mismatch for package '${item.pkgId}': expected '${locked.manifestDigest}', got '${actualDigest}'. Re-resolution required.`);
+                    throw new ActionDockError(MANIFEST_DIGEST_MISMATCH, `Manifest digest mismatch for package '${item.pkgId}': expected '${locked.manifestDigest}', got '${actualDigest}'. Re-resolution required.`);
                 }
                 const pkgVersion = depManifest.version || locked?.version || "0.1.0";
                 const reqs = versionRequirements.get(item.pkgId) || [];
@@ -580,10 +583,4 @@ export class PackageGraphBuilder {
         // 模式 C：全局包发现构建
         return this.buildFromGlobalDiscovery(nodes, generation);
     }
-    /**
-     * 异步构建包依赖拓扑图。
-     */
-    async build() {
-        return this.buildSync();
-    }
 }

package/dist/{profile/client-actions.d.ts → client/actions.d.ts}

@@ -1,5 +1,5 @@
 import type { ExecutionResult } from "@actiondock/sdk";
-import { type RemoteClientRequestOptions } from "./client-transport.js";
+import { type RemoteClientRequestOptions } from "./transport.js";
 /**
  * 远端 Action 执行与查询域端点。
  */

package/dist/{profile/client-actions.js → client/actions.js}

@@ -1,14 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { ACTION_CANCELLED, ACTION_TIMEOUT, NETWORK_ERROR } from "../errors.js";
-import { getInsecureDispatcher } from "../server/dispatcher.js";
-import { normalizeServerUrl } from "./manager.js";
-import { assertSecureTransport, buildHeaders, fetchRemoteRoute, } from "./client-transport.js";
-import { buildQueryString, fetchRemoteJson } from "./client-query.js";
+import { getInsecureDispatcher } from "./dispatcher.js";
+import { assertSecureTransport, buildHeaders, buildQueryString, fetchRemoteJson, fetchRemoteRoute, normalizeServerUrl, } from "./transport.js";
 /**
  * 执行远端 Action：支持幂等标识、异步触发、外部取消信号与本地超时守卫组合。
  */
 export async function executeRemoteAction(serverUrl, actionId, input = {}, configOverridesOrOptions, tokenArg) {
-    // Parse options / backwards compatibility
     let configOverrides;
     let token = tokenArg;
     let timeoutMs;
@@ -54,7 +51,6 @@ export async function executeRemoteAction(serverUrl, actionId, input = {}, confi
     if (requestId) {
         executionPayload.requestId = requestId;
     }
-    // 组合外部取消信号与本地超时守卫：服务端僵死时仍能在 timeoutMs 内本地中断，避免永久挂起
     let timeoutTimer;
     let localTimedOut = false;
     try {
@@ -116,7 +112,6 @@ export async function executeRemoteAction(serverUrl, actionId, input = {}, confi
             return data;
         }
         if (!res.ok) {
-            // 错误信封严禁伪造 runId：与任何真实运行无关的标识会让调用方查询永远 not_found
             return {
                 ok: false,
                 runId: "",
@@ -134,7 +129,6 @@ export async function executeRemoteAction(serverUrl, actionId, input = {}, confi
         };
     }
     catch (err) {
-        // 本地超时守卫触发时归类为超时；外部信号中止时归类为取消
         if (localTimedOut) {
             return {
                 ok: false,

package/dist/{profile/client-config.d.ts → client/config.d.ts}

@@ -1,4 +1,4 @@
-import type { RemoteClientRequestOptions } from "./client-transport.js";
+import type { RemoteClientRequestOptions } from "./transport.js";
 /**
  * 远端配置域端点。
  */

package/dist/{profile/client-config.js → client/config.js}

@@ -1,4 +1,4 @@
-import { buildQueryString, fetchRemoteJson } from "./client-query.js";
+import { buildQueryString, fetchRemoteJson } from "./transport.js";
 /**
  * 远端配置域端点。
  */

package/dist/client/dispatcher.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 获取用于忽略服务端证书校验的全局单例 Undici Agent 调度器。
+ */
+export declare function getInsecureDispatcher(): unknown;

package/dist/client/dispatcher.js

@@ -0,0 +1,21 @@
+import { Agent } from "undici";
+/**
+ * 全局单例 Undici Agent（忽略服务端证书校验）。
+ * 显式配置 bodyTimeout: 0 以防止 SSE 长连接与流式事件读取出现 UND_ERR_BODY_TIMEOUT 空闲超时断流。
+ * Agent 关闭或销毁后自动重建，保证长生命周期进程内的调度器始终可用。
+ */
+let globalInsecureAgent;
+/**
+ * 获取用于忽略服务端证书校验的全局单例 Undici Agent 调度器。
+ */
+export function getInsecureDispatcher() {
+    if (!globalInsecureAgent || globalInsecureAgent.closed || globalInsecureAgent.destroyed) {
+        globalInsecureAgent = new Agent({
+            connect: {
+                rejectUnauthorized: false,
+            },
+            bodyTimeout: 0,
+        });
+    }
+    return globalInsecureAgent;
+}

package/dist/client/health.d.ts

@@ -0,0 +1,38 @@
+import { type RemoteClientRequestOptions } from "./transport.js";
+import { type Clock } from "../storage/clock.js";
+/**
+ * 远端服务器健康探测与时延检测结果。
+ */
+export interface RemoteHealthResult {
+    /** 服务端是否连通且鉴权成功 */
+    ok: boolean;
+    /** 服务端状态标识（如 "ok"） */
+    status?: string;
+    /** 远端 ActionDock 版本号 */
+    version?: string;
+    /** 远端服务运行时间（秒） */
+    uptime?: number;
+    /** 网络往返延迟（毫秒） */
+    latencyMs: number;
+    /** 探测失败时的错误信息 */
+    error?: string;
+}
+/**
+ * 远端健康探测控制选项。
+ */
+export interface CheckRemoteHealthOptions extends RemoteClientRequestOptions {
+    /** 可选注入时钟抽象（缺省使用系统时钟） */
+    clock?: Clock;
+}
+/**
+ * 远端健康检查域端点。
+ */
+/**
+ * 探测指定远端 ActionDock 服务的健康状态与网络延迟。
+ *
+ * @param serverUrl 目标服务端地址
+ * @param token 鉴权 Token（可选）
+ * @param timeoutMs 探测超时时间（默认 5000ms）
+ * @param options 传输与安全控制选项
+ */
+export declare function checkRemoteHealth(serverUrl: string, token?: string, timeoutMs?: number, options?: CheckRemoteHealthOptions): Promise<RemoteHealthResult>;

package/dist/{profile/client-health.js → client/health.js}

@@ -1,6 +1,8 @@
-import { normalizeServerUrl } from "./manager.js";
-import { assertSecureTransport, buildHeaders, fetchRemoteRoute, } from "./client-transport.js";
-import { getInsecureDispatcher } from "../server/dispatcher.js";
+import { getInsecureDispatcher } from "./dispatcher.js";
+import { assertSecureTransport, buildHeaders, fetchRemoteRoute, normalizeServerUrl, } from "./transport.js";
+import { SystemClock } from "../storage/clock.js";
+/** 模块级默认时钟实例 */
+const defaultClock = new SystemClock();
 /**
  * 远端健康检查域端点。
  */
@@ -13,7 +15,8 @@ import { getInsecureDispatcher } from "../server/dispatcher.js";
  * @param options 传输与安全控制选项
  */
 export async function checkRemoteHealth(serverUrl, token, timeoutMs = 5000, options) {
-    const startTime = Date.now();
+    const clock = options?.clock ?? defaultClock;
+    const startTime = clock.monotonic();
     let timer;
     try {
         assertSecureTransport(serverUrl, token, {
@@ -35,7 +38,7 @@ export async function checkRemoteHealth(serverUrl, token, timeoutMs = 5000, opti
             fetchInit.tls = { rejectUnauthorized: false };
         }
         const res = await fetchRemoteRoute(normalizeServerUrl(serverUrl), "/api/v2/health", fetchInit);
-        const latencyMs = Date.now() - startTime;
+        const latencyMs = Math.round(clock.monotonic() - startTime);
         if (!res.ok) {
             const text = await res.text().catch(() => "");
             return {
@@ -54,7 +57,7 @@ export async function checkRemoteHealth(serverUrl, token, timeoutMs = 5000, opti
         };
     }
     catch (err) {
-        const latencyMs = Date.now() - startTime;
+        const latencyMs = Math.round(clock.monotonic() - startTime);
         return {
             ok: false,
             latencyMs,

package/dist/client/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ActionDock 核心远程 HTTP 客户端模块。
+ *
+ * 遵循架构收敛设计规范：按资源域组织，传输层单点。
+ * 彻底从 profile 目录解耦移入独立 client 模块。
+ */
+export { assertSecureTransport, buildHeaders, buildQueryString, buildQueryStringPreservingEmpty, createRemoteFetch, fetchRemoteJson, fetchRemoteRoute, normalizeServerUrl, } from "./transport.js";
+export type { RemoteClientRequestOptions, RemoteFetchInit, SecureTransportOptions, } from "./transport.js";
+export { checkRemoteHealth } from "./health.js";
+export type { RemoteHealthResult } from "./health.js";
+export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteDoctor, fetchRemoteInfo, } from "./actions.js";
+export type { RemoteExecuteOptions, RemoteExecutionResult } from "./actions.js";
+export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./playbooks.js";
+export { cancelRemoteRun, cleanExpiredRemoteRuns, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./runs.js";
+export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./state.js";
+export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigEnv, setRemoteConfig, } from "./config.js";

package/dist/client/index.js

@@ -0,0 +1,20 @@
+/**
+ * ActionDock 核心远程 HTTP 客户端模块。
+ *
+ * 遵循架构收敛设计规范：按资源域组织，传输层单点。
+ * 彻底从 profile 目录解耦移入独立 client 模块。
+ */
+// 1. 传输层单点
+export { assertSecureTransport, buildHeaders, buildQueryString, buildQueryStringPreservingEmpty, createRemoteFetch, fetchRemoteJson, fetchRemoteRoute, normalizeServerUrl, } from "./transport.js";
+// 2. 健康检查域
+export { checkRemoteHealth } from "./health.js";
+// 3. Action 执行与查询域
+export { executeRemoteAction, fetchRemoteActionShow, fetchRemoteActions, fetchRemoteDoctor, fetchRemoteInfo, } from "./actions.js";
+// 4. Playbook 规程查询域
+export { fetchRemotePlaybookShow, fetchRemotePlaybooks } from "./playbooks.js";
+// 5. 运行记录管理域
+export { cancelRemoteRun, cleanExpiredRemoteRuns, clearRemoteRuns, fetchRemoteRun, fetchRemoteRuns, } from "./runs.js";
+// 6. 状态存储管理域
+export { clearRemoteState, deleteRemoteStateKey, fetchRemoteStateList, getRemoteStateKey, setRemoteStateKey, } from "./state.js";
+// 7. 配置管理域
+export { deleteRemoteConfig, fetchRemoteConfig, fetchRemoteConfigEnv, setRemoteConfig, } from "./config.js";

package/dist/{profile/client-playbooks.d.ts → client/playbooks.d.ts}

@@ -1,4 +1,4 @@
-import type { RemoteClientRequestOptions } from "./client-transport.js";
+import type { RemoteClientRequestOptions } from "./transport.js";
 /**
  * 远端 Playbook 规程域端点。
  */

package/dist/{profile/client-playbooks.js → client/playbooks.js}

@@ -1,4 +1,4 @@
-import { buildQueryString, fetchRemoteJson } from "./client-query.js";
+import { buildQueryString, fetchRemoteJson } from "./transport.js";
 /**
  * 远端 Playbook 规程域端点。
  */

package/dist/{profile/client-runs.d.ts → client/runs.d.ts}

@@ -1,5 +1,5 @@
 import type { RunRecord } from "@actiondock/sdk";
-import type { RemoteClientRequestOptions } from "./client-transport.js";
+import type { RemoteClientRequestOptions } from "./transport.js";
 /**
  * 远端运行记录域端点。
  */
@@ -24,9 +24,11 @@ export declare function fetchRemoteRuns(serverUrl: string, token?: string, optio
     packageId?: string;
     intent?: string;
     limit?: number;
+    offset?: number;
+    requestIds?: string[];
 } & RemoteClientRequestOptions): Promise<{
     ok: boolean;
-    total: number;
+    total?: number;
     items: RunRecord[];
 }>;
 /**

package/dist/{profile/client-runs.js → client/runs.js}

@@ -1,4 +1,4 @@
-import { buildQueryString, fetchRemoteJson } from "./client-query.js";
+import { buildQueryString, fetchRemoteJson } from "./transport.js";
 /**
  * 远端运行记录域端点。
  */
@@ -11,6 +11,7 @@ export async function fetchRemoteRun(serverUrl, runId, token, options) {
         allowInsecureHttp: options?.allowInsecureHttp,
         insecure: options?.insecure,
         dispatcher: options?.dispatcher,
+        signal: options?.signal,
     });
 }
 /**
@@ -36,11 +37,16 @@ export async function fetchRemoteRuns(serverUrl, token, options) {
         packageId: options?.packageId,
         intent: options?.intent,
         limit: options?.limit,
+        offset: options?.offset,
+        requestIds: options?.requestIds && options.requestIds.length > 0
+            ? options.requestIds
+            : undefined,
     })}`, token, {
         errorPrefix: "Failed to fetch remote runs",
         allowInsecureHttp: options?.allowInsecureHttp,
         insecure: options?.insecure,
         dispatcher: options?.dispatcher,
+        signal: options?.signal,
     });
 }
 /**

package/dist/{profile/client-state.d.ts → client/state.d.ts}

@@ -1,4 +1,4 @@
-import type { RemoteClientRequestOptions } from "./client-transport.js";
+import type { RemoteClientRequestOptions } from "./transport.js";
 /**
  * 远端状态存储域端点。
  */

package/dist/{profile/client-state.js → client/state.js}

@@ -1,4 +1,4 @@
-import { buildQueryStringPreservingEmpty, fetchRemoteJson } from "./client-query.js";
+import { buildQueryStringPreservingEmpty, fetchRemoteJson } from "./transport.js";
 /**
  * 远端状态存储域端点。
  */

package/dist/{profile/client-transport.d.ts → client/transport.d.ts}

@@ -1,8 +1,9 @@
 /**
- * 远端客户端传输层。
+ * 远端客户端传输层单点。
  *
- * 职责单一聚焦：鉴权头拼装、明文传输安全校验与 insecure dispatcher 注入，
- * 作为全部远端端点函数的传输样板单一事实源。
+ * 职责单一聚焦：服务端地址规范化、鉴权头拼装、明文传输安全校验、
+ * insecure dispatcher 注入、JSON 响应解析与查询参数序列化，
+ * 作为全部远端端点函数的统一传输层单一事实源。
  */
 /**
  * 传输层安全豁免控制选项。
@@ -13,12 +14,15 @@ export interface SecureTransportOptions {
     /** 是否跳过 TLS 证书合法性校验 */
     insecure?: boolean;
 }
+/**
+ * 格式化并规范化 Server URL 地址（若未指定协议，本地回环地址默认使用 http://，非本地回环地址默认使用 https://，并移除末尾斜杠）。
+ */
+export declare function normalizeServerUrl(url: string): string;
 /**
  * 校验在携带认证 Token 时传输层协议与目标地址是否安全。
  * 若请求携带认证 Token 且目标为非本地回环的明文 http://，默认报错拒绝。
  * 可通过 allowInsecureHttp 选项、insecure 选项、环境变量或命令行参数豁免明文限制。
- * 目标 URL 无法解析时无论豁免与否均 fail-closed 抛 INVALID_ARGUMENT，
- * 杜绝携凭据请求发往不可控的畸形地址。
+ * 目标 URL 无法解析时无论豁免与否均 fail-closed 抛 INVALID_ARGUMENT。
  */
 export declare function assertSecureTransport(serverUrl: string, token?: string, options?: SecureTransportOptions): void;
 /**
@@ -35,6 +39,8 @@ export interface RemoteClientRequestOptions {
     insecure?: boolean;
     /** 自定义底层 HTTP 调度器（平台中立） */
     dispatcher?: unknown;
+    /** 取消信号，用于中止 HTTP 请求 */
+    signal?: AbortSignal;
 }
 /** 远端请求描述选项。 */
 export interface RemoteFetchInit {
@@ -49,15 +55,28 @@ export interface RemoteFetchInit {
 }
 /**
  * 构建绑定传输上下文（Token、安全选项与调度器）的远端请求函数。
- *
- * 单一事实源收敛所有 fetchRemoteXxx 端点的传输样板：
- * 调用方仅需声明 path 与查询参数，鉴权头拼装、明文传输校验与
- * insecure dispatcher 注入均在此统一处理。
  */
 export declare function createRemoteFetch(serverUrl: string, token?: string, options?: RemoteClientRequestOptions): (path: string, init?: RemoteFetchInit) => Promise<Response>;
 /**
- * 远端请求单一入口：执行目标协议路由请求。
+ * 远端请求底层入口：执行目标协议路由请求。
  */
 export declare function fetchRemoteRoute(base: string, path: string, init: RequestInit & {
     dispatcher?: any;
 }): Promise<Response>;
+/**
+ * 执行远端请求并将响应解析为 JSON，统一处理错误信封透传。
+ */
+export declare function fetchRemoteJson<T = any>(serverUrl: string, path: string, token?: string, options?: {
+    method?: string;
+    body?: unknown;
+    errorPrefix?: string;
+} & RemoteClientRequestOptions): Promise<T>;
+/**
+ * 由可选参数字典构造查询串（无参数时返回空串）。
+ * 过滤 undefined 与空串。
+ */
+export declare function buildQueryString(params: Record<string, string | number | boolean | readonly (string | number | boolean)[] | undefined>): string;
+/**
+ * 构造保留空串语义的查询串：仅跳过 undefined，保留空串。
+ */
+export declare function buildQueryStringPreservingEmpty(params: Record<string, string | number | boolean | readonly (string | number | boolean)[] | undefined>): string;