@gt-fe/eap-runtime 0.0.8 → 0.0.10

package/dist/runtime/dev-runtime.js

@@ -30,8 +30,9 @@ import { RoutingLLMProvider } from '../providers/routing-llm-provider.js';
 import { createToolExecutor } from '../tool/create-tool-executor.js';
 import { MockToolExecutor } from '../tool/mock-tool-executor.js';
 import { DevToolExecutor } from '../tool/dev-tool-executor.js';
+import { withHarnessPrimitives } from '../tool/harness-primitives.js';
 import { AllowAllGovernanceClient, HttpGovernanceClient, } from '../governance/index.js';
-import { InvokeOrchestrator, StreamOrchestrator, SessionService, MessageService, SessionContextService, TaskService, LangGraphAdapter, HitlHandler, TokenBudgetService, InMemoryTokenBudgetRepository, TokenStatsService, TokenBudgetGuard, SessionBudgetChecker, createAgentRegistryClient, GraphLoader, } from '../index.js';
+import { InvokeOrchestrator, StreamOrchestrator, SessionService, MessageService, SessionContextService, TaskService, LangGraphAdapter, HitlHandler, TokenBudgetService, TokenStatsService, TokenBudgetGuard, SessionBudgetChecker, createAgentRegistryClient, GraphLoader, } from '../index.js';
 import { createAgentRuntime } from './agent-runtime.js';
 import { assembleRuntimeStorage } from './storage-profile.js';
 import { resolveSkillHotReload, watchPreinstallSkillRoot, watchSkillRoots } from '../registry/skill-tree.js';
@@ -46,43 +47,45 @@ export function createDevRuntime() {
     const foundationConfigured = Boolean(process.env.FOUNDATION_SERVICE_URL && process.env.FOUNDATION_SERVICE_URL.trim().length > 0);
     const toolExecutionMode = (process.env.EAP_TOOL_EXECUTION_MODE ?? 'mcp').toLowerCase();
     const deploymentContext = process.env.EAP_DEPLOYMENT_CONTEXT ?? 'server';
-    // ── 存储 profile（默认 dev：File Session/Message/Checkpoint）──
-    // 兼容旧变量：EAP_SESSION_STORE=memory → 强制 test（全内存）
-    const legacySessionStore = process.env.EAP_SESSION_STORE?.toLowerCase();
+    // ── 存储：未配库默认文件；配齐 DATABASE + Redis 则 Redis+PG ──
     const storage = assembleRuntimeStorage({
-        defaultProfile: legacySessionStore === 'memory' || legacySessionStore === 'in-memory' ? 'test' : 'dev',
-        profile: legacySessionStore === 'memory' || legacySessionStore === 'in-memory'
-            ? 'test'
-            : undefined,
+        defaultProfile: 'dev',
     });
+    const turnLog = process.env.EAP_LLM_TURN_LOG === '0' ? undefined : storage.turnLog;
     // ── LLM Provider（本地 eap.config runtime.llm 优先，再 Foundation 路由，再环境直连）──
     let llmProviderKind;
     let llmProvider;
     const localLlm = process.env.EAP_LLM_MODE === 'local';
     if (localLlm || (!foundationConfigured && process.env.OPENAI_API_KEY)) {
         llmProvider = localLlm
-            ? createLocalLlmProvider(requireLocalLlmConnections())
+            ? createLocalLlmProvider(requireLocalLlmConnections(), turnLog)
             : new HttpLLMProvider({
                 apiKey: process.env.OPENAI_API_KEY ?? '',
                 baseUrl: process.env.OPENAI_BASE_URL,
                 defaultModel: process.env.EAP_DEFAULT_MODEL,
+                turnLog,
             });
         llmProviderKind = 'openai-http';
     }
     else if (foundationConfigured) {
-        llmProvider = new RoutingLLMProvider({ foundationUrl });
+        llmProvider = new RoutingLLMProvider({ foundationUrl, turnLog });
         llmProviderKind = 'routing';
     }
     else {
-        llmProvider = createDefaultLLMProvider();
+        llmProvider = createDefaultLLMProvider(turnLog);
         llmProviderKind = 'echo';
     }
     // ── Tool Executor（显式 mock → dev+mcp 直连，缺配置失败 → 通用路由）──
-    const toolExecutor = toolExecutionMode === 'mock'
+    const needsHarnessWrap = toolExecutionMode === 'mock' ||
+        (toolExecutionMode === 'mcp' && deploymentContext === 'dev');
+    const innerExecutor = toolExecutionMode === 'mock'
         ? new MockToolExecutor({ toolsDir: process.env.EAP_LOCAL_TOOLS_DIR })
         : toolExecutionMode === 'mcp' && deploymentContext === 'dev'
             ? new DevToolExecutor()
             : createToolExecutor({ foundationUrl, deploymentContext });
+    const toolExecutor = needsHarnessWrap
+        ? withHarnessPrimitives(innerExecutor)
+        : innerExecutor;
     // ── Governance ──
     const governanceClient = process.env.GOVERNANCE_DISABLED === '1' || !foundationConfigured
         ? new AllowAllGovernanceClient()
@@ -99,7 +102,7 @@ export function createDevRuntime() {
     const sessionContextService = new SessionContextService(sessionService, messageService);
     // ── Task / Token ──
     const taskService = new TaskService();
-    const budgetService = new TokenBudgetService(new InMemoryTokenBudgetRepository());
+    const budgetService = new TokenBudgetService(storage.tokenBudgetRepository);
     const tokenStatsService = new TokenStatsService();
     const tokenBudgetGuard = new TokenBudgetGuard(budgetService);
     const sessionBudgetChecker = new SessionBudgetChecker(budgetService);
@@ -168,6 +171,8 @@ export function createDevRuntime() {
         hitlHandler,
         graphLoader,
         messageService,
+        sessionService,
+        turnLog,
     });
     return {
         invokeOrchestrator,
@@ -177,6 +182,7 @@ export function createDevRuntime() {
         streamResumeHitl: (taskId, response) => agentRuntime.streamResumeHitl(taskId, response),
         sessionService,
         messageService,
+        turnLog,
         sessionContextService,
         taskService,
         tokenStatsService,
@@ -189,9 +195,10 @@ export function createDevRuntime() {
             llmDefaultModel: process.env.EAP_DEFAULT_MODEL ?? 'DeepSeek-V4-Pro',
             governanceKind: governanceClient instanceof AllowAllGovernanceClient ? 'AllowAll' : 'Http',
             storageProfile: storage.profile,
-            sessionStoreKind: storage.diagnostics.sessionKind === 'file' ? 'file' : 'in-memory',
+            sessionStoreKind: storage.diagnostics.sessionKind,
             messageStoreKind: storage.diagnostics.messageKind,
             checkpointKind: storage.diagnostics.checkpointKind,
+            llmTurnKind: storage.diagnostics.llmTurnKind,
             foundationConfigured,
             skillHotReload,
         },

package/dist/runtime/index.d.ts

@@ -1,4 +1,4 @@
-export { AgentRuntime, createAgentRuntime, type AgentRuntimeDeps, type ForkRelationRecord, type RecordForkRelation, } from './agent-runtime.js';
-export type { ExecuteParams, ExecuteResult, ForkOverrides, ForkResult, HitlResponse, ResumeHitlResult, SSEEvent, } from './types.js';
+export { AgentRuntime, createAgentRuntime, type AgentRuntimeDeps, type ForkRelationRecord, type RecordForkRelation, type ConversationDetail, } from './agent-runtime.js';
+export type { ExecuteParams, ExecuteResult, ForkParams, ForkOverrides, ForkResult, HitlResponse, ResumeHitlResult, SSEEvent, } from './types.js';
 export { createDevRuntime, type DevRuntime, } from './dev-runtime.js';
-export { assembleRuntimeStorage, resolveRuntimeStorageProfile, type RuntimeStorageProfile, type AssembleRuntimeStorageOptions, type AssembledRuntimeStorage, } from './storage-profile.js';
+export { assembleRuntimeStorage, resolveRuntimeStorageProfile, resolveDevStorageDirs, type RuntimeStorageProfile, type AssembleRuntimeStorageOptions, type AssembledRuntimeStorage, } from './storage-profile.js';

package/dist/runtime/index.js

@@ -1,3 +1,3 @@
 export { AgentRuntime, createAgentRuntime, } from './agent-runtime.js';
 export { createDevRuntime, } from './dev-runtime.js';
-export { assembleRuntimeStorage, resolveRuntimeStorageProfile, } from './storage-profile.js';
+export { assembleRuntimeStorage, resolveRuntimeStorageProfile, resolveDevStorageDirs, } from './storage-profile.js';

package/dist/runtime/storage-profile.d.ts

@@ -9,11 +9,13 @@ import type { ICheckpointSaver } from '../checkpoint/contracts/checkpoint-saver.
 import { type IPgPool } from '../checkpoint/pg-checkpoint-saver.js';
 import type { ISessionRepository } from '../session/session.service.js';
 import type { IFullMessageRepository } from '../session/message.service.js';
+import type { ILlmTurnLog } from '../debug/llm-turn-log.js';
+import { type ITokenBudgetRepository } from '../token/token-budget.service.js';
 export type RuntimeStorageProfile = 'test' | 'dev' | 'integration' | 'production';
 export interface AssembleRuntimeStorageOptions {
     /** 显式 profile；缺省读 EAP_RUNTIME_STORAGE_PROFILE */
     profile?: RuntimeStorageProfile;
-    /** 未指定 profile 时的默认值（dev-runtime → dev；embedded → integration） */
+    /** 未指定 profile 且未配库时的默认值（本地 CLI → `dev` 文件） */
     defaultProfile: RuntimeStorageProfile;
     /** File Checkpoint / Session / Message 根目录 */
     checkpointDir?: string;
@@ -31,20 +33,27 @@ export interface AssembledRuntimeStorage {
     /** undefined = SessionService 默认 InMemory */
     sessionRepository?: ISessionRepository;
     messageRepository: IFullMessageRepository;
+    turnLog: ILlmTurnLog;
+    tokenBudgetRepository: ITokenBudgetRepository;
     diagnostics: {
         profile: RuntimeStorageProfile;
-        checkpointKind: 'memory' | 'file' | 'redis+pg' | 'pg';
-        sessionKind: 'memory' | 'file';
-        messageKind: 'memory' | 'file' | 'postgres';
+        checkpointKind: 'file' | 'redis+pg';
+        sessionKind: 'file' | 'hosting';
+        messageKind: 'file' | 'postgres';
+        llmTurnKind: 'file' | 'postgres';
+        tokenBudgetKind: 'process' | 'postgres';
     };
 }
 export declare function resolveRuntimeStorageProfile(explicit: RuntimeStorageProfile | undefined, defaultProfile: RuntimeStorageProfile, env?: NodeJS.ProcessEnv): RuntimeStorageProfile;
+/** 本地 File 存储默认落工程 `.eap/`，可用 EAP_DATA_DIR / EAP_*_DIR 覆盖。 */
+export declare function resolveDevStorageDirs(env?: NodeJS.ProcessEnv, cwd?: string): {
+    checkpointDir: string;
+    sessionDir: string;
+    messageDir: string;
+};
 /**
- * 按 profile 装配 Checkpoint / Session / Message 存储
- *
- * - test: 全内存
- * - dev: File Checkpoint + File Session + File Message
- * - integration/production: Message=PG；Checkpoint=Redis 热 + PG 备；
- *   Session 仓储不落 PG（sessionId 权威在 Hosting.sessions，Runtime 内存采纳）
+ * 按 profile 装配 Checkpoint / Message / Token / LLM 回合存储。
+ * `dev`：文件。其余 profile：Redis + PostgreSQL（缺配置则抛错）。
+ * 未设 profile 时：已配置 DB 或 Redis 则按 Redis+PostgreSQL；否则使用 defaultProfile。
  */
 export declare function assembleRuntimeStorage(options: AssembleRuntimeStorageOptions, env?: NodeJS.ProcessEnv): AssembledRuntimeStorage;

package/dist/runtime/storage-profile.js

@@ -6,16 +6,19 @@
  */
 // @ts-expect-error pg 无内置类型；Hosting 侧同样按 any 使用
 import pg from 'pg';
+import path from 'node:path';
 import { Redis } from 'ioredis';
 import { FileCheckpointSaver } from '../checkpoint/file-checkpoint-saver.js';
 import { PostgresCheckpointSaver } from '../checkpoint/pg-checkpoint-saver.js';
 import { RedisCheckpointSaver } from '../checkpoint/redis-checkpoint-saver.js';
 import { CompositeCheckpointSaver } from '../checkpoint/composite-checkpoint-saver.js';
-import { InMemoryCheckpointSaver } from '../checkpoint/in-memory-checkpoint-saver.js';
 import { FileSessionRepository } from '../session/file-session.repository.js';
-import { InMemoryFullMessageRepository } from '../session/message.service.js';
 import { FileMessageRepository } from '../session/file-message.repository.js';
 import { PostgresMessageRepository } from '../session/pg-message.repository.js';
+import { FileLlmTurnLog, resolveLlmTurnDir } from '../debug/llm-turn-log.js';
+import { PostgresLlmTurnLog } from '../debug/pg-llm-turn-log.js';
+import { InMemoryTokenBudgetRepository } from '../token/token-budget.service.js';
+import { PostgresTokenBudgetRepository } from '../token/pg-token-budget.repository.js';
 const { Pool } = pg;
 const VALID_PROFILES = new Set([
     'test',
@@ -23,11 +26,20 @@ const VALID_PROFILES = new Set([
     'integration',
     'production',
 ]);
+function hasDbEnv(env) {
+    return Boolean(env.DATABASE_URL?.trim() || (env.DB_HOST && env.DB_NAME && env.DB_USER));
+}
+function hasRedisEnv(env) {
+    return Boolean(env.REDIS_URL?.trim() || env.REDIS_HOST);
+}
 export function resolveRuntimeStorageProfile(explicit, defaultProfile, env = process.env) {
     const raw = explicit ?? env.EAP_RUNTIME_STORAGE_PROFILE;
     if (raw && VALID_PROFILES.has(raw)) {
         return raw;
     }
+    if (hasDbEnv(env) || hasRedisEnv(env)) {
+        return 'integration';
+    }
     return defaultProfile;
 }
 function requireDbEnv(env) {
@@ -39,12 +51,12 @@ function requireDbEnv(env) {
     if (!env.DB_USER && !env.DATABASE_URL)
         missing.push('DB_USER 或 DATABASE_URL');
     if (missing.length > 0) {
-        throw new Error(`[EAP_RUNTIME_STORAGE_PROFILE] integration/production 缺少数据库配置: ${missing.join(', ')}`);
+        throw new Error(`[EAP_RUNTIME_STORAGE_PROFILE] Redis+PostgreSQL 路径缺少数据库配置: ${missing.join(', ')}`);
     }
 }
 function requireRedisEnv(env) {
     if (!env.REDIS_HOST && !env.REDIS_URL) {
-        throw new Error('[EAP_RUNTIME_STORAGE_PROFILE] integration/production 缺少 REDIS_HOST 或 REDIS_URL（禁止回退 File Checkpoint）');
+        throw new Error('[EAP_RUNTIME_STORAGE_PROFILE] Redis+PostgreSQL 路径缺少 REDIS_HOST 或 REDIS_URL');
     }
 }
 function createPgPoolFromEnv(env) {
@@ -73,44 +85,41 @@ function createRedisFromEnv(env) {
         maxRetriesPerRequest: 1,
     });
 }
+/** 本地 File 存储默认落工程 `.eap/`，可用 EAP_DATA_DIR / EAP_*_DIR 覆盖。 */
+export function resolveDevStorageDirs(env = process.env, cwd = process.cwd()) {
+    const root = env.EAP_DATA_DIR?.trim() || path.join(cwd, '.eap');
+    const checkpointDir = env.EAP_CHECKPOINT_DIR?.trim() || path.join(root, 'checkpoints');
+    const sessionDir = env.EAP_SESSION_DIR?.trim() || path.join(root, 'sessions');
+    const messageDir = env.EAP_MESSAGE_DIR?.trim() || path.join(sessionDir, 'messages');
+    return { checkpointDir, sessionDir, messageDir };
+}
 /**
- * 按 profile 装配 Checkpoint / Session / Message 存储
- *
- * - test: 全内存
- * - dev: File Checkpoint + File Session + File Message
- * - integration/production: Message=PG；Checkpoint=Redis 热 + PG 备；
- *   Session 仓储不落 PG（sessionId 权威在 Hosting.sessions，Runtime 内存采纳）
+ * 按 profile 装配 Checkpoint / Message / Token / LLM 回合存储。
+ * `dev`：文件。其余 profile：Redis + PostgreSQL（缺配置则抛错）。
+ * 未设 profile 时：已配置 DB 或 Redis 则按 Redis+PostgreSQL；否则使用 defaultProfile。
  */
 export function assembleRuntimeStorage(options, env = process.env) {
     const profile = resolveRuntimeStorageProfile(options.profile, options.defaultProfile, env);
-    const checkpointDir = options.checkpointDir ?? env.EAP_CHECKPOINT_DIR ?? '/tmp/eap-checkpoints';
-    const sessionDir = options.sessionDir ?? env.EAP_SESSION_DIR ?? '/tmp/eap-sessions';
-    const messageDir = options.messageDir ?? env.EAP_MESSAGE_DIR ?? `${sessionDir.replace(/\/$/, '')}/messages`;
-    if (profile === 'test') {
-        return {
-            profile,
-            checkpointSaver: new InMemoryCheckpointSaver(),
-            sessionRepository: undefined,
-            messageRepository: new InMemoryFullMessageRepository(),
-            diagnostics: {
-                profile,
-                checkpointKind: 'memory',
-                sessionKind: 'memory',
-                messageKind: 'memory',
-            },
-        };
-    }
-    if (profile === 'dev') {
+    const defaults = resolveDevStorageDirs(env);
+    const checkpointDir = options.checkpointDir ?? defaults.checkpointDir;
+    const sessionDir = options.sessionDir ?? defaults.sessionDir;
+    const messageDir = options.messageDir ?? defaults.messageDir;
+    const useFiles = profile === 'dev';
+    if (useFiles) {
         return {
             profile,
             checkpointSaver: new FileCheckpointSaver(checkpointDir),
             sessionRepository: new FileSessionRepository({ baseDir: sessionDir }),
             messageRepository: new FileMessageRepository({ baseDir: messageDir }),
+            turnLog: new FileLlmTurnLog(resolveLlmTurnDir(env)),
+            tokenBudgetRepository: new InMemoryTokenBudgetRepository(),
             diagnostics: {
                 profile,
                 checkpointKind: 'file',
                 sessionKind: 'file',
                 messageKind: 'file',
+                llmTurnKind: 'file',
+                tokenBudgetKind: 'process',
             },
         };
     }
@@ -128,11 +137,15 @@ export function assembleRuntimeStorage(options, env = process.env) {
         checkpointSaver,
         sessionRepository: undefined,
         messageRepository: new PostgresMessageRepository(pool),
+        turnLog: new PostgresLlmTurnLog(pool),
+        tokenBudgetRepository: new PostgresTokenBudgetRepository(pool),
         diagnostics: {
             profile,
             checkpointKind: 'redis+pg',
-            sessionKind: 'memory',
+            sessionKind: 'hosting',
             messageKind: 'postgres',
+            llmTurnKind: 'postgres',
+            tokenBudgetKind: 'postgres',
         },
     };
 }

package/dist/runtime/types.d.ts

@@ -12,12 +12,8 @@ import type { GraphMessage } from '../graph/contracts/executable-graph.js';
 import type { SSEEvent } from '../sse/contracts/sse-emitter.contract.js';
 /** 同步/流式执行参数 */
 export interface ExecuteParams {
-    /**
-     * @deprecated 使用 agentCode；保留仅为迁移双读
-     */
-    agentId?: string;
-    /** 对外主键（优先） */
-    agentCode?: string;
+    /** 对外主键 */
+    agentCode: string;
     input: string;
     /** 平台执行上下文（Hosting / eap dev 注入，对齐 04 R15） */
     executionContext?: ExecutionContext;
@@ -48,6 +44,16 @@ export interface HitlResponse {
      */
     threadId?: string;
 }
+/** Fork 入参：上层先发 taskId / traceId，Runtime 不再 createFlow */
+export interface ForkParams {
+    checkpointId: string;
+    /** 上层已发号的 Task ID（Hosting createTask / 本地 UUID） */
+    taskId: string;
+    /** 上层已创建的 Trace id（Hosting createTrace / 本地 UUID） */
+    traceId: string;
+    executionContext?: ExecutionContext;
+    overrides?: ForkOverrides;
+}
 /** Fork 参数覆盖 */
 export interface ForkOverrides {
     model?: string;
@@ -56,11 +62,7 @@ export interface ForkOverrides {
     state?: Record<string, unknown>;
     /** 源 Trace ID（未提供时从 checkpoint 元数据读取） */
     originalTraceId?: string;
-    /**
-     * @deprecated 使用 agentCode
-     */
-    agentId?: string;
-    /** 执行所用 Agent（未提供时从 checkpoint state 读取） */
+    /** 执行所用 Agent（未提供时从 checkpoint state.agentCode 读取） */
     agentCode?: string;
     /** 预装版本（未提供时从 checkpoint state.agentVersion 读取） */
     agentVersion?: string;
@@ -95,12 +97,8 @@ export interface ForkResult {
  * - 该 session 已有历史时，视作已种入，跳过写入（exactly-once 幂等）。
  */
 export interface SeedSessionMessagesParams {
-    /**
-     * @deprecated 使用 agentCode；保留仅为迁移双读
-     */
-    agentId?: string;
-    /** 对外主键（优先） */
-    agentCode?: string;
+    /** 对外主键 */
+    agentCode: string;
     /** 预装版本（写入 session.metadata.agentVersion，续聊回退） */
     agentVersion?: string;
     /** 会话 ID；未提供时新建 session */

package/dist/server.js

@@ -49,7 +49,7 @@ const server = createServer(async (req, res) => {
     if (req.method === 'GET' && url.pathname === '/metrics') {
         sendJson(res, 200, {
             mode: 'standalone',
-            checkpointDir: process.env.EAP_CHECKPOINT_DIR ?? '/tmp/eap-checkpoints',
+            checkpointDir: process.env.EAP_CHECKPOINT_DIR ?? '.eap/checkpoints',
             foundationUrl: process.env.FOUNDATION_SERVICE_URL ?? 'http://localhost:3100',
         });
         return;

package/dist/session/session.service.d.ts

@@ -102,6 +102,8 @@ export interface ISessionRepository {
     findById(id: string): Promise<SessionRecord | null>;
     findByUserId(userId: string, limit?: number, offset?: number): Promise<SessionRecord[]>;
     update(session: SessionRecord): Promise<void>;
+    /** 本地排查：列出全部未删除会话（File / 内存实现；PG 可不提供） */
+    listAll?(): Promise<SessionRecord[]>;
 }
 /**
  * IMessageRepository — Message 查询接口（最小定义）
@@ -143,6 +145,7 @@ export declare class InMemorySessionRepository implements ISessionRepository {
     findById(id: string): Promise<SessionRecord | null>;
     findByUserId(userId: string, limit?: number, offset?: number): Promise<SessionRecord[]>;
     update(session: SessionRecord): Promise<void>;
+    listAll(): Promise<SessionRecord[]>;
 }
 /**
  * InMemoryMessageRepository — 内存 Message 存储（stub）
@@ -181,6 +184,8 @@ export declare class SessionService {
         limit?: number;
         offset?: number;
     }): Promise<SessionRecord[]>;
+    /** 本地排查：列出全部会话（仓储未实现 listAll 时返回空） */
+    listAllSessions(): Promise<SessionRecord[]>;
     /**
      * 归档 Session（标记为 archived）
      */

package/dist/session/session.service.js

@@ -35,6 +35,11 @@ export class InMemorySessionRepository {
     async update(session) {
         this.store.set(session.id, { ...session });
     }
+    async listAll() {
+        return Array.from(this.store.values())
+            .filter((s) => !s.isDeleted)
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
 }
 /**
  * InMemoryMessageRepository — 内存 Message 存储（stub）
@@ -138,6 +143,13 @@ export class SessionService {
     async listSessions(userId, options) {
         return this.sessionRepository.findByUserId(userId, options?.limit, options?.offset);
     }
+    /** 本地排查：列出全部会话（仓储未实现 listAll 时返回空） */
+    async listAllSessions() {
+        if (typeof this.sessionRepository.listAll !== 'function') {
+            return [];
+        }
+        return this.sessionRepository.listAll();
+    }
     /**
      * 归档 Session（标记为 archived）
      */

package/dist/sse/events/index.d.ts

@@ -39,13 +39,13 @@ export declare const CORE_SSE_EVENTS: readonly ["session.created", "task.started
 /**
  * 可选事件类型（Agent 按需支持）
  */
-export declare const OPTIONAL_SSE_EVENTS: readonly ["skill.matched", "skill.unmatched", "skill.started", "skill.completed", "skill.failed", "reasoning.step", "tool.progress", "file.created", "file.updated", "code.executed", "collaboration.handed_off", "collaboration.subtask.started", "collaboration.subtask.completed", "plan.created", "plan.step.started", "plan.step.completed", "response.max_iterations_reached", "stats.node_token_usage"];
+export declare const OPTIONAL_SSE_EVENTS: readonly ["skill.matched", "skill.unmatched", "skill.started", "skill.completed", "skill.failed", "skill.loaded", "skill.resource_read", "reasoning.step", "tool.progress", "file.created", "file.updated", "code.executed", "collaboration.handed_off", "collaboration.subtask.started", "collaboration.subtask.completed", "plan.created", "plan.step.started", "plan.step.completed", "response.max_iterations_reached", "stats.node_token_usage"];
 /**
  * SSEEventType — SSE 事件类型字符串联合类型
  */
-export type SSEEventType = 'session.created' | 'task.started' | 'task.completed' | 'task.error' | 'reasoning.started' | 'response.chunk' | 'tool.called' | 'tool.result' | 'tool.error' | 'hitl.waited' | 'hitl.resumed' | 'response.final' | 'stats.token_usage' | 'connection.heartbeat' | 'skill.matched' | 'skill.unmatched' | 'skill.started' | 'skill.completed' | 'skill.failed' | 'reasoning.step' | 'tool.progress' | 'file.created' | 'file.updated' | 'code.executed' | 'collaboration.handed_off' | 'collaboration.subtask.started' | 'collaboration.subtask.completed' | 'plan.created' | 'plan.step.started' | 'plan.step.completed' | 'response.max_iterations_reached' | 'stats.node_token_usage';
+export type SSEEventType = 'session.created' | 'task.started' | 'task.completed' | 'task.error' | 'reasoning.started' | 'response.chunk' | 'tool.called' | 'tool.result' | 'tool.error' | 'hitl.waited' | 'hitl.resumed' | 'response.final' | 'stats.token_usage' | 'connection.heartbeat' | 'skill.matched' | 'skill.unmatched' | 'skill.started' | 'skill.completed' | 'skill.failed' | 'skill.loaded' | 'skill.resource_read' | 'reasoning.step' | 'tool.progress' | 'file.created' | 'file.updated' | 'code.executed' | 'collaboration.handed_off' | 'collaboration.subtask.started' | 'collaboration.subtask.completed' | 'plan.created' | 'plan.step.started' | 'plan.step.completed' | 'response.max_iterations_reached' | 'stats.node_token_usage';
 import type { SessionCreatedPayload, TaskStartedPayload, TaskCompletedPayload, TaskErrorPayload } from './session-events.js';
-import type { SkillMatchedPayload, SkillUnmatchedPayload, SkillStartedPayload, SkillCompletedPayload, SkillFailedPayload } from './skill-events.js';
+import type { SkillMatchedPayload, SkillUnmatchedPayload, SkillStartedPayload, SkillCompletedPayload, SkillFailedPayload, SkillLoadedPayload, SkillResourceReadPayload } from './skill-events.js';
 import type { ReasoningStartedPayload, ReasoningStepPayload, ResponseChunkPayload } from './reasoning-events.js';
 import type { ToolCalledPayload, ToolResultPayload, ToolProgressPayload, ToolErrorPayload } from './tool-events.js';
 import type { FileCreatedPayload, FileUpdatedPayload } from './file-events.js';
@@ -79,6 +79,8 @@ export interface SSEEventPayloadMap {
     'skill.started': SkillStartedPayload;
     'skill.completed': SkillCompletedPayload;
     'skill.failed': SkillFailedPayload;
+    'skill.loaded': SkillLoadedPayload;
+    'skill.resource_read': SkillResourceReadPayload;
     'reasoning.step': ReasoningStepPayload;
     'tool.progress': ToolProgressPayload;
     'file.created': FileCreatedPayload;

package/dist/sse/events/index.js

@@ -59,6 +59,8 @@ export const OPTIONAL_SSE_EVENTS = [
     'skill.started',
     'skill.completed',
     'skill.failed',
+    'skill.loaded',
+    'skill.resource_read',
     'reasoning.step',
     'tool.progress',
     'file.created',

package/dist/sse/events/skill-events.d.ts

@@ -46,3 +46,14 @@ export interface SkillFailedPayload {
     skillName: string;
     error: string;
 }
+/** 读入 SKILL.md（Harness，不是业务 Tool） */
+export interface SkillLoadedPayload {
+    skillId: string;
+    skillName?: string;
+    path: string;
+}
+/** 读取 Skill 包内附属文件 */
+export interface SkillResourceReadPayload {
+    skillId?: string;
+    path: string;
+}

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

@@ -32,6 +32,16 @@ export declare class InMemoryTraceCollector implements ITraceCollector {
         status: 'completed' | 'failed';
         error?: string;
     }): Promise<void>;
+    recordCheckpointRef(_input: {
+        checkpointId: string;
+        traceId: string;
+        spanId: string;
+        summary?: {
+            nodeId?: string;
+            threadId?: string;
+            step?: number;
+        };
+    }): Promise<void>;
     /** 获取所有会话（调试用） */
     getAllSessions(): TraceSession[];
 }

package/dist/sse/trace-collector.js

@@ -54,6 +54,7 @@ export class InMemoryTraceCollector {
         return `link-node-${randomUUID()}`;
     }
     async completeLinkNode(_nodeId, _params) { }
+    async recordCheckpointRef(_input) { }
     /** 获取所有会话（调试用） */
     getAllSessions() {
         return Array.from(this.sessions.values());

package/dist/token/token-budget.service.d.ts

@@ -32,7 +32,7 @@ export interface BudgetRecord {
 /**
  * ITokenBudgetRepository — 配额记录持久化抽象
  *
- * 由 InMemoryTokenBudgetRepository（默认）或 MySQL 实现注入。
+ * 由 InMemoryTokenBudgetRepository 或 PostgresTokenBudgetRepository 注入。
  */
 export interface ITokenBudgetRepository {
     /**
@@ -47,7 +47,7 @@ export interface ITokenBudgetRepository {
 /**
  * InMemoryTokenBudgetRepository — 基于 Map 的内存持久化
  *
- * 适用于单进程/测试场景。生产环境应替换为 MySQL 实现。
+ * 用于 `profile=dev` 文件路径及单测。Redis+PostgreSQL 路径使用 PostgresTokenBudgetRepository。
  */
 export declare class InMemoryTokenBudgetRepository implements ITokenBudgetRepository {
     private store;

package/dist/token/token-budget.service.js

@@ -15,7 +15,7 @@
 /**
  * InMemoryTokenBudgetRepository — 基于 Map 的内存持久化
  *
- * 适用于单进程/测试场景。生产环境应替换为 MySQL 实现。
+ * 用于 `profile=dev` 文件路径及单测。Redis+PostgreSQL 路径使用 PostgresTokenBudgetRepository。
  */
 export class InMemoryTokenBudgetRepository {
     store = new Map();

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

@@ -9,6 +9,7 @@ import { HttpToolExecutor } from './http-tool-executor.js';
 import { 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';
 export class EmptyInstallStore {
     get() {
         return null;
@@ -48,7 +49,7 @@ export function createToolExecutor(options) {
     const transport = resolveGatewayTransport(options.gatewayTransport);
     const serverExecutor = createServerExecutor(options.foundationUrl, transport, options.httpTimeout);
     const localExecutor = new LocalToolExecutor({ installStore });
-    return new ToolExecutionRouter({
+    return withHarnessPrimitives(new ToolExecutionRouter({
         httpExecutor: serverExecutor,
         localExecutor,
         installStore,
@@ -56,5 +57,5 @@ export function createToolExecutor(options) {
         toolTypes: options.toolTypes,
         toolRuntimes: options.toolRuntimes,
         forceToolServer: options.forceToolServer,
-    });
+    }));
 }

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

@@ -0,0 +1,32 @@
+/**
+ * 平台默认 Harness 原语：read_file / write_file / execute_command。
+ *
+ * 不写进 agent.manifest.toolsets。同名业务工具优先（问数 file-io 等）。
+ * 读：工作目录 + 技能包 + EAP_LOCAL_SKILLS_DIR + FILE_IO_ROOT。
+ * 写：仅工作目录，且不跟随符号链接。
+ * 命令：cwd 落在 jail 内；环境变量白名单，不继承 process.env。
+ */
+import type { LoadedToolMap } from './loaded-tool-definition.js';
+import type { IToolExecutor, ToolCallRequest, ToolCallResult } from './tool-executor.interface.js';
+export declare function mergeHarnessPrimitives(loadedTools: LoadedToolMap | undefined): LoadedToolMap | undefined;
+/** 装配点：业务 toolsets + 平台 Harness 原语。 */
+export declare function assembleLoadedTools(loadedTools: LoadedToolMap | undefined): LoadedToolMap | undefined;
+export interface HarnessJailOptions {
+    workdir?: string;
+    extraRoots?: string[];
+}
+export declare function resolveJailRoots(options?: HarnessJailOptions): string[];
+export declare function resolveJailedPath(requested: string, roots: string[], opts?: {
+    mustExist?: boolean;
+}): string;
+export declare class HarnessPrimitiveExecutor implements IToolExecutor {
+    private readonly workdir?;
+    private readonly extraRoots?;
+    constructor(options?: HarnessJailOptions);
+    private rootsFor;
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+    private readFile;
+    private writeFile;
+    private executeCommand;
+}
+export declare function withHarnessPrimitives(inner: IToolExecutor, options?: HarnessJailOptions): IToolExecutor;