@gt-fe/eap-runtime 0.0.8 → 0.0.11

package/README.md

@@ -8,6 +8,8 @@ Enterprise Agent Platform **执行引擎**（LangGraph.js）：Agent Graph 编
 
 | 日期 | 摘要 |
 |------|------|
+| 2026-08-24 | 0.0.10：官方 Skill / Harness、`ForkParams`、对话详情、存储两档。依赖 `@eap/contracts@0.0.9`。详见 [CHANGELOG.md](./CHANGELOG.md) |
+| 2026-08-21 | 0.0.9：Gateway `/mcp` JSON-RPC 补 `Accept`；`tools/call` 透传工具版本。详见 [CHANGELOG.md](./CHANGELOG.md) |
 | 2026-08-19 | 0.0.8：Skill 子图 SSE 闭环；`ExecuteParams.traceId`；`tool.called` 改为 Tool 节点开始执行。依赖 `@eap/contracts@0.0.8`。详见 [CHANGELOG.md](./CHANGELOG.md) |
 | 2026-08-18 | 0.0.7：`DevHttpExecutor`、`mode=mcp` 缺配置失败、HTTP 出站语义与 Gateway 共用 `@eap/contracts@0.0.7` |
 | 2026-07-29 | 补全 `.env.example` 全量环境变量（部署上下文 / Tool / 预装 / 存储装配 / 调试分区）；§5 预装开关表补 `EAP_PRELOAD_DEFINITION_CACHE` |
@@ -21,10 +23,12 @@ Enterprise Agent Platform **执行引擎**（LangGraph.js）：Agent Graph 编
 | 权威文档 | 路径 |
 |----------|------|
 | 模块规格 | [`.kiro/specs/04-runtime-core/`](../.kiro/specs/04-runtime-core/) |
+| Runtime DDL | [`docs/ddl.md`](./docs/ddl.md) |
 | SDK 集成手册 | [`docs/contracts/runtime-sdk-integration-final.md`](../docs/contracts/runtime-sdk-integration-final.md) |
 | 环境变量总表 | [`docs/governance/governance-env-config.md`](../docs/governance/governance-env-config.md) |
 | 预装联调契约 | [`docs/contracts/preload-hosting-runtime-contract.md`](../docs/contracts/preload-hosting-runtime-contract.md) |
 | 预装加载与请求流转 | [`docs/contracts/runtime-preinstall-load-flow.md`](../docs/contracts/runtime-preinstall-load-flow.md) |
+| 技能 FS 待办 | [`docs/TODO-skill-fs.md`](./docs/TODO-skill-fs.md) |
 | 本地 Agent 闭环 | [`docs/workflows/local-agent-dev-loop.md`](../docs/workflows/local-agent-dev-loop.md) |
 
 ---
@@ -82,7 +86,7 @@ for await (const ev of agentRuntime.stream({ agentCode, input, sessionId, taskId
 await agentRuntime.seedSessionMessages({ agentCode, messages: [ /* role: user | assistant */ ] });
 await agentRuntime.resumeHitl(taskId, { choice, userId, /* … */ });
 for await (const ev of agentRuntime.streamResumeHitl(taskId, { choice, userId })) { /* HITL 续跑事件 */ }
-await agentRuntime.fork(checkpointId, { /* overrides */ });
+await agentRuntime.fork({ checkpointId, taskId, traceId, overrides: { /* … */ } });
 ```
 
 细则与字段表见 [`docs/contracts/runtime-sdk-integration-final.md`](../docs/contracts/runtime-sdk-integration-final.md)。
@@ -175,26 +179,18 @@ node ../fixtures/eap-preinstall-sample/scripts/seal-snapshot.mjs
 
 ## 6. 持久化与存储 Profile
 
-由 `assembleRuntimeStorage()` / `EAP_RUNTIME_STORAGE_PROFILE` 统一装配 Checkpoint、Session、Message。
+`assembleRuntimeStorage()` 按 profile 与环境变量选择介质。表结构见 [`docs/ddl.md`](./docs/ddl.md)。
 
-| Profile | Checkpoint | Session | Message | 典型场景 |
-|---------|------------|---------|---------|----------|
-| `test` | Memory | Memory | Memory | 单测 |
-| `dev` | File | File | File | `eap chat` / 本机 |
-| `integration` | Redis + PG | （Hosting Session） | PG | Hosting 内嵌联调 |
-| `production` | Redis + PG | （Hosting Session） | PG | 多副本生产 |
+| 条件 | Checkpoint | Message / LLM 回合 | Token 配额 |
+|------|------------|-------------------|------------|
+| `EAP_RUNTIME_STORAGE_PROFILE=dev`，或未设 profile 且未配置数据库与 Redis | 文件（默认 `.eap/checkpoints`） | 文件 | 进程内，不落库 |
+| `test` / `integration` / `production`，或未设 profile 但已配置 `DATABASE_URL`/`DB_*` 或 `REDIS_*` | Redis + PostgreSQL | PostgreSQL | PostgreSQL `token_budgets` |
 
-常用目录变量（**仅 `dev` profile**）：
+后一路径缺少数据库或 Redis 时抛错。显式 `dev` 时即使已配置数据库仍使用文件。
 
-| 变量 | 说明 |
-|------|------|
-| `EAP_CHECKPOINT_DIR` | File Checkpoint |
-| `EAP_SESSION_DIR` | File Session |
-| `EAP_MESSAGE_DIR` | File Message |
-
-完整策略与库表约定：[`docs/governance/governance-env-config.md` §9](../docs/governance/governance-env-config.md#9-runtime-存储装配策略)、[`docs/architecture/session-message-checkpoint-alignment.md`](../docs/architecture/session-message-checkpoint-alignment.md)、[`docs/verification/db-storage-verification.md`](../docs/verification/db-storage-verification.md)。
+仅文件路径使用的目录变量：`EAP_CHECKPOINT_DIR`、`EAP_SESSION_DIR`、`EAP_MESSAGE_DIR`（可用 `EAP_DATA_DIR` 作为根目录）。
 
-本地带 File 存储的 fixture 示例：[`fixtures/eap-local-test/`](../fixtures/eap-local-test/)（`chat.sh` / `chat-db.sh`）。
+环境变量总表：[governance-env-config.md §9](../docs/governance/governance-env-config.md#9-runtime-存储装配策略)。
 
 ---
 
@@ -202,8 +198,7 @@ node ../fixtures/eap-preinstall-sample/scripts/seal-snapshot.mjs
 
 | 模式 | 何时 | 说明 |
 |------|------|------|
-| `mock` | 本地默认 | 不调真实 Tool |
-| `mcp` / DevMcp | `eap chat --tool-mode mcp` | 本机直连 MCP（`EAP_TOOL_EXECUTION_MODE`，仅 createDevRuntime） |
+| `mcp` / DevToolExecutor | 本地默认（`dev` + `mcp`） | 按清单直连 MCP / HTTP / 本机 code |
 | Gateway | 生产 / Hosting | `EAP_TOOL_GATEWAY_TRANSPORT=mcp`（生产）；`http` 仅调试 |
 
 - 编排：`ToolOrchestrator` + `ToolExecutionRouter`（`deploymentContext`: `server` \| `desktop` \| `dev`）
@@ -259,7 +254,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=mock                 # 或 mcp
+EAP_TOOL_EXECUTION_MODE=mcp                  # 本地默认；http-debug 走 Gateway 调试口
 # OPENAI_BASE_URL / OPENAI_API_KEY / EAP_DEFAULT_MODEL
 ```
 

package/dist/api/handlers/invoke.handler.js

@@ -21,7 +21,8 @@ import { TokenBudgetExhaustedError } from '../../token/token-budget-guard.js';
 import { resolveExecutionContext } from '../../governance/governance-client.js';
 import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.js';
 import { toLoadedToolMap } from '../../tool/loaded-tool-definition.js';
-import { toLoadedSkillMap, mergeSkillScriptTools } from '../../tool/system-prompt-builder.js';
+import { toLoadedSkillMap } from '../../tool/system-prompt-builder.js';
+import { assembleLoadedTools } from '../../tool/harness-primitives.js';
 import { resolveAgentCode } from '../../common/agent-code.js';
 import { unwrapHitlPaused } from '../../graph/hitl/hitl-handler.js';
 import { resolveTraceId } from '../../common/trace-id.js';
@@ -173,11 +174,13 @@ export class InvokeOrchestrator {
                 })
                 : undefined;
             const skillDefinitions = toLoadedSkillMap(loadedSkills);
-            // Skill scripts 虚拟 Tool 并入 loadedTools（同名不覆盖平台 Tool）
-            const loadedTools = mergeSkillScriptTools(loadedToolsBase, loadedSkills);
+            const loadedTools = assembleLoadedTools(loadedToolsBase);
             const promptRoots = this.graphLoader
                 ? await this.graphLoader.resolvePromptRoots(agentCode, req.agentVersion)
                 : [];
+            const agentDir = this.graphLoader
+                ? (await this.graphLoader.resolveAgentDir(agentCode, req.agentVersion)) ?? undefined
+                : undefined;
             // 组装 GraphState：有 Checkpoint 历史则只追加本轮 user，避免双重 append
             const history = messageRecordsToGraphMessages(sessionContext.messages);
             const messages = await buildTurnGraphMessages({
@@ -204,6 +207,7 @@ export class InvokeOrchestrator {
                 skillDefinitions,
                 skillInput,
                 promptRoots,
+                agentDir,
                 traceId: resolveTraceId(req),
                 traceCollector: this.traceCollector,
             });

package/dist/api/handlers/messages.handler.js

@@ -47,7 +47,6 @@ export class MessagesOrchestrator {
         const agentVersion = req.agentVersion ?? metaVersion;
         // ─── Step 2: 委托 InvokeOrchestrator（user/assistant Message 由 invoke 主路径写回）───
         const invokeReq = {
-            agentId: session.agentId,
             agentCode: session.agentId,
             input,
             sessionId,

package/dist/api/handlers/stream.handler.js

@@ -25,10 +25,11 @@ import { TokenBudgetExhaustedError } from '../../token/token-budget-guard.js';
 import { SSEEmitter } from '../../sse/sse-emitter.js';
 import { resolveExecutionContext } from '../../governance/governance-client.js';
 import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.js';
-import { ErrorCodes } from '@gt-fe/eap-contracts';
+import { ErrorCodes } from '@eap/contracts';
 import { classifyRuntimeError } from '../../utils/http-error.js';
 import { toLoadedToolMap } from '../../tool/loaded-tool-definition.js';
-import { toLoadedSkillMap, mergeSkillScriptTools } from '../../tool/system-prompt-builder.js';
+import { toLoadedSkillMap } from '../../tool/system-prompt-builder.js';
+import { assembleLoadedTools } from '../../tool/harness-primitives.js';
 import { resolveAgentCode } from '../../common/agent-code.js';
 import { unwrapHitlPaused } from './invoke.handler.js';
 import { buildHitlWaitedPayload } from '../../graph/hitl/hitl-handler.js';
@@ -195,11 +196,13 @@ export class StreamOrchestrator {
             ? await this.graphLoader.loadSkillDefinitions(agentCode, { ...loadOpts, userId })
             : undefined;
         const skillDefinitions = toLoadedSkillMap(loadedSkills);
-        // Skill scripts 虚拟 Tool 并入 loadedTools（同名不覆盖平台 Tool）
-        const loadedTools = mergeSkillScriptTools(loadedToolsBase, loadedSkills);
+        const loadedTools = assembleLoadedTools(loadedToolsBase);
         const promptRoots = this.graphLoader
             ? await this.graphLoader.resolvePromptRoots(agentCode, req.agentVersion)
             : [];
+        const agentDir = this.graphLoader
+            ? (await this.graphLoader.resolveAgentDir(agentCode, req.agentVersion)) ?? undefined
+            : undefined;
         // 组装 GraphState：有 Checkpoint 历史则只追加本轮 user，避免双重 append
         const history = messageRecordsToGraphMessages(sessionContext.messages);
         const messages = await buildTurnGraphMessages({
@@ -232,6 +235,7 @@ export class StreamOrchestrator {
                 skillDefinitions,
                 skillInput,
                 promptRoots,
+                agentDir,
                 traceId: resolveTraceId(req),
                 traceCollector: this.traceCollector,
             });

package/dist/api/routes/agent.routes.d.ts

@@ -4,12 +4,12 @@
  * 生产环境由 Hosting 提供对外 HTTP；本模块供 `EAP_DEV_HTTP=1` 本地调试。
  */
 import type { ServerResponse } from 'node:http';
-import type { InvokeRequest as ContractInvokeRequest, InvokeResponse as ContractInvokeResponse } from '@gt-fe/eap-contracts';
+import type { InvokeRequest as ContractInvokeRequest, InvokeResponse as ContractInvokeResponse } from '@eap/contracts';
 import type { ITaskManager } from '../../task/task.service.js';
 import type { SessionService } from '../../session/session.service.js';
 import type { IStateGraphEngine } from '../../graph/contracts/executable-graph.js';
 import type { SSEEmitter } from '../../sse/sse-emitter.js';
-export type { InvokeConfig, InvokeResponseData } from '@gt-fe/eap-contracts';
+export type { InvokeConfig, InvokeResponseData } from '@eap/contracts';
 /**
  * dev HTTP 层 Invoke 请求（扩展 userId，Hosting 从 auth 注入）
  */

package/dist/api/routes/agent.routes.js

@@ -21,7 +21,7 @@ export function createAgentRouteHandlers(deps) {
      */
     async function invokeHandler(req) {
         const { input, sessionId, config, userId } = req;
-        const agentCode = req.agentCode ?? req.agentId;
+        const agentCode = req.agentCode;
         if (!agentCode) {
             throw new Error('agentCode is required');
         }
@@ -109,7 +109,7 @@ export function createAgentRouteHandlers(deps) {
      */
     async function streamHandler(req, res) {
         const { input, sessionId, config, userId } = req;
-        const agentCode = req.agentCode ?? req.agentId;
+        const agentCode = req.agentCode;
         if (!agentCode) {
             res.write(`event: error\ndata: ${JSON.stringify({ error: 'agentCode is required' })}\n\n`);
             res.end();

package/dist/checkpoint/checkpoint-ref-notify.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Checkpoint 落盘后通知上层写 checkpoint_refs。
+ * 无 traceId 或 spanId 则跳过；回调失败不抛。
+ * collector 不得写入持久化正文。
+ */
+import type { ITraceCollector } from '../contracts/trace-collector.js';
+import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+/** 去掉不可序列化的 collector，再交给 Saver。 */
+export declare function stripCheckpointCollectors(data: CheckpointData): CheckpointData;
+export declare function notifyCheckpointRef(data: CheckpointData, collectorOverride?: ITraceCollector): Promise<void>;

package/dist/checkpoint/checkpoint-ref-notify.js

@@ -0,0 +1,59 @@
+/**
+ * Checkpoint 落盘后通知上层写 checkpoint_refs。
+ * 无 traceId 或 spanId 则跳过；回调失败不抛。
+ * collector 不得写入持久化正文。
+ */
+function pickString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function omitTraceCollector(record) {
+    const { traceCollector: _drop, ...rest } = record;
+    return rest;
+}
+/** 去掉不可序列化的 collector，再交给 Saver。 */
+export function stripCheckpointCollectors(data) {
+    const state = omitTraceCollector({ ...data.state });
+    const snap = data.engineSnapshot ? { ...data.engineSnapshot } : undefined;
+    if (snap?.channel_values && typeof snap.channel_values === 'object') {
+        snap.channel_values = omitTraceCollector({
+            ...snap.channel_values,
+        });
+    }
+    return {
+        ...data,
+        state: state,
+        ...(snap ? { engineSnapshot: snap } : {}),
+    };
+}
+export async function notifyCheckpointRef(data, collectorOverride) {
+    const channels = data.engineSnapshot && typeof data.engineSnapshot.channel_values === 'object'
+        ? data.engineSnapshot.channel_values
+        : {};
+    const state = (data.state ?? {});
+    const collector = (collectorOverride ??
+        channels['traceCollector'] ??
+        state['traceCollector']);
+    const traceId = pickString(state['traceId'], channels['traceId']);
+    const spanId = pickString(state['lastSpanId'], channels['lastSpanId']);
+    if (!collector?.recordCheckpointRef || !traceId || !spanId)
+        return;
+    try {
+        await collector.recordCheckpointRef({
+            checkpointId: data.checkpointId,
+            traceId,
+            spanId,
+            summary: {
+                nodeId: data.currentNodeId || pickString(channels['currentNode']),
+                threadId: data.threadId,
+                step: Array.isArray(data.historyPath) ? data.historyPath.length : undefined,
+            },
+        });
+    }
+    catch {
+        // 采集失败不阻断 Graph / HITL
+    }
+}

package/dist/checkpoint/index.d.ts

@@ -3,6 +3,7 @@ export { RedisCheckpointSaver } from './redis-checkpoint-saver.js';
 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 type { CreateCheckpointParams } from './checkpoint-serializer.js';
 export { FileCheckpointSaver } from './file-checkpoint-saver.js';

package/dist/checkpoint/index.js

@@ -3,6 +3,7 @@ export * from './contracts/index.js';
 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 { FileCheckpointSaver } from './file-checkpoint-saver.js';
 export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';

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

@@ -20,12 +20,16 @@ export class PostgresCheckpointSaver {
      */
     async save(threadId, data) {
         const sql = `
-      INSERT INTO checkpoints (id, thread_id, checkpoint_id, current_node_id, history_path, state, created_by, created_at, updated_by, updated_at)
-      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+      INSERT INTO checkpoints (
+        id, thread_id, checkpoint_id, current_node_id, history_path, state, engine_snapshot,
+        created_by, created_at, updated_by, updated_at
+      )
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
       ON CONFLICT (thread_id, checkpoint_id) DO UPDATE SET
         current_node_id = EXCLUDED.current_node_id,
         history_path = EXCLUDED.history_path,
         state = EXCLUDED.state,
+        engine_snapshot = EXCLUDED.engine_snapshot,
         updated_by = EXCLUDED.updated_by,
         updated_at = EXCLUDED.updated_at
     `;
@@ -36,6 +40,7 @@ export class PostgresCheckpointSaver {
             data.currentNodeId,
             JSON.stringify(data.historyPath),
             JSON.stringify(data.state),
+            data.engineSnapshot == null ? null : JSON.stringify(data.engineSnapshot),
             data.createdBy || 'system',
             data.createdAt,
             data.updatedBy || 'system',
@@ -105,6 +110,7 @@ export class PostgresCheckpointSaver {
             currentNodeId: source.currentNodeId,
             historyPath: source.historyPath,
             state: overrides ? { ...source.state, ...overrides } : source.state,
+            engineSnapshot: source.engineSnapshot,
             createdBy: 'fork',
             createdAt: now,
             updatedBy: 'fork',
@@ -128,6 +134,7 @@ export class PostgresCheckpointSaver {
             currentNodeId: row.current_node_id,
             historyPath: typeof row.history_path === 'string' ? JSON.parse(row.history_path) : row.history_path,
             state: typeof row.state === 'string' ? JSON.parse(row.state) : row.state,
+            engineSnapshot: parseJsonObject(row.engine_snapshot),
             createdBy: row.created_by,
             createdAt: row.created_at.toISOString(),
             updatedBy: row.updated_by,
@@ -138,3 +145,19 @@ export class PostgresCheckpointSaver {
         };
     }
 }
+function parseJsonObject(value) {
+    if (value == null || value === '')
+        return undefined;
+    if (typeof value === 'object')
+        return value;
+    try {
+        const parsed = JSON.parse(value);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}

package/dist/common/agent-code.d.ts

@@ -1,10 +1,8 @@
 /**
- * Agent 对外主键解析（迁移期双读）
- *
- * 正式字段为 agentCode；历史 agentId 仅作同义兜底。
+ * Agent 对外主键。只认 agentCode。
+ * SessionRecord.agentId 是存储列名（值为 agentCode），不是本函数的入参。
  */
 export declare function resolveAgentCode(input: {
     agentCode?: string | null;
-    agentId?: string | null;
     fallback?: string;
 }): string;

package/dist/common/agent-code.js

@@ -1,12 +1,11 @@
 /**
- * Agent 对外主键解析（迁移期双读）
- *
- * 正式字段为 agentCode；历史 agentId 仅作同义兜底。
+ * Agent 对外主键。只认 agentCode。
+ * SessionRecord.agentId 是存储列名（值为 agentCode），不是本函数的入参。
  */
 export function resolveAgentCode(input) {
-    const code = input.agentCode ?? input.agentId ?? input.fallback;
+    const code = input.agentCode ?? input.fallback;
     if (code == null || code === '') {
-        throw new Error('agentCode is required (agentId synonym accepted during migration)');
+        throw new Error('agentCode is required');
     }
     return String(code);
 }

package/dist/common/types.d.ts

@@ -1,8 +1,8 @@
 /**
  * eap-runtime 内部共享类型定义
  *
- * 本文件定义 Runtime 模块内部使用的类型，与 @gt-fe/eap-contracts 中的公共协议类型互补但不重复。
- * - @gt-fe/eap-contracts 定义跨模块的公共协议（如 Task 实体、Session 实体、Agent Manifest）
+ * 本文件定义 Runtime 模块内部使用的类型，与 @eap/contracts 中的公共协议类型互补但不重复。
+ * - @eap/contracts 定义跨模块的公共协议（如 Task 实体、Session 实体、Agent Manifest）
  * - 本文件定义 Runtime 执行引擎内部流转的配置、上下文、枚举等
  */
 /**
@@ -32,7 +32,7 @@ export declare const DEFAULT_RUNTIME_CONFIG: RuntimeConfig;
 /**
  * 执行上下文 — 贯穿 Graph 执行生命周期（Runtime 内部）
  *
- * 平台级 ExecutionContext（@gt-fe/eap-contracts）由 Hosting/eap dev 注入；
+ * 平台级 ExecutionContext（@eap/contracts）由 Hosting/eap dev 注入；
  * 本类型在 Task 创建后组装，供引擎子服务使用。
  */
 export interface RuntimeRunContext {
@@ -62,7 +62,7 @@ export type TaskStatus = 'pending' | 'running' | 'waiting_hitl' | 'success' | 'f
 /**
  * Runtime 执行上下文绑定状态（非平台 Session 生命周期）
  *
- * 平台 Session 三态（active/paused/closed）由 Hosting 管理，见 @gt-fe/eap-contracts。
+ * 平台 Session 三态（active/paused/closed）由 Hosting 管理，见 @eap/contracts。
  * Runtime 仅在引擎内标记执行上下文是否仍可绑定：`active` | `archived`。
  */
 export type ExecutionSessionBindingStatus = 'active' | 'archived';
@@ -77,7 +77,7 @@ export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
 /**
  * 单次 LLM/Tool 调用的 Token 消耗记录
  *
- * 与 @gt-fe/eap-contracts.TokenUsage 的区别：
+ * 与 @eap/contracts.TokenUsage 的区别：
  * - contracts 版本是 Task 级聚合结果（含 byNode/byModel）
  * - 本类型是单次调用粒度的原始记录，用于 Runtime 内部累计和 stats.node_token 事件
  */

package/dist/common/types.js

@@ -1,8 +1,8 @@
 /**
  * eap-runtime 内部共享类型定义
  *
- * 本文件定义 Runtime 模块内部使用的类型，与 @gt-fe/eap-contracts 中的公共协议类型互补但不重复。
- * - @gt-fe/eap-contracts 定义跨模块的公共协议（如 Task 实体、Session 实体、Agent Manifest）
+ * 本文件定义 Runtime 模块内部使用的类型，与 @eap/contracts 中的公共协议类型互补但不重复。
+ * - @eap/contracts 定义跨模块的公共协议（如 Task 实体、Session 实体、Agent Manifest）
  * - 本文件定义 Runtime 执行引擎内部流转的配置、上下文、枚举等
  */
 /** RuntimeConfig 默认值 */

package/dist/contracts/permission-checker.d.ts

@@ -1,7 +1,7 @@
 /**
  * 权限校验器接口（对齐 06-governance R16.8）
  */
-import type { ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult } from '@gt-fe/eap-contracts';
+import type { ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult } from '@eap/contracts';
 /**
  * IPermissionChecker — Runtime 执行期权限校验
  */

package/dist/contracts/trace-collector.d.ts

@@ -82,9 +82,9 @@ export interface ExecutionNodeEvent {
     /** 节点名称 */
     name: string;
     /** 节点类型 */
-    type: 'start' | 'llm' | 'tool' | 'skill' | 'condition' | 'end';
+    type: 'start' | 'llm' | 'tool' | 'skill' | 'condition' | 'hitl' | 'end';
     /** 工具运行环境（type=tool） */
-    toolRuntime?: 'local' | 'server' | 'both' | 'mock';
+    toolRuntime?: 'local' | 'server' | 'both';
     /** Agent 对外主键 */
     agentCode?: string;
     /** 输入数据 */
@@ -184,6 +184,20 @@ export interface ITraceCollector {
         outputTokens?: number;
         totalTokens?: number;
     }): Promise<void>;
+    /**
+     * Checkpoint 已落盘后的引用回调。Hosting 适配 TraceClient.recordCheckpointRef。
+     * Runtime 仅在同时有 traceId 与 spanId 时调用；不传 graph state 正文。
+     */
+    recordCheckpointRef?(input: {
+        checkpointId: string;
+        traceId: string;
+        spanId: string;
+        summary?: {
+            nodeId?: string;
+            threadId?: string;
+            step?: number;
+        };
+    }): Promise<void>;
     /**
      * 创建链路
      *

package/dist/debug/llm-turn-log.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 本地 LLM 回合落盘：每次模型调用写一份 JSON（入参、响应、URL、脱敏密钥、system 段）。
+ * 默认 `.eap/llm-turns/{sessionId}/`。EAP_LLM_TURN_LOG=0 关闭。
+ */
+export interface LlmTurnContext {
+    sessionId?: string;
+    taskId?: string;
+    nodeId?: string;
+    agentCode?: string;
+    correlationId?: string;
+}
+export interface LlmTurnRecord extends LlmTurnContext {
+    id: string;
+    ts: string;
+    url: string;
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    apiKey: string;
+    systemPrompt?: string;
+    systemSections?: Array<{
+        id: string;
+        title: string;
+        chars: number;
+        body?: string;
+    }>;
+    tools?: string[];
+    messages: Array<{
+        role: string;
+        content: string;
+        toolCallId?: string;
+        toolCalls?: unknown;
+    }>;
+    response: {
+        content: string;
+        toolCalls?: unknown;
+        reasoningContent?: string;
+        inputTokens: number;
+        outputTokens: number;
+        finishReason?: string;
+        error?: string;
+    };
+    latencyMs: number;
+}
+export interface LlmTurnIndexEntry {
+    id: string;
+    ts: string;
+    sessionId?: string;
+    taskId?: string;
+    nodeId?: string;
+    model: string;
+    url: string;
+    file: string;
+    inputTokens: number;
+    outputTokens: number;
+}
+export type LlmTurnLogKind = 'memory' | 'file' | 'postgres';
+export interface ILlmTurnLog {
+    readonly kind: LlmTurnLogKind;
+    record(turn: Omit<LlmTurnRecord, 'id' | 'ts'> & {
+        id?: string;
+        ts?: string;
+    }): Promise<LlmTurnRecord>;
+    list(sessionId: string): Promise<LlmTurnIndexEntry[]>;
+    read(sessionId: string, turnId: string): Promise<LlmTurnRecord | null>;
+    listSessions(): Promise<string[]>;
+    readonly baseDir: string;
+}
+export declare function finalizeLlmTurn(turn: Omit<LlmTurnRecord, 'id' | 'ts'> & {
+    id?: string;
+    ts?: string;
+}): LlmTurnRecord;
+export declare function toLlmTurnIndexEntry(record: LlmTurnRecord, file?: string): LlmTurnIndexEntry;
+export declare function maskApiKey(key: string | undefined): string;
+export declare function resolveLlmTurnDir(env?: NodeJS.ProcessEnv, cwd?: string): string;
+export declare function createFileLlmTurnLogFromEnv(env?: NodeJS.ProcessEnv): FileLlmTurnLog | undefined;
+export declare class InMemoryLlmTurnLog implements ILlmTurnLog {
+    readonly kind: "memory";
+    readonly baseDir = "memory://llm-turns";
+    private readonly bySession;
+    record(turn: Omit<LlmTurnRecord, 'id' | 'ts'> & {
+        id?: string;
+        ts?: string;
+    }): Promise<LlmTurnRecord>;
+    list(sessionId: string): Promise<LlmTurnIndexEntry[]>;
+    read(sessionId: string, turnId: string): Promise<LlmTurnRecord | null>;
+    listSessions(): Promise<string[]>;
+}
+export declare class FileLlmTurnLog implements ILlmTurnLog {
+    readonly baseDir: string;
+    readonly kind: "file";
+    constructor(baseDir: string);
+    record(turn: Omit<LlmTurnRecord, 'id' | 'ts'> & {
+        id?: string;
+        ts?: string;
+    }): Promise<LlmTurnRecord>;
+    list(sessionId: string): Promise<LlmTurnIndexEntry[]>;
+    read(sessionId: string, turnId: string): Promise<LlmTurnRecord | null>;
+    listSessions(): Promise<string[]>;
+}