@gt-fe/eap-runtime 0.0.16 → 0.0.18

package/README.md

@@ -256,7 +256,7 @@ FOUNDATION_SERVICE_URL=...
 EAP_DEPLOYMENT_CONTEXT=dev
 EAP_PREINSTALL_ROOT=/abs/path/to/preinstall   # 或 Agent 工程内预装树
 EAP_RUNTIME_STORAGE_PROFILE=dev
-EAP_TOOL_EXECUTION_MODE=mcp                  # 本地默认；http-debug 走 Gateway 调试口
+EAP_TOOL_EXECUTION_MODE=mcp                  # 仅 createDevRuntime / eap chat；Hosting 的 TOOL_EXECUTION_MODE 不读
 # OPENAI_BASE_URL / OPENAI_API_KEY / EAP_DEFAULT_MODEL
 ```
 
@@ -277,26 +277,28 @@ EAP_TOOL_EXECUTION_MODE=mcp                  # 本地默认；http-debug 走 Gat
 
 ---
 
-## 11. 发布到公司私有 npm（可选）
+## 11. 发布 npm 包
 
-私服：`https://maven.gtcloud.cn/repository/npm-local/`（模板 [`.npmrc.example`](./.npmrc.example)）。
+升版、CHANGELOG、`git commit` / `git push` 不在脚本里，先做完再跑脚本。脚本只做构建、发布、核对 registry 上的版本号。
 
-> `@eap:registry=...` 须写入 `.npmrc` 文件，不可在 shell 中作为命令直接执行。
+| 脚本 | 包 | registry |
+|------|----|----------|
+| [`scripts/publish-intranet.sh`](./scripts/publish-intranet.sh) | `@eap/runtime` | Nexus `https://maven.gtcloud.cn/repository/npm-local/` |
+| [`scripts/publish-public.sh`](./scripts/publish-public.sh) | `@gt-fe/eap-runtime` | npmjs。临时目录改名；dist 里 `@eap/contracts` 改为 `@gt-fe/eap-contracts`。不改源码 `package.json` |
 
 ```bash
+# 登录（一次性）
 cp .npmrc.example .npmrc
 npm login --registry https://maven.gtcloud.cn/repository/npm-local/
+npm login --registry https://registry.npmjs.org/
 
-# 1) 先发 @eap/contracts（version 改为目标版，如 0.0.1）
-cd ../eap-contracts && cp .npmrc.example .npmrc
-pnpm run build && npm publish --registry https://maven.gtcloud.cn/repository/npm-local/
-
-# 2) runtime：package.json 中 @eap/contracts 改为版本号（勿再用 file:）
-cd ../runtime && pnpm run build
-npm publish --registry https://maven.gtcloud.cn/repository/npm-local/
+./scripts/publish-intranet.sh
+./scripts/publish-public.sh
 ```
 
-含 `_authToken` 的 `.npmrc` 已 gitignore，勿提交凭证。
+不要在源码目录对 npmjs 执行 `npm publish`（`publishConfig` 指向 Nexus；公网 dist 必须改写 contracts）。含 `_authToken` 的 `.npmrc` 已 gitignore，勿提交凭证。`@eap:registry=...` 须写入 `.npmrc` 文件，不可在 shell 中当命令执行。
+
+UAT Hosting 吃公网包：把 `@eap/runtime` 指到 `npm:@gt-fe/eap-runtime@<本版>` 后重建镜像。
 
 ---
 

package/dist/checkpoint/checkpoint-serializer.d.ts

@@ -40,13 +40,17 @@ export interface CreateCheckpointParams {
  * 确保所有必要字段的一致性。
  */
 export declare function createCheckpointData(params: CreateCheckpointParams): CheckpointData;
+/**
+ * 落盘用快照：可 JSON 往返的数据留下；定时器 / 函数 / 环丢掉。
+ * 环用栈判定，同一对象出现两次但不成环（菱形）仍保留。
+ */
+export declare function toJsonSafe(value: unknown, stack?: Set<object>): unknown;
+/** 所有 Checkpoint Saver 落盘共用，禁止裸 JSON.stringify(state)。 */
+export declare function stringifyJsonSafe(value: unknown): string;
 /**
  * 序列化 CheckpointData 为 JSON 字符串
  *
- * 处理边界情况：
- * - Date 对象 → ISO 字符串
- * - undefined 值自动剔除（JSON.stringify 默认行为）
- * - 循环引用检测（抛出明确错误而非默认 TypeError）
+ * Date → ISO；定时器 / 循环引用省略，不抛 TypeError。
  */
 export declare function serializeCheckpoint(data: CheckpointData): string;
 /**

package/dist/checkpoint/checkpoint-serializer.js

@@ -37,30 +37,69 @@ export function createCheckpointData(params) {
 // ─────────────────────────────────────────────
 // 序列化 / 反序列化
 // ─────────────────────────────────────────────
+function isTimerHandle(value) {
+    const name = value.constructor?.name;
+    if (name === 'Timeout' || name === 'TimersList' || name === 'Immediate')
+        return true;
+    return Object.prototype.hasOwnProperty.call(value, '_idlePrev')
+        && Object.prototype.hasOwnProperty.call(value, '_idleNext');
+}
+/**
+ * 落盘用快照：可 JSON 往返的数据留下；定时器 / 函数 / 环丢掉。
+ * 环用栈判定，同一对象出现两次但不成环（菱形）仍保留。
+ */
+export function toJsonSafe(value, stack = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value === 'undefined' || typeof value === 'function' || typeof value === 'symbol') {
+        return undefined;
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value !== 'object')
+        return undefined;
+    if (isTimerHandle(value))
+        return undefined;
+    if (stack.has(value))
+        return undefined;
+    const maybeToJSON = value.toJSON;
+    if (typeof maybeToJSON === 'function') {
+        return toJsonSafe(maybeToJSON.call(value), stack);
+    }
+    if (Array.isArray(value)) {
+        stack.add(value);
+        const out = value.map((item) => {
+            const next = toJsonSafe(item, stack);
+            return next === undefined ? null : next;
+        });
+        stack.delete(value);
+        return out;
+    }
+    stack.add(value);
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        const next = toJsonSafe(child, stack);
+        if (next !== undefined)
+            out[key] = next;
+    }
+    stack.delete(value);
+    return out;
+}
+/** 所有 Checkpoint Saver 落盘共用，禁止裸 JSON.stringify(state)。 */
+export function stringifyJsonSafe(value) {
+    return JSON.stringify(toJsonSafe(value));
+}
 /**
  * 序列化 CheckpointData 为 JSON 字符串
  *
- * 处理边界情况：
- * - Date 对象 → ISO 字符串
- * - undefined 值自动剔除（JSON.stringify 默认行为）
- * - 循环引用检测（抛出明确错误而非默认 TypeError）
+ * Date → ISO；定时器 / 循环引用省略，不抛 TypeError。
  */
 export function serializeCheckpoint(data) {
-    const seen = new WeakSet();
-    return JSON.stringify(data, (_key, value) => {
-        // Date → ISO 字符串
-        if (value instanceof Date) {
-            return value.toISOString();
-        }
-        // 循环引用检测
-        if (typeof value === 'object' && value !== null) {
-            if (seen.has(value)) {
-                throw new Error(`[CheckpointSerializer] Circular reference detected during serialization`);
-            }
-            seen.add(value);
-        }
-        return value;
-    });
+    return stringifyJsonSafe(data);
 }
 /**
  * 反序列化 JSON 字符串为 CheckpointData

package/dist/checkpoint/file-checkpoint-saver.js

@@ -4,6 +4,7 @@
  */
 import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { stringifyJsonSafe } from './checkpoint-serializer.js';
 export class FileCheckpointSaver {
     baseDir;
     constructor(baseDir) {
@@ -12,7 +13,7 @@ export class FileCheckpointSaver {
     async save(threadId, data) {
         const dir = join(this.baseDir, threadId);
         await mkdir(dir, { recursive: true });
-        await writeFile(join(dir, `${data.checkpointId}.json`), JSON.stringify(data));
+        await writeFile(join(dir, `${data.checkpointId}.json`), stringifyJsonSafe(data));
         // 更新 latest 指针
         await writeFile(join(dir, 'latest.json'), JSON.stringify({ checkpointId: data.checkpointId }));
     }

package/dist/checkpoint/index.d.ts

@@ -4,7 +4,7 @@ export type { RedisCheckpointSaverOptions } from './redis-checkpoint-saver.js';
 export { CompositeCheckpointSaver } from './composite-checkpoint-saver.js';
 export { restoreCheckpoint } from './restore-checkpoint.js';
 export { notifyCheckpointRef, stripCheckpointCollectors } from './checkpoint-ref-notify.js';
-export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, } from './checkpoint-serializer.js';
+export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, stringifyJsonSafe, toJsonSafe, } from './checkpoint-serializer.js';
 export type { CreateCheckpointParams } from './checkpoint-serializer.js';
 export { FileCheckpointSaver } from './file-checkpoint-saver.js';
 export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';

package/dist/checkpoint/index.js

@@ -4,7 +4,7 @@ export { RedisCheckpointSaver } from './redis-checkpoint-saver.js';
 export { CompositeCheckpointSaver } from './composite-checkpoint-saver.js';
 export { restoreCheckpoint } from './restore-checkpoint.js';
 export { notifyCheckpointRef, stripCheckpointCollectors } from './checkpoint-ref-notify.js';
-export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, } from './checkpoint-serializer.js';
+export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, stringifyJsonSafe, toJsonSafe, } from './checkpoint-serializer.js';
 export { FileCheckpointSaver } from './file-checkpoint-saver.js';
 export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';
 export { MongoCheckpointSaver } from './mongo-checkpoint-saver.js';

package/dist/checkpoint/pg-checkpoint-saver.js

@@ -7,6 +7,7 @@
  * @see design.md §1.3 checkpoints 数据模型
  * @see checkpoint-saver.contract.ts ICheckpointSaver 接口定义
  */
+import { stringifyJsonSafe } from './checkpoint-serializer.js';
 // ─────────────────────────────────────────────
 // PostgresCheckpointSaver
 // ─────────────────────────────────────────────
@@ -38,9 +39,9 @@ export class PostgresCheckpointSaver {
             threadId,
             data.checkpointId,
             data.currentNodeId,
-            JSON.stringify(data.historyPath),
-            JSON.stringify(data.state),
-            data.engineSnapshot == null ? null : JSON.stringify(data.engineSnapshot),
+            stringifyJsonSafe(data.historyPath),
+            stringifyJsonSafe(data.state),
+            data.engineSnapshot == null ? null : stringifyJsonSafe(data.engineSnapshot),
             data.createdBy || 'system',
             data.createdAt,
             data.updatedBy || 'system',

package/dist/checkpoint/redis-checkpoint-saver.js

@@ -9,6 +9,7 @@
  *
  * @see design.md §1.3 checkpoints 数据模型
  */
+import { stringifyJsonSafe } from './checkpoint-serializer.js';
 /**
  * RedisCheckpointSaver — ICheckpointSaver 的 Redis 实现
  *
@@ -52,7 +53,7 @@ export class RedisCheckpointSaver {
         const idxKey = this.threadIndexKey(threadId);
         const ltKey = this.latestKey(threadId);
         const revKey = this.reverseIndexKey(data.checkpointId);
-        const json = JSON.stringify(data);
+        const json = stringifyJsonSafe(data);
         const score = new Date(data.createdAt).getTime();
         const pipeline = this.redis.pipeline();
         // 存储 Checkpoint JSON

package/dist/tool/create-tool-executor.d.ts

@@ -1,9 +1,11 @@
 /**
  * createToolExecutor — 按部署上下文组装 Router + Gateway/Local 执行器
  *
- * server / hosting：**默认 MCP**（McpToolExecutor → POST /api/v1/mcp）；
+ * server / hosting：**默认 MCP**（McpToolExecutor → POST {绝对基址}/api/v1/mcp）；
  * `EAP_TOOL_GATEWAY_TRANSPORT=http` 时用 HttpToolExecutor（仅调试）。
  * desktop 经 ToolExecutionRouter 分流 Local / Gateway。
+ * desktop|dev 且 foundationUrl 不是绝对 http(s)：不创建 Gateway 客户端，只挂 LocalToolExecutor。
+ * 不读 Hosting 的 TOOL_EXECUTION_MODE。
  */
 import type { ILocalToolInstallStore, LocalToolInstallRecord } from '@gt-fe/eap-contracts';
 import { type DeploymentContext } from './tool-execution-router.js';

package/dist/tool/create-tool-executor.js

@@ -1,12 +1,14 @@
 /**
  * createToolExecutor — 按部署上下文组装 Router + Gateway/Local 执行器
  *
- * server / hosting：**默认 MCP**（McpToolExecutor → POST /api/v1/mcp）；
+ * server / hosting：**默认 MCP**（McpToolExecutor → POST {绝对基址}/api/v1/mcp）；
  * `EAP_TOOL_GATEWAY_TRANSPORT=http` 时用 HttpToolExecutor（仅调试）。
  * desktop 经 ToolExecutionRouter 分流 Local / Gateway。
+ * desktop|dev 且 foundationUrl 不是绝对 http(s)：不创建 Gateway 客户端，只挂 LocalToolExecutor。
+ * 不读 Hosting 的 TOOL_EXECUTION_MODE。
  */
 import { HttpToolExecutor } from './http-tool-executor.js';
-import { McpToolExecutor } from './mcp-tool-executor.js';
+import { isAbsoluteHttpUrl, McpToolExecutor } from './mcp-tool-executor.js';
 import { LocalToolExecutor } from './local-tool-executor.js';
 import { ToolExecutionRouter, } from './tool-execution-router.js';
 import { withHarnessPrimitives } from './harness-primitives.js';
@@ -46,14 +48,19 @@ function createServerExecutor(foundationUrl, transport, timeout) {
  */
 export function createToolExecutor(options) {
     const installStore = options.installStore ?? new EmptyInstallStore();
+    const localExecutor = new LocalToolExecutor({ installStore });
+    const deploymentContext = resolveDeploymentContext(options.deploymentContext);
+    const hasGateway = isAbsoluteHttpUrl(options.foundationUrl);
+    if (!hasGateway && (deploymentContext === 'desktop' || deploymentContext === 'dev')) {
+        return withHarnessPrimitives(localExecutor);
+    }
     const transport = resolveGatewayTransport(options.gatewayTransport);
     const serverExecutor = createServerExecutor(options.foundationUrl, transport, options.httpTimeout);
-    const localExecutor = new LocalToolExecutor({ installStore });
     return withHarnessPrimitives(new ToolExecutionRouter({
         httpExecutor: serverExecutor,
         localExecutor,
         installStore,
-        deploymentContext: resolveDeploymentContext(options.deploymentContext),
+        deploymentContext,
         toolTypes: options.toolTypes,
         toolRuntimes: options.toolRuntimes,
         forceToolServer: options.forceToolServer,

package/dist/tool/index.d.ts

@@ -3,7 +3,7 @@ export { hydrateMcpTools, isMcpDiscoverStub, needsMcpHydration, parseListedTools
 export { toLoadedToolMap, type LoadedToolDefinition, type LoadedToolMap, type LoadedToolManifestRef, } from './loaded-tool-definition.js';
 export { ToolOrchestrator } from './tool-orchestrator.js';
 export { HttpToolExecutor, type HttpToolExecutorOptions, } from './http-tool-executor.js';
-export { McpToolExecutor, type McpToolExecutorOptions, } from './mcp-tool-executor.js';
+export { McpToolExecutor, isAbsoluteHttpUrl, type McpToolExecutorOptions, } from './mcp-tool-executor.js';
 export { LocalToolExecutor, isLocalPreferredExecution, resolveCodeExecutionFromRequest } from './local-tool-executor.js';
 export { DevMcpExecutor, type DevMcpExecutorOptions, } from './dev-mcp-executor.js';
 export { DevHttpExecutor, buildHttpToolUrl, resolveHttpExecutionFromRequest, type DevHttpExecution, } from './dev-http-executor.js';

package/dist/tool/index.js

@@ -2,7 +2,7 @@ export { hydrateMcpTools, isMcpDiscoverStub, needsMcpHydration, parseListedTools
 export { toLoadedToolMap, } from './loaded-tool-definition.js';
 export { ToolOrchestrator } from './tool-orchestrator.js';
 export { HttpToolExecutor, } from './http-tool-executor.js';
-export { McpToolExecutor, } from './mcp-tool-executor.js';
+export { McpToolExecutor, isAbsoluteHttpUrl, } from './mcp-tool-executor.js';
 export { LocalToolExecutor, isLocalPreferredExecution, resolveCodeExecutionFromRequest } from './local-tool-executor.js';
 export { DevMcpExecutor, } from './dev-mcp-executor.js';
 export { DevHttpExecutor, buildHttpToolUrl, resolveHttpExecutionFromRequest, } from './dev-http-executor.js';

package/dist/tool/mcp-tool-executor.d.ts

@@ -4,6 +4,8 @@
  * @see docs/contracts/tool-execution.md §2.0
  */
 import type { IToolExecutor, McpListedTool, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+/** Tool Gateway 基址：必须是绝对 http(s)。空串 / 相对路径禁止 fetch。 */
+export declare function isAbsoluteHttpUrl(value: unknown): boolean;
 export interface McpToolExecutorOptions {
     baseUrl: string;
     timeout?: number;

package/dist/tool/mcp-tool-executor.js

@@ -4,8 +4,24 @@
  * @see docs/contracts/tool-execution.md §2.0
  */
 import { ErrorCodes } from '@gt-fe/eap-contracts';
+import { emitRuntimeLog } from '../common/logger.js';
 import { abortOrTimeoutMessage, isAbortError } from './timeout.js';
 import { nextListCursor, parseListedTools } from './mcp-list.js';
+/** Tool Gateway 基址：必须是绝对 http(s)。空串 / 相对路径禁止 fetch。 */
+export function isAbsoluteHttpUrl(value) {
+    if (typeof value !== 'string')
+        return false;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return false;
+    try {
+        const url = new URL(trimmed);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
 function resolveAgentCode(request) {
     return request.authContext.agentCode;
 }
@@ -49,7 +65,14 @@ export class McpToolExecutor {
     /** endpoint+user+agent → in-flight / completed tools/list */
     listCache = new Map();
     constructor(options) {
-        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        if (!isAbsoluteHttpUrl(options.baseUrl)) {
+            emitRuntimeLog('warn', 'tool', 'McpToolExecutor 基址不是绝对 http(s)，拒绝请求', {
+                event: 'runtime.tool.gateway_base_invalid',
+                baseUrl: options.baseUrl,
+            });
+            throw new Error(`McpToolExecutor 需要绝对 http(s) 基址，收到 ${JSON.stringify(options.baseUrl ?? '')}`);
+        }
+        this.baseUrl = options.baseUrl.trim().replace(/\/+$/, '');
         this.timeout = options.timeout ?? 30_000;
         const path = options.mcpPath ?? '/api/v1/mcp';
         this.mcpUrl = `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gt-fe/eap-runtime",
-  "version": "0.0.16",
-  "description": "Enterprise Agent Platform \u2014 Runtime\u6838\u5fc3\uff1aGraph\u6267\u884c\u5f15\u64ce\u3001Task\u751f\u547d\u5468\u671f\u3001Session\u7ba1\u7406\u3001Checkpoint\u6301\u4e45\u5316",
+  "version": "0.0.18",
+  "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",