@gt-fe/eap-runtime 0.0.36 → 0.0.37

package/dist/graph/adapters/langgraph.adapter.js

@@ -1172,6 +1172,7 @@ export class LangGraphAdapter {
                     },
                     correlationId: typeof state['correlationId'] === 'string' ? state['correlationId'] : undefined,
                     taskId: typeof state['taskId'] === 'string' ? state['taskId'] : undefined,
+                    sessionId: typeof state['sessionId'] === 'string' ? state['sessionId'] : undefined,
                     onListFailure: ({ toolset, error }) => {
                         this.emitToolExecutionEvents({
                             toolCallId: `mcp-list:${toolset}`,

package/dist/registry/graph-loader.js

@@ -270,6 +270,26 @@ function resolveMcpServer(manifest) {
     }
     return undefined;
 }
+function mcpKnownToolNames(manifest) {
+    const tools = manifest.tools;
+    if (!Array.isArray(tools))
+        return [];
+    const names = [];
+    const seen = new Set();
+    for (const tool of tools) {
+        if (!tool || typeof tool !== 'object')
+            continue;
+        const name = tool.name;
+        if (typeof name !== 'string')
+            continue;
+        const trimmed = name.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        names.push(trimmed);
+    }
+    return names;
+}
 /** 门户把同一次注册的「用户确认」写在每个 tools[] 上。MCP 不展开这份清单，占位记录读这个值。 */
 function mcpToolsRequireConfirmation(manifest) {
     const tools = manifest.tools;
@@ -301,6 +321,7 @@ function mcpDiscoverStub(pre, options) {
     if (options?.autoApprove && options.autoApprove.length > 0) {
         execution.autoApprove = options.autoApprove;
     }
+    execution.knownTools = mcpKnownToolNames(m);
     return {
         toolId: pre.toolId,
         name: pre.name,

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

@@ -73,7 +73,8 @@ export class DevMcpExecutor {
         const url = execution.server?.url ?? '';
         const cmd = execution.server?.command ?? '';
         const args = (execution.server?.args ?? []).join('\0');
-        const key = `${url || `stdio:${cmd}:${args}`}\0${request.authContext?.userId ?? ''}\0${request.authContext?.agentCode ?? ''}`;
+        const scope = request.sessionId?.trim() || request.taskId?.trim() || '';
+        const key = `${url || `stdio:${cmd}:${args}`}\0${request.authContext?.userId ?? ''}\0${request.authContext?.agentCode ?? ''}\0${scope}`;
         const cached = this.listCache.get(key);
         if (cached)
             return cached;

package/dist/tool/harness-primitives.d.ts

@@ -1,5 +1,5 @@
 /**
- * 平台默认 Harness 原语：read_file / write_file / execute_command。
+ * 平台默认 Harness 原语：read_file / write_file / append_to_file / execute_command / datetime_to_unix / unix_to_datetime。
  *
  * 不写进 agent.manifest.toolsets。同名业务工具优先（问数 file-io 等）。
  * 写：`dirname(agentDir)/users/<userId>/`（含用户自己的 skills）。产物默认 `files/`，公开副本 `public/`。
@@ -56,6 +56,7 @@ export declare class HarnessPrimitiveExecutor implements IToolExecutor {
     private extraRootsFor;
     private requireWorkdir;
     execute(request: ToolCallRequest): Promise<ToolCallResult>;
+    private convertTime;
     private readFile;
     private writeFile;
     private executeCommand;

package/dist/tool/harness-primitives.js

@@ -1,5 +1,5 @@
 /**
- * 平台默认 Harness 原语：read_file / write_file / execute_command。
+ * 平台默认 Harness 原语：read_file / write_file / append_to_file / execute_command / datetime_to_unix / unix_to_datetime。
  *
  * 不写进 agent.manifest.toolsets。同名业务工具优先（问数 file-io 等）。
  * 写：`dirname(agentDir)/users/<userId>/`（含用户自己的 skills）。产物默认 `files/`，公开副本 `public/`。
@@ -20,6 +20,7 @@ import { MAX_SNAPSHOT_ENUM, MAX_SNAPSHOT_URLS, PUBLIC_FILE_MODE, ensureUserSlots
 import { BUILTIN_TOOL_SOURCE, DEFAULT_BUILTIN_TIMEOUT_MS, MAX_BUILTIN_TIMEOUT_MS, clampBuiltinTimeout, isBuiltinToolExecution, resolveBuiltinToolsConfig, } from '@gt-fe/eap-contracts';
 import { ensureInterpreterShims, formatSpawnError, killProcessTree, resolveShellSpawn, sandboxEnv, spawnOptionsFor, substituteSkillDir, } from './harness-command.js';
 import { expandSkillScriptRefs, isSkillEntryFile } from './skill-script-refs.js';
+import { resolveDatetimeToUnix, resolveUnixToDatetime } from './unix-time.js';
 /** 超时杀进程或 spawn 失败后等 `close`；未到则最多再等此时长再快照。 */
 const SPAWN_CLOSE_GRACE_MS = 1000;
 function builtinConfig() {
@@ -140,6 +141,64 @@ function harnessDefinitions() {
                 },
             },
         },
+        {
+            toolId: 'builtin:datetime_to_unix',
+            name: 'datetime_to_unix',
+            manifest: {
+                id: 'builtin:datetime_to_unix',
+                name: 'datetime_to_unix',
+                description: '把日期或时刻换成 Unix 秒和毫秒。已有时间戳要换成日期时用 unix_to_datetime。返回 JSON：timezone、datetime、unix_seconds、unix_milliseconds；只写日期时另有 note。unix_seconds 与 unix_milliseconds 是数字字符串。按秒的参数填 unix_seconds，按毫秒的参数填 unix_milliseconds。',
+                ...common,
+            },
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    datetime: {
+                        type: 'string',
+                        description: '要换算的日期或时刻。省略或空字符串表示现在。只写日期按 timezone 当天 00:00:00，如 2027-01-01、2027年1月1日、2027/01/01。时刻如 2027-01-01 11:00，T 与空格相同。毫秒写在秒后，1 到 3 位，.1 表示 100 毫秒。不要写 Z、+08:00 或数字。',
+                    },
+                    timezone: {
+                        type: 'string',
+                        description: 'IANA 时区名，如 Asia/Shanghai、UTC、America/New_York。省略则用环境段的「时区」。',
+                    },
+                },
+            },
+        },
+        {
+            toolId: 'builtin:unix_to_datetime',
+            name: 'unix_to_datetime',
+            manifest: {
+                id: 'builtin:unix_to_datetime',
+                name: 'unix_to_datetime',
+                description: '把 Unix 时间戳换成日期文字。日期换时间戳用 datetime_to_unix。返回 JSON：timezone、unit、formatted、format、unix_seconds、unix_milliseconds。',
+                ...common,
+            },
+            inputSchema: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['timestamp'],
+                properties: {
+                    timestamp: {
+                        type: 'string',
+                        description: '整数字符串。秒如 1798732800，毫秒如 1798732800000。不要传日期。',
+                    },
+                    unit: {
+                        type: 'string',
+                        enum: ['s', 'ms'],
+                        description: 's 为秒，ms 为毫秒。省略时，绝对值达到 1000000000000（13 位）视为毫秒，否则视为秒。',
+                    },
+                    timezone: {
+                        type: 'string',
+                        description: 'IANA 时区名，如 Asia/Shanghai、UTC、America/New_York。省略则用环境段的「时区」。',
+                    },
+                    format: {
+                        type: 'string',
+                        description: 'formatted 的写法，默认 YYYY-MM-DD HH:mm:ss。记号只有 YYYY、MM（月）、DD、HH、mm（分）、ss、SSS。分钟写 mm。',
+                    },
+                },
+            },
+        },
     ];
 }
 export function mergeHarnessPrimitives(loadedTools) {
@@ -401,6 +460,10 @@ export class HarnessPrimitiveExecutor {
                     return await this.writeFile(request, true);
                 case 'execute_command':
                     return await this.executeCommand(request);
+                case 'datetime_to_unix':
+                    return this.convertTime(request, resolveDatetimeToUnix);
+                case 'unix_to_datetime':
+                    return this.convertTime(request, resolveUnixToDatetime);
                 default:
                     return fail(request, `未知 Harness 原语：${request.toolName}`);
             }
@@ -409,6 +472,12 @@ export class HarnessPrimitiveExecutor {
             return fail(request, err instanceof Error ? err.message : String(err));
         }
     }
+    convertTime(request, resolve) {
+        const resolved = resolve(request.arguments);
+        if (!resolved.ok)
+            return fail(request, resolved.error);
+        return ok(request, JSON.stringify(resolved.value));
+    }
     async readFile(request) {
         const filePath = String(request.arguments.path ?? '');
         const workdir = this.workdirFor(request);

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

@@ -25,6 +25,8 @@ export interface McpDiscoverExecution {
     bundlePath?: string;
     enabledTools?: string[];
     autoApprove?: string[];
+    /** 预装清单里已有的子工具名。缺省表示沿用 stub 的确认规则。 */
+    knownTools?: string[];
 }
 export declare function readMcpDiscoverExecution(raw: unknown): McpDiscoverExecution | null;
 export declare function isMcpDiscoverStub(def: LoadedToolDefinition): boolean;
@@ -71,6 +73,7 @@ export interface HydrateMcpToolsAuth {
     authContext: AuthContext;
     correlationId?: string;
     taskId?: string;
+    sessionId?: string;
     onListFailure?: (failure: {
         toolset: string;
         endpoint: string;
@@ -79,10 +82,13 @@ export interface HydrateMcpToolsAuth {
 }
 /**
  * 将 MCP discover stub 替换为 tools/list 结果。
- * 无 stub 时原样返回（同一引用）。按 endpoint+user+agent 在执行器内缓存 list。
+ * 无 stub 时原样返回（同一引用）。执行器按会话缓存 list。
  * enabledTools 为可选白名单；autoApprove 的子工具 requireConfirmation=false。
+ * knownTools 之外的新工具，不是只读时要用户确认。
  * 单个 endpoint 的 list 失败只跳过该工具集；全部失败才抛错（错误含工具集名）。
  */
 export declare function hydrateMcpTools(loadedTools: LoadedToolMap | undefined, executor: IToolExecutor | undefined, auth: HydrateMcpToolsAuth): Promise<LoadedToolMap | undefined>;
+/** 登记过的名字沿用 stub；新名字在不是只读时要确认。没有 knownTools 时全部沿用 stub。 */
+export declare function mcpChildNeedsConfirmation(tool: McpListedTool, stub: LoadedToolDefinition, autoApprove: boolean, known: Set<string> | null): boolean;
 /** 测试与 HITL 续跑：从已 hydrate 的 map 判断是否还要 list */
 export declare function needsMcpHydration(loadedTools: LoadedToolMap | undefined): boolean;

package/dist/tool/mcp-list.js

@@ -24,6 +24,7 @@ export function parseListedTools(result) {
             name: t.name,
             description: typeof t.description === 'string' ? t.description : undefined,
             inputSchema,
+            ...(t.annotations?.readOnlyHint === true ? { readOnly: true } : {}),
         });
     }
     return out;
@@ -144,8 +145,9 @@ export function toolTraceIdentity(loaded, toolName) {
 }
 /**
  * 将 MCP discover stub 替换为 tools/list 结果。
- * 无 stub 时原样返回（同一引用）。按 endpoint+user+agent 在执行器内缓存 list。
+ * 无 stub 时原样返回（同一引用）。执行器按会话缓存 list。
  * enabledTools 为可选白名单；autoApprove 的子工具 requireConfirmation=false。
+ * knownTools 之外的新工具，不是只读时要用户确认。
  * 单个 endpoint 的 list 失败只跳过该工具集；全部失败才抛错（错误含工具集名）。
  */
 export async function hydrateMcpTools(loadedTools, executor, auth) {
@@ -193,6 +195,7 @@ export async function hydrateMcpTools(loadedTools, executor, auth) {
                 execution: primary.manifest.execution,
                 ...(toolsetCode ? { toolsetCode } : {}),
                 ...(primary.manifest.version ? { toolVersion: primary.manifest.version } : {}),
+                ...(auth.sessionId ? { sessionId: auth.sessionId } : {}),
             });
         }
         catch (err) {
@@ -213,12 +216,13 @@ export async function hydrateMcpTools(loadedTools, executor, auth) {
             const enabled = exec?.enabledTools;
             const enabledSet = enabled && enabled.length > 0 ? new Set(enabled) : null;
             const autoApprove = new Set(exec?.autoApprove ?? []);
+            const known = Array.isArray(exec?.knownTools) ? new Set(exec.knownTools) : null;
             const picked = enabledSet ? listed.filter((t) => enabledSet.has(t.name)) : listed;
             for (const tool of picked) {
                 if (emitted.has(tool.name))
                     continue;
                 emitted.add(tool.name);
-                result[tool.name] = listedToolToDefinition(tool, stub, autoApprove.has(tool.name));
+                result[tool.name] = listedToolToDefinition(tool, stub, mcpChildNeedsConfirmation(tool, stub, autoApprove.has(tool.name), known));
             }
         }
     }
@@ -227,11 +231,20 @@ export async function hydrateMcpTools(loadedTools, executor, auth) {
     }
     return result;
 }
-function listedToolToDefinition(tool, stub, autoApprove) {
+/** 登记过的名字沿用 stub；新名字在不是只读时要确认。没有 knownTools 时全部沿用 stub。 */
+export function mcpChildNeedsConfirmation(tool, stub, autoApprove, known) {
+    if (autoApprove)
+        return false;
+    if (known === null || known.has(tool.name))
+        return Boolean(stub.manifest.requireConfirmation);
+    return tool.readOnly !== true;
+}
+function listedToolToDefinition(tool, stub, requireConfirmation) {
     const exec = { ...(readMcpDiscoverExecution(stub.manifest.execution) ?? {}) };
     delete exec.discover;
     delete exec.enabledTools;
     delete exec.autoApprove;
+    delete exec.knownTools;
     const rest = exec;
     return {
         toolId: `${stub.toolId}:${tool.name}`,
@@ -245,7 +258,7 @@ function listedToolToDefinition(tool, stub, autoApprove) {
             description: tool.description,
             toolRuntime: stub.manifest.toolRuntime,
             dataScope: stub.manifest.dataScope,
-            requireConfirmation: autoApprove ? false : Boolean(stub.manifest.requireConfirmation),
+            requireConfirmation,
             execution: {
                 ...rest,
                 protocol: 'mcp',

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

@@ -18,7 +18,7 @@ export declare class McpToolExecutor implements IToolExecutor {
     private readonly mcpUrl;
     private rpcId;
     private initialized;
-    /** endpoint+user+agent+toolset+version → in-flight / completed tools/list */
+    /** 同一会话复用 tools/list。新会话或新 task 重新要。 */
     private readonly listCache;
     constructor(options: McpToolExecutorOptions);
     execute(request: ToolCallRequest): Promise<ToolCallResult>;

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

@@ -81,6 +81,7 @@ function mcpListCacheKey(mcpUrl, request) {
         request.authContext.agentCode,
         request.toolsetCode?.trim() ?? '',
         request.toolVersion?.trim() ?? '',
+        request.sessionId?.trim() || request.taskId?.trim() || '',
     ].join('\0');
 }
 export class McpToolExecutor {
@@ -89,7 +90,7 @@ export class McpToolExecutor {
     mcpUrl;
     rpcId = 1;
     initialized = false;
-    /** endpoint+user+agent+toolset+version → in-flight / completed tools/list */
+    /** 同一会话复用 tools/list。新会话或新 task 重新要。 */
     listCache = new Map();
     constructor(options) {
         if (!isAbsoluteHttpUrl(options.baseUrl)) {

package/dist/tool/system-prompt-builder.js

@@ -20,7 +20,9 @@
  *
  * @see docs/status/module-status-and-backlog.md RT-5
  */
+import { resolveBuiltinToolsConfig } from '@gt-fe/eap-contracts';
 import { commandDialectLines } from './harness-command.js';
+import { defaultTimezone } from './unix-time.js';
 // ─────────────────────────────────────────────
 // 平台规则常量（一年改不了两次，不值得搞配置表）
 // ─────────────────────────────────────────────
@@ -64,6 +66,21 @@ const PLATFORM_RULES = `你是运行在企业智能体平台（EAP）上的 AI
 
 ## 规则优先级
 以上平台规则最高。后面的身份、技能说明、Agent 基线、节点提示词与之冲突时，以平台规则为准。`;
+/** 内置时间工具开着时，写进平台规则「时间」段。关掉内置工具则不写。 */
+function timestampBan() {
+    return [
+        '- **禁止**自己计算 Unix 秒或毫秒。禁止心算，禁止用当前时间戳加减，禁止用 `execute_command`、`date` 或 python 换算。',
+        '- 环境段「当前时间戳（秒）」「当前时间戳（毫秒）」可以原样抄。',
+        '- 其它日期或时间戳**必须**调用 `datetime_to_unix`（日期换成时间戳）或 `unix_to_datetime`（时间戳换成日期），只使用返回的 `unix_seconds`、`unix_milliseconds` 或 `formatted`。',
+        '- 这两个工具省略 timezone 时，用环境段的「时区」。填入其它工具的秒或毫秒，必须是返回的 `unix_seconds` 或 `unix_milliseconds`。',
+    ].join('\n');
+}
+function platformRules() {
+    if (!resolveBuiltinToolsConfig(process.env).enabled)
+        return PLATFORM_RULES;
+    const anchor = '- 遇到非法日期（如 2 月 30 日）先告诉用户，不要擅自改写后静默查询。';
+    return PLATFORM_RULES.replace(anchor, `${anchor}\n${timestampBan()}`);
+}
 export function toLoadedSkillMap(skills) {
     if (!skills?.length)
         return undefined;
@@ -136,7 +153,7 @@ export class SystemPromptBuilder {
                 return;
             sections.push({ id, title, body: trimmed });
         };
-        add('platform-rules', '平台规则', PLATFORM_RULES);
+        add('platform-rules', '平台规则', platformRules());
         add('environment', '环境', this.buildEnvironment(context));
         add('identity', 'Agent 身份', this.buildAgentIdentity(context));
         if (context.userId && context.userId.trim() && context.userId !== 'anonymous') {
@@ -154,15 +171,16 @@ export class SystemPromptBuilder {
     }
     buildEnvironment(context, now = new Date()) {
         const windows = naturalTimeWindows(now);
+        const zone = defaultTimezone();
+        const ms = now.getTime();
         const lines = [
             '## 环境',
+            `- 时区：${zone}。当前时间、周和月都按此时区。`,
             `- 当前时间：${windows.now}（${windows.weekday}）`,
-            `- 本周：${windows.thisWeek}`,
-            `- 上周：${windows.lastWeek}`,
-            `- 上周末：${windows.lastWeekend}`,
-            `- 本月：${windows.thisMonth}`,
-            `- 上月：${windows.lastMonth}`,
+            `- 当前时间戳（秒）：${Math.floor(ms / 1000)}`,
+            `- 当前时间戳（毫秒）：${ms}`,
         ];
+        lines.push(`- 本周：${windows.thisWeek}`, `- 上周：${windows.lastWeek}`, `- 上周末：${windows.lastWeekend}`, `- 本月：${windows.thisMonth}`, `- 上月：${windows.lastMonth}`);
         if (context.workingDirectory) {
             lines.push(`- 工作目录：${context.workingDirectory}`);
         }
@@ -255,7 +273,7 @@ export function naturalTimeWindows(now = new Date()) {
     const lastMonthStart = new Date(now.getFullYear(), now.getMonth() - 1, 1);
     const lastMonthEnd = new Date(now.getFullYear(), now.getMonth(), 0);
     return {
-        now: `${formatDay(now)} ${pad2(now.getHours())}:${pad2(now.getMinutes())}`,
+        now: `${formatDay(now)} ${pad2(now.getHours())}:${pad2(now.getMinutes())}:${pad2(now.getSeconds())}`,
         weekday: weekdays[now.getDay()] ?? '',
         thisWeek: `${formatDay(thisMon)}（周一） ~ ${formatDay(thisSun)}（周日）`,
         lastWeek: `${formatDay(lastMon)}（周一） ~ ${formatDay(lastSun)}（周日）`,

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

@@ -38,6 +38,10 @@ export interface ToolCallRequest {
     taskId?: string;
     /** 链路关联 ID；缺省可用 toolCallId */
     correlationId?: string;
+    /**
+     * 会话标识。MCP tools/list 按会话缓存：同一会话复用名单，新会话重新向 Gateway 要。
+     */
+    sessionId?: string;
     /** 路由用：manifest type */
     toolType?: string;
     /** 路由用：manifest runtime */
@@ -143,6 +147,8 @@ export interface McpListedTool {
     name: string;
     description?: string;
     inputSchema?: Record<string, unknown>;
+    /** 上游 annotations.readOnlyHint 为 true。缺省视为会改数据。 */
+    readOnly?: boolean;
 }
 /**
  * IToolExecutor — Tool 执行网关接口

package/dist/tool/unix-time.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 两个方向分开：
+ * datetime_to_unix 只收日期字符串；unix_to_datetime 只收整数字符串时间戳。
+ * 省略 timezone 时用进程 IANA 时区，与环境段的当前时间相同。
+ */
+/** 省略 timezone 时用的时区：进程 IANA 名，没有则 Asia/Shanghai。 */
+export declare function defaultTimezone(): string;
+export interface DatetimeToUnixValue {
+    timezone: string;
+    datetime: string;
+    unix_seconds: string;
+    unix_milliseconds: string;
+    note?: string;
+}
+export interface UnixToDatetimeValue {
+    timezone: string;
+    unit: 's' | 'ms';
+    formatted: string;
+    format: string;
+    unix_seconds: string;
+    unix_milliseconds: string;
+}
+export type TimeResolution<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function resolveDatetimeToUnix(args: Record<string, unknown> | undefined): TimeResolution<DatetimeToUnixValue>;
+export declare function resolveUnixToDatetime(args: Record<string, unknown> | undefined): TimeResolution<UnixToDatetimeValue>;

package/dist/tool/unix-time.js

@@ -0,0 +1,304 @@
+/**
+ * 两个方向分开：
+ * datetime_to_unix 只收日期字符串；unix_to_datetime 只收整数字符串时间戳。
+ * 省略 timezone 时用进程 IANA 时区，与环境段的当前时间相同。
+ */
+const FALLBACK_TIMEZONE = 'Asia/Shanghai';
+const DEFAULT_FORMAT = 'YYYY-MM-DD HH:mm:ss';
+/** 省略 unit 时，绝对值达到此值视为毫秒，否则视为秒。 */
+const MS_THRESHOLD = 1_000_000_000_000;
+/** Date 可表示的绝对毫秒。超出后 Intl 会抛英文异常。 */
+const MAX_ABS_MS = 8_640_000_000_000_000;
+const FORMAT_TOKEN = 'YYYY|SSS|MM|DD|HH|mm|ss';
+const DATE_EXAMPLE = '例如 2027-01-01、2027年1月1日、2027/01/01、2027-01-01 11:00、2027-01-01 11:00:00.123。';
+const DATE_ONLY_NOTE = '只写了日期，按该时区当天 00:00:00。其它工具若要日期，传原来的日期，不要传这个零点的秒。';
+/** 省略 timezone 时用的时区：进程 IANA 名，没有则 Asia/Shanghai。 */
+export function defaultTimezone() {
+    try {
+        const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        if (typeof zone === 'string' && zone.trim()) {
+            Intl.DateTimeFormat('en-US', { timeZone: zone });
+            return zone;
+        }
+    }
+    catch {
+        // 进程没有可用的 IANA 时区
+    }
+    return FALLBACK_TIMEZONE;
+}
+export function resolveDatetimeToUnix(args) {
+    const record = args ?? {};
+    const extra = unknownKeys(record, ['datetime', 'timezone']);
+    if (extra.length > 0) {
+        return fail(`datetime_to_unix 只接受 datetime、timezone，收到 ${extra.join('、')}。格式化时间戳请用 unix_to_datetime。`);
+    }
+    const timezone = readTimezone(record.timezone);
+    if (!timezone.ok)
+        return timezone;
+    const raw = record.datetime;
+    if (raw == null || (typeof raw === 'string' && raw.trim() === '')) {
+        return { ok: true, value: fromInstant(Date.now(), timezone.value, false) };
+    }
+    if (typeof raw === 'number' || (typeof raw === 'string' && /^[+-]?\d+$/.test(raw.trim()))) {
+        return fail('datetime 是数字。时间戳请用 unix_to_datetime 的 timestamp。');
+    }
+    if (typeof raw !== 'string') {
+        return fail('datetime 必须是字符串，例如 2027-01-01 或 2027-01-01 11:00。');
+    }
+    const text = raw.trim();
+    if (/[zZ]$/.test(text) || /[+-]\d{2}:?\d{2}$/.test(text)) {
+        return fail('datetime 带了时区。请去掉 Z 或偏移，改用 timezone。');
+    }
+    const parsed = parseWall(text);
+    if (!parsed.ok)
+        return parsed;
+    const ms = wallToInstant(parsed.value.civil, timezone.value);
+    if (ms == null)
+        return fail(`时区 ${timezone.value} 没有这个时刻：${text}。`);
+    return { ok: true, value: fromInstant(ms + parsed.value.millis, timezone.value, parsed.value.dateOnly) };
+}
+export function resolveUnixToDatetime(args) {
+    const record = args ?? {};
+    const extra = unknownKeys(record, ['timestamp', 'unit', 'timezone', 'format']);
+    if (extra.length > 0) {
+        return fail(`unix_to_datetime 只接受 timestamp、unit、timezone、format，收到 ${extra.join('、')}。日期换时间戳请用 datetime_to_unix。`);
+    }
+    const timezone = readTimezone(record.timezone);
+    if (!timezone.ok)
+        return timezone;
+    const format = readFormat(record.format);
+    if (!format.ok)
+        return format;
+    const unit = readUnit(record.unit);
+    if (!unit.ok)
+        return unit;
+    const raw = record.timestamp;
+    if (raw == null || (typeof raw === 'string' && raw.trim() === '')) {
+        return fail('timestamp 必填。秒如 1798732800，毫秒如 1798732800000。');
+    }
+    if (typeof raw !== 'number' && typeof raw !== 'string') {
+        return fail('timestamp 必须是整数字符串。秒如 1798732800，毫秒如 1798732800000。');
+    }
+    const text = typeof raw === 'number' ? String(raw) : raw.trim();
+    if (!/^[+-]?\d+$/.test(text)) {
+        return fail('timestamp 必须是整数字符串。日期请用 datetime_to_unix 的 datetime。');
+    }
+    if (text.replace(/^[+-]/, '').length > 15)
+        return fail('时间戳超出可表示范围。');
+    const n = Number(text);
+    if (!Number.isSafeInteger(n))
+        return fail('时间戳超出可表示范围。');
+    const resolved = unit.value ?? (Math.abs(n) >= MS_THRESHOLD ? 'ms' : 's');
+    const ms = resolved === 'ms' ? n : n * 1000;
+    if (!Number.isFinite(ms) || Math.abs(ms) > MAX_ABS_MS)
+        return fail('时间戳超出可表示范围。');
+    let civil;
+    try {
+        civil = partsInZone(ms, timezone.value);
+    }
+    catch {
+        return fail('时间戳超出可表示范围。');
+    }
+    if (!Number.isFinite(civil.year))
+        return fail('时间戳超出可表示范围。');
+    return {
+        ok: true,
+        value: {
+            timezone: timezone.value,
+            unit: resolved,
+            formatted: applyFormat(civil, ms, format.value),
+            format: format.value,
+            unix_seconds: String(Math.floor(ms / 1000)),
+            unix_milliseconds: String(ms),
+        },
+    };
+}
+function fromInstant(ms, timezone, dateOnly) {
+    const civil = partsInZone(ms, timezone);
+    const frac = ((ms % 1000) + 1000) % 1000;
+    let datetime = applyFormat(civil, ms, DEFAULT_FORMAT);
+    if (frac !== 0)
+        datetime += `.${String(frac).padStart(3, '0')}`;
+    const value = {
+        timezone,
+        datetime,
+        unix_seconds: String(Math.floor(ms / 1000)),
+        unix_milliseconds: String(ms),
+    };
+    if (dateOnly)
+        value.note = DATE_ONLY_NOTE;
+    return value;
+}
+function unknownKeys(record, allowed) {
+    return Object.keys(record).filter((key) => !allowed.includes(key));
+}
+function readTimezone(raw) {
+    if (raw == null || (typeof raw === 'string' && raw.trim() === '')) {
+        return { ok: true, value: defaultTimezone() };
+    }
+    if (typeof raw !== 'string')
+        return fail('timezone 必须是 IANA 时区名，例如 Asia/Shanghai 或 UTC。');
+    const timezone = raw.trim();
+    try {
+        Intl.DateTimeFormat('en-US', { timeZone: timezone });
+    }
+    catch {
+        return fail(`时区无效：${timezone}。请用 IANA 名，例如 Asia/Shanghai、UTC、America/New_York。`);
+    }
+    return { ok: true, value: timezone };
+}
+function readFormat(raw) {
+    if (raw == null || (typeof raw === 'string' && raw.trim() === '')) {
+        return { ok: true, value: DEFAULT_FORMAT };
+    }
+    if (typeof raw !== 'string') {
+        return fail('format 必须是字符串。记号只有 YYYY、MM、DD、HH、mm、ss、SSS。');
+    }
+    const format = raw.trim();
+    const token = new RegExp(FORMAT_TOKEN, 'g');
+    const stripped = format.replace(token, '');
+    if (/[A-Za-z]/.test(stripped) || !new RegExp(FORMAT_TOKEN).test(format)) {
+        return fail(`format 无法使用：${format}。记号只有 YYYY、MM、DD、HH、mm、ss、SSS。月是 MM，分是 mm。例如 YYYY-MM-DD HH:mm:ss。`);
+    }
+    if (/HH[^A-Za-z]*MM/.test(format)) {
+        return fail(`format 把分钟写成了 MM：${format}。分钟用 mm，月份用 MM。例如 YYYY-MM-DD HH:mm:ss。`);
+    }
+    if (/YYYY[^A-Za-z]*mm/.test(format)) {
+        return fail(`format 把月份写成了 mm：${format}。月份用 MM，分钟用 mm。例如 YYYY-MM-DD HH:mm:ss。`);
+    }
+    return { ok: true, value: format };
+}
+function readUnit(raw) {
+    if (raw == null || raw === '')
+        return { ok: true, value: undefined };
+    if (raw === 's' || raw === 'ms')
+        return { ok: true, value: raw };
+    return fail('unit 只能是 s 或 ms。s 为秒，ms 为毫秒。');
+}
+function parseWall(text) {
+    if (/\.\d{4,}/.test(text))
+        return fail(`毫秒最多三位。${DATE_EXAMPLE}`);
+    const isoDate = /^(\d{4})([-/])(\d{1,2})\2(\d{1,2})$/.exec(text);
+    if (isoDate)
+        return accept(text, true, isoDate[1], isoDate[3], isoDate[4]);
+    const isoTime = /^(\d{4})([-/])(\d{1,2})\2(\d{1,2})[T ](\d{1,2}):(\d{1,2})(?::(\d{1,2}))?(?:\.(\d{1,3}))?$/.exec(text);
+    if (isoTime)
+        return accept(text, false, isoTime[1], isoTime[3], isoTime[4], isoTime[5], isoTime[6], isoTime[7], isoTime[8]);
+    const cnDate = /^(\d{4})年(\d{1,2})月(\d{1,2})日$/.exec(text);
+    if (cnDate)
+        return accept(text, true, cnDate[1], cnDate[2], cnDate[3]);
+    const cnTime = /^(\d{4})年(\d{1,2})月(\d{1,2})日[ T]?(\d{1,2}):(\d{1,2})(?::(\d{1,2}))?(?:\.(\d{1,3}))?$/.exec(text);
+    if (cnTime)
+        return accept(text, false, cnTime[1], cnTime[2], cnTime[3], cnTime[4], cnTime[5], cnTime[6], cnTime[7]);
+    const cnHan = /^(\d{4})年(\d{1,2})月(\d{1,2})日[ T]?(\d{1,2})时(\d{1,2})分(?:(\d{1,2})秒)?$/.exec(text);
+    if (cnHan)
+        return accept(text, false, cnHan[1], cnHan[2], cnHan[3], cnHan[4], cnHan[5], cnHan[6]);
+    return fail(`看不懂这个时间：${text}。${DATE_EXAMPLE}`);
+}
+function accept(text, dateOnly, year, month, day, hour, minute, second, fraction) {
+    const civil = checkedCivil({
+        year: Number(year),
+        month: Number(month),
+        day: Number(day),
+        hour: dateOnly ? 0 : Number(hour),
+        minute: dateOnly ? 0 : Number(minute),
+        second: dateOnly ? 0 : Number(second ?? 0),
+    });
+    if (!civil)
+        return fail(`${dateOnly ? '日期' : '时刻'}无效：${text}。`);
+    const millis = fraction ? Number(fraction.padEnd(3, '0')) : 0;
+    return { ok: true, value: { civil, millis, dateOnly } };
+}
+function checkedCivil(civil) {
+    if (civil.year < 1000 || civil.year > 9999)
+        return null;
+    if (civil.month < 1 || civil.month > 12 || civil.day < 1)
+        return null;
+    if (civil.hour > 23 || civil.minute > 59 || civil.second > 59)
+        return null;
+    const probe = new Date(Date.UTC(civil.year, civil.month - 1, civil.day));
+    if (probe.getUTCFullYear() !== civil.year ||
+        probe.getUTCMonth() !== civil.month - 1 ||
+        probe.getUTCDate() !== civil.day) {
+        return null;
+    }
+    return civil;
+}
+/** 墙上时间换成 UTC 毫秒。重叠的本地时刻保留第一次校正后仍能对上的那个。缺口返回 null。 */
+function wallToInstant(civil, timeZone) {
+    const desired = Date.UTC(civil.year, civil.month - 1, civil.day, civil.hour, civil.minute, civil.second);
+    let instant = desired - offsetMs(timeZone, desired);
+    const corrected = desired - offsetMs(timeZone, instant);
+    if (corrected !== instant)
+        instant = corrected;
+    const back = partsInZone(instant, timeZone);
+    if (back.year !== civil.year ||
+        back.month !== civil.month ||
+        back.day !== civil.day ||
+        back.hour !== civil.hour ||
+        back.minute !== civil.minute ||
+        back.second !== civil.second) {
+        return null;
+    }
+    return instant;
+}
+function offsetMs(timeZone, instant) {
+    const civil = partsInZone(instant, timeZone);
+    const asUtc = Date.UTC(civil.year, civil.month - 1, civil.day, civil.hour, civil.minute, civil.second);
+    return asUtc - instant;
+}
+function partsInZone(ms, timeZone) {
+    const formatted = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+    }).formatToParts(new Date(ms));
+    const bag = {};
+    for (const part of formatted) {
+        if (part.type !== 'literal')
+            bag[part.type] = part.value;
+    }
+    let year = Number(bag.year);
+    let month = Number(bag.month);
+    let day = Number(bag.day);
+    let hour = Number(bag.hour);
+    if (hour === 24) {
+        hour = 0;
+        const next = new Date(Date.UTC(year, month - 1, day) + 24 * 60 * 60 * 1000);
+        year = next.getUTCFullYear();
+        month = next.getUTCMonth() + 1;
+        day = next.getUTCDate();
+    }
+    return {
+        year,
+        month,
+        day,
+        hour,
+        minute: Number(bag.minute),
+        second: Number(bag.second),
+    };
+}
+function applyFormat(civil, ms, pattern) {
+    const sub = ((ms % 1000) + 1000) % 1000;
+    const map = {
+        YYYY: String(civil.year).padStart(4, '0'),
+        MM: pad(civil.month),
+        DD: pad(civil.day),
+        HH: pad(civil.hour),
+        mm: pad(civil.minute),
+        ss: pad(civil.second),
+        SSS: String(sub).padStart(3, '0'),
+    };
+    return pattern.replace(new RegExp(FORMAT_TOKEN, 'g'), (token) => map[token] ?? token);
+}
+function pad(n) {
+    return String(n).padStart(2, '0');
+}
+function fail(error) {
+    return { ok: false, error };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gt-fe/eap-runtime",
-  "version": "0.0.36",
+  "version": "0.0.37",
   "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
     "ioredis": "^5.4.0",
     "pg": "^8.13.0",
     "yaml": "^2.6.1",
-    "@gt-fe/eap-contracts": "0.0.18"
+    "@gt-fe/eap-contracts": "0.0.19"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",