@gt-fe/eap-runtime 0.0.20 → 0.0.22

package/dist/runtime/dev-rag-deps.d.ts

@@ -0,0 +1,21 @@
+/**
+ * dev 装配的 rag 依赖 — createDevRuntime 检测显式配置后自动注入
+ *
+ * 启用条件：EAP_EMBED_API_KEY 存在（缺省不注入，行为与无 rag 的 master 一致）。
+ * retriever 惰性初始化：vector-engine（better-sqlite3+sqlite-vec，native 依赖）
+ * 只在首次检索时动态 import——装配期零 native 加载，服务端部署不受影响。
+ * import 目标可用 EAP_VECTOR_ENGINE_PATH 指定绝对路径（默认解析 @eap/vector-engine；
+ * eap-cli 发版链等无该包的环境走绝对路径注入）。
+ *
+ * 环境变量（与 .local 演示脚本同一套）：
+ * - EAP_EMBED_API_KEY / EAP_EMBED_BASE_URL / EAP_EMBED_MODEL / EAP_EMBED_DIMS：embedding 网关
+ * - RAG_DB：向量库路径（缺省 ~/.eap/rag/agent.db）
+ */
+import type { IRetriever, RagNodeDeps } from '../graph/nodes/rag/index.js';
+/**
+ * dev rag 装配：EAP_EMBED_API_KEY 显式配置才启用，否则 undefined（不注入）。
+ * llmProvider 复用 dev 装配已构造的实例（与 llm 节点同一体系）。
+ * EAP_RAG_TRACE=1 时接 console 观测 rag.* 事件流（轮次决策/各源检索/降噪/收束），
+ * 供多源融合行为观察；缺省静默。
+ */
+export declare function createDevRagNodeDeps(llmProvider: RagNodeDeps['llmProvider'], loadFn?: () => Promise<IRetriever>): RagNodeDeps | undefined;

package/dist/runtime/dev-rag-deps.js

@@ -0,0 +1,186 @@
+/**
+ * dev 装配的 rag 依赖 — createDevRuntime 检测显式配置后自动注入
+ *
+ * 启用条件：EAP_EMBED_API_KEY 存在（缺省不注入，行为与无 rag 的 master 一致）。
+ * retriever 惰性初始化：vector-engine（better-sqlite3+sqlite-vec，native 依赖）
+ * 只在首次检索时动态 import——装配期零 native 加载，服务端部署不受影响。
+ * import 目标可用 EAP_VECTOR_ENGINE_PATH 指定绝对路径（默认解析 @eap/vector-engine；
+ * eap-cli 发版链等无该包的环境走绝对路径注入）。
+ *
+ * 环境变量（与 .local 演示脚本同一套）：
+ * - EAP_EMBED_API_KEY / EAP_EMBED_BASE_URL / EAP_EMBED_MODEL / EAP_EMBED_DIMS：embedding 网关
+ * - RAG_DB：向量库路径（缺省 ~/.eap/rag/agent.db）
+ */
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, watchFile } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { appendFileSync } from 'node:fs';
+// 惰性读 env：模块顶层读不到（runtime 经 sdk import 链早于 CLI 灌 .env.local 执行）
+const trace = (line) => {
+    console.log(line);
+    const f = process.env.EAP_RAG_TRACE_FILE;
+    if (f)
+        appendFileSync(f, line + '\n', 'utf-8');
+};
+/** 入库日志环形缓冲（globalThis 桥接：Playground 服务同进程读，GET /api/rag-ingest-log） */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const ingestLogBuf = (globalThis.__ragIngestLog ??= []);
+const ingestLog = (line) => {
+    const ts = new Date().toISOString().slice(11, 19);
+    ingestLogBuf.push(`[${ts}] ${line}`);
+    if (ingestLogBuf.length > 200)
+        ingestLogBuf.splice(0, ingestLogBuf.length - 200);
+};
+import { HttpEmbedder, LocalSqliteRetriever } from '../graph/nodes/rag/index.js';
+/** 惰性 IRetriever：首次调用才加载真实现；加载失败不缓存，允许下轮重试 */
+class LazyLocalRetriever {
+    load;
+    sourceId = 'local';
+    implPromise;
+    constructor(load) {
+        this.load = load;
+    }
+    ensure() {
+        this.implPromise ??= this.load().catch((err) => {
+            this.implPromise = undefined; // 失败不缓存，下次调用重试加载
+            throw err;
+        });
+        return this.implPromise;
+    }
+    async retrieve(query, opts) {
+        return (await this.ensure()).retrieve(query, opts);
+    }
+    async retrieveByKeyword(query, opts) {
+        const impl = await this.ensure();
+        if (!impl.retrieveByKeyword)
+            return [];
+        return impl.retrieveByKeyword(query, opts);
+    }
+}
+/** 默认加载器：HttpEmbedder + vector-engine + LocalSqliteRetriever（单库：RAG_DB） */
+async function loadLocalRetriever() {
+    const dims = Number(process.env.EAP_EMBED_DIMS ?? 1024);
+    const embedder = new HttpEmbedder({
+        baseUrl: String(process.env.EAP_EMBED_BASE_URL ?? 'https://gtaiapi.gtcloud.cn'),
+        model: String(process.env.EAP_EMBED_MODEL ?? 'Qwen3-Embedding-8B'),
+        apiKey: String(process.env.EAP_EMBED_API_KEY ?? ''),
+        dims,
+        dimensions: dims,
+    });
+    const moduleName = process.env.EAP_VECTOR_ENGINE_PATH ?? '@eap/vector-engine';
+    // Windows 绝对路径须转 file:// URL（盘符字母否则被解析为 URL scheme）
+    const spec = /^[a-zA-Z]:[\\/]/.test(moduleName) ? pathToFileURL(moduleName).href : moduleName;
+    const mod = (await import(spec));
+    const dbPath = process.env.RAG_DB ?? join(homedir(), '.eap', 'rag', 'agent.db');
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const engine = await mod.createAsyncEngine({ dbPath, dims });
+    // 自动向量化：EAP_RAG_AUTO_INGEST=1 时常驻调度器扫授权目录，文件放入即入库
+    // （写入侧归宿主/桌面语义；dev 演示用轮询，生产为授权事件触发）。
+    // RAG_DOCS_DIR 支持 `;` 分隔多目录——"授权一个新文件夹" = 追加一个路径。
+    //
+    // 授权清单热更新（客户端授权动作的 dev 模拟）：RAG_AUTHORIZED_DIRS_FILE（json
+    // {"dirs":[...]}，缺省 <库目录>/authorized-dirs.json）存在则覆盖 RAG_DOCS_DIR，
+    // 文件变更 → scheduler.updateDirs 即时生效（新目录入库/移除软删），全程不重启。
+    if (process.env.EAP_RAG_AUTO_INGEST) {
+        const envDirs = (process.env.RAG_DOCS_DIR ?? join(dirname(dbPath), 'docs'))
+            .split(';')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const authFile = process.env.RAG_AUTHORIZED_DIRS_FILE ?? join(dirname(dbPath), 'authorized-dirs.json');
+        const readAuthDirs = () => {
+            try {
+                const parsed = JSON.parse(readFileSync(authFile, 'utf-8'));
+                if (Array.isArray(parsed.dirs) && parsed.dirs.every((d) => typeof d === 'string')) {
+                    const dirs = parsed.dirs.map((d) => d.trim()).filter(Boolean);
+                    return dirs.length ? dirs : undefined; // 空清单视为无效，防误清库
+                }
+            }
+            catch {
+                // 文件不存在/解析失败：保持现清单
+            }
+            return undefined;
+        };
+        let currentDirs = readAuthDirs() ?? envDirs;
+        const scheduler = new mod.IngestScheduler({
+            engine,
+            embedder,
+            userId: process.env.RAG_USER ?? 'anonymous',
+            dirs: currentDirs,
+            intervalMs: Number(process.env.EAP_RAG_SCAN_INTERVAL_MS ?? 30_000),
+            watch: process.env.EAP_RAG_SCAN_MODE !== 'interval',
+            onEvent: (e) => {
+                if (e.type === 'file.ingested') {
+                    const line = `[rag-ingest] 📥 ${String(e['filePath']).split('\\').pop()} → ${e['chunks']} 片`;
+                    console.log(line);
+                    ingestLog(line);
+                }
+                else if (e.type === 'file.failed') {
+                    const line = `[rag-ingest] ✗ ${String(e['filePath']).split('\\').pop()}: ${e['error']}`;
+                    console.log(line);
+                    ingestLog(line);
+                }
+            },
+        });
+        scheduler.start();
+        ingestLog(`🚀 自动向量化已启动：${currentDirs.length} 个授权目录`);
+        console.log(`[rag-ingest] 自动向量化已启动：目录 ${currentDirs.join('; ')}（${Number(process.env.EAP_RAG_SCAN_INTERVAL_MS ?? 30_000) / 1000}s 轮询${existsSync(authFile) ? `，授权清单 ${authFile} 热更新` : ''}）`);
+        // 授权清单文件变更 → updateDirs（编辑器保存/前端写入均触发；stat 轮询最稳）
+        watchFile(authFile, { interval: 2000 }, () => {
+            const next = readAuthDirs();
+            if (next && next.join(';') !== currentDirs.join(';')) {
+                currentDirs = next;
+                scheduler.updateDirs(next);
+                const line = `[rag-ingest] 🔑 授权目录更新（免重启生效）：${next.length} 个目录`;
+                console.log(line + `（${next.join('; ')}）`);
+                ingestLog(line);
+            }
+        });
+    }
+    return new LocalSqliteRetriever({ engine, embedder });
+}
+/**
+ * dev rag 装配：EAP_EMBED_API_KEY 显式配置才启用，否则 undefined（不注入）。
+ * llmProvider 复用 dev 装配已构造的实例（与 llm 节点同一体系）。
+ * EAP_RAG_TRACE=1 时接 console 观测 rag.* 事件流（轮次决策/各源检索/降噪/收束），
+ * 供多源融合行为观察；缺省静默。
+ */
+export function createDevRagNodeDeps(llmProvider, loadFn = loadLocalRetriever) {
+    if (!process.env.EAP_EMBED_API_KEY)
+        return undefined;
+    const fmt = (v, n = 40) => String(v ?? '').replace(/\s+/g, ' ').slice(0, n);
+    const emitEvent = process.env.EAP_RAG_TRACE
+        ? (type, p) => {
+            if (type === 'rag.round') {
+                const calls = (p['toolCalls'] ?? [])
+                    .map((t) => `${t.name}(${JSON.stringify(t.arguments)})`).join('  ');
+                trace(`[rag] 第${p['round']}轮: ${calls}`);
+            }
+            else if (type === 'rag.search') {
+                const head = p['kind'] === 'kb' ? `kb:${p['toolName']}` : `local:"${fmt(p['query'], 20)}"`;
+                trace(`[rag]   search ${head} topK=${p['topK']} → hits=${p['hits']} ${p['durationMs']}ms${p['success'] ? '' : ` ✗${p['error']}`}${p['scope'] ? ` scope=${p['scope']}` : ''}`);
+            }
+            else if (type === 'rag.denoise') {
+                trace(`[rag]   降噪 候选${p['candidates']} → 保留${p['kept']}`);
+                for (const f of p['filtered'] ?? [])
+                    trace(`[rag]     滤 ${fmt(f.rawId, 30)}（${fmt(f.reason, 30)}）`);
+            }
+            else if (type === 'rag.rewrite') {
+                trace(`[rag]   空结果重写 "${fmt(p['from'], 20)}" → "${fmt(p['to'], 20)}"`);
+            }
+            else if (type === 'rag.finish') {
+                trace(`[rag] 收束: ${p['rounds']}轮 最终${p['docs']}条${p['empty'] ? '（空）' : ''}`);
+            }
+        }
+        : undefined;
+    // 预热：自动向量化开启时立即后台装配一次——调度器/授权热更新/入库日志不等到首次
+    // local_search 才启动（演示"先授权后提问"场景需要授权即生效）。失败静默，检索时重试。
+    if (process.env.EAP_RAG_AUTO_INGEST) {
+        void Promise.resolve(loadFn()).catch(() => undefined);
+    }
+    return {
+        llmProvider,
+        retrievers: [new LazyLocalRetriever(loadFn)],
+        emitEvent,
+    };
+}

package/dist/runtime/dev-runtime.d.ts

@@ -28,6 +28,19 @@ import { type AgentRuntime } from './agent-runtime.js';
 import type { RuntimeStorageProfile } from './storage-profile.js';
 import type { HitlResponse, ResumeHitlResult, SSEEvent } from './types.js';
 import type { ILlmTurnLog } from '../debug/llm-turn-log.js';
+import type { ExecutionInterceptors } from '../execution/interceptors.js';
+import { LongTermMemoryService } from '../memory/long-term-memory.service.js';
+export interface CreateDevRuntimeOptions {
+    interceptors?: ExecutionInterceptors;
+    compression?: {
+        enabled?: boolean;
+        persistCompressed?: boolean;
+    };
+    memory?: {
+        enabled?: boolean;
+        service?: LongTermMemoryService;
+    };
+}
 /** createDevRuntime 返回值（CLI 嵌入用，可选字段后续扩展） */
 export interface DevRuntime {
     invokeOrchestrator: InvokeOrchestrator;
@@ -63,12 +76,15 @@ export interface DevRuntime {
         llmTurnKind: 'file' | 'postgres';
         foundationConfigured: boolean;
         skillHotReload: boolean;
+        /** rag 节点依赖已注入（EAP_EMBED_API_KEY 显式配置时 true） */
+        ragEnabled: boolean;
     };
 }
 /**
  * 装配本地 dev 模式所需的全部 Runtime 依赖
  *
  * @returns DevRuntime（含 invokeOrchestrator / streamOrchestrator / 诊断摘要）
- * @throws EAP_LLM_MODE=local 但解不出任何密钥时抛错，避免静默 Echo
+ * @throws `EAP_LLM_MODE=local` 且解不出密钥
+ * @throws 已配 `FOUNDATION_SERVICE_URL` 且 `EAP_LLM_CONNECTIONS` 不是合法 JSON 对象
  */
-export declare function createDevRuntime(): DevRuntime;
+export declare function createDevRuntime(options?: CreateDevRuntimeOptions): DevRuntime;

package/dist/runtime/dev-runtime.js

@@ -25,24 +25,29 @@
  */
 import { createDefaultLLMProvider } from '../providers/echo-llm-provider.js';
 import { HttpLLMProvider } from '../providers/http-llm-provider.js';
-import { createLocalLlmProvider, requireLocalLlmConnections } from '../providers/local-llm-provider.js';
+import { createLocalLlmProvider, createOptionalLocalLlmProvider, requireLocalLlmConnections, } from '../providers/local-llm-provider.js';
 import { RoutingLLMProvider } from '../providers/routing-llm-provider.js';
 import { createToolExecutor } from '../tool/create-tool-executor.js';
 import { DevToolExecutor } from '../tool/dev-tool-executor.js';
-import { withHarnessPrimitives } from '../tool/harness-primitives.js';
+import { captureOverlayJailOptions, withHarnessPrimitives } from '../tool/harness-primitives.js';
 import { AllowAllGovernanceClient, HttpGovernanceClient, } from '../governance/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 { createDevRagNodeDeps } from './dev-rag-deps.js';
+import { RagSearchToolExecutor } from '../graph/nodes/rag/index.js';
 import { resolveSkillHotReload, watchPreinstallSkillRoot, watchSkillRoots } from '../registry/skill-tree.js';
 import { RUNTIME_PACKAGE_VERSION } from '../common/runtime-package-version.js';
+import { LongTermMemoryService } from '../memory/long-term-memory.service.js';
+import { isRuntimeMemoryEnabled } from '../session/apply-session-memory.js';
 /**
  * 装配本地 dev 模式所需的全部 Runtime 依赖
  *
  * @returns DevRuntime（含 invokeOrchestrator / streamOrchestrator / 诊断摘要）
- * @throws EAP_LLM_MODE=local 但解不出任何密钥时抛错，避免静默 Echo
+ * @throws `EAP_LLM_MODE=local` 且解不出密钥
+ * @throws 已配 `FOUNDATION_SERVICE_URL` 且 `EAP_LLM_CONNECTIONS` 不是合法 JSON 对象
  */
-export function createDevRuntime() {
+export function createDevRuntime(options) {
     const foundationUrl = process.env.FOUNDATION_SERVICE_URL ?? 'http://localhost:3100';
     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();
@@ -68,7 +73,12 @@ export function createDevRuntime() {
         llmProviderKind = 'openai-http';
     }
     else if (foundationConfigured) {
-        llmProvider = new RoutingLLMProvider({ foundationUrl, turnLog });
+        const fallbackProvider = createOptionalLocalLlmProvider(turnLog);
+        llmProvider = new RoutingLLMProvider({
+            foundationUrl,
+            turnLog,
+            ...(fallbackProvider ? { fallbackProvider } : {}),
+        });
         llmProviderKind = 'routing';
     }
     else {
@@ -76,12 +86,14 @@ export function createDevRuntime() {
         llmProviderKind = 'echo';
     }
     // ── Tool Executor（dev+mcp 直连，缺配置失败 → 通用路由）──
+    // overlay 必须在此处捕获：SDK createAgent 返回后会恢复 process.env。
+    const overlayJail = captureOverlayJailOptions();
     const needsHarnessWrap = toolExecutionMode === 'mcp' && deploymentContext === 'dev';
     const innerExecutor = toolExecutionMode === 'mcp' && deploymentContext === 'dev'
         ? new DevToolExecutor()
-        : createToolExecutor({ foundationUrl, deploymentContext });
+        : createToolExecutor({ foundationUrl, deploymentContext, jail: overlayJail });
     const toolExecutor = needsHarnessWrap
-        ? withHarnessPrimitives(innerExecutor)
+        ? withHarnessPrimitives(innerExecutor, overlayJail)
         : innerExecutor;
     // ── Governance ──
     const governanceClient = process.env.GOVERNANCE_DISABLED === '1' || !foundationConfigured
@@ -92,7 +104,35 @@ export function createDevRuntime() {
         close: () => { },
         heartbeat: () => { },
     });
-    const graphEngine = new LangGraphAdapter(storage.checkpointSaver, llmProvider, toolExecutor, governanceClient, hitlHandler);
+    // rag：EAP_EMBED_API_KEY 显式配置才注入（retriever 惰性初始化，见 dev-rag-deps.ts）
+    const ragNodeDeps = createDevRagNodeDeps(llmProvider);
+    // 工具形态：RagSearchToolExecutor 装饰工具执行器——拦截 rag_search 跑 rag 内核
+    // （多轮检索/融合/降噪，与节点形态同一 runReactLoop），其余工具调用原样透传。
+    // EAP_RAG_SOURCES（JSON 数据源描述符数组，工具形态无 rag 节点时的检索面声明位）：
+    // 会话勾选 ragSources 由此过滤；不配 = 内层工具表不圈定（由请求 loadedTools 决定）
+    const ragSourcesEnv = (() => {
+        const raw = process.env.EAP_RAG_SOURCES;
+        if (!raw)
+            return undefined;
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? { sources: parsed } : undefined;
+        }
+        catch {
+            console.warn('[rag] EAP_RAG_SOURCES 不是合法 JSON 数组，忽略');
+            return undefined;
+        }
+    })();
+    const ragToolExecutor = ragNodeDeps
+        ? new RagSearchToolExecutor(toolExecutor, ragNodeDeps, {
+            config: {
+                model: process.env.EAP_DEFAULT_MODEL ?? 'DeepSeek-V4-Flash',
+                ...(ragSourcesEnv ? { retrievalSources: ragSourcesEnv } : {}),
+            },
+        })
+        : toolExecutor;
+    const graphEngine = new LangGraphAdapter(storage.checkpointSaver, llmProvider, ragToolExecutor, governanceClient, hitlHandler, ragNodeDeps, options?.interceptors);
+    graphEngine.bindOverlayExtraRoots(overlayJail.extraRoots);
     // ── Session / Messages ──
     const sessionService = new SessionService(storage.sessionRepository);
     const messageService = new MessageService(storage.messageRepository);
@@ -137,6 +177,19 @@ export function createDevRuntime() {
         })()
         : () => { };
     // ── Orchestrators ──
+    const sessionCompression = {
+        provider: llmProvider,
+        turnLog,
+        enabled: options?.compression?.enabled,
+        persistCompressed: options?.compression?.persistCompressed,
+    };
+    const sessionMemory = {
+        enabled: options?.memory?.enabled,
+        service: options?.memory?.service ??
+            (isRuntimeMemoryEnabled(options?.memory?.enabled)
+                ? new LongTermMemoryService()
+                : undefined),
+    };
     const invokeOrchestrator = new InvokeOrchestrator({
         sessionContextService,
         taskService,
@@ -147,6 +200,8 @@ export function createDevRuntime() {
         messageService,
         graphLoader,
         checkpointSaver: storage.checkpointSaver,
+        sessionCompression,
+        sessionMemory,
     });
     const streamOrchestrator = new StreamOrchestrator({
         sessionContextService,
@@ -158,6 +213,8 @@ export function createDevRuntime() {
         messageService,
         graphLoader,
         checkpointSaver: storage.checkpointSaver,
+        sessionCompression,
+        sessionMemory,
     });
     const agentRuntime = createAgentRuntime({
         invokeOrchestrator,
@@ -170,6 +227,8 @@ export function createDevRuntime() {
         messageService,
         sessionService,
         turnLog,
+        sessionCompression,
+        sessionMemory,
     });
     return {
         invokeOrchestrator,
@@ -199,6 +258,7 @@ export function createDevRuntime() {
             llmTurnKind: storage.diagnostics.llmTurnKind,
             foundationConfigured,
             skillHotReload,
+            ragEnabled: ragNodeDeps !== undefined,
         },
     };
 }

package/dist/runtime/index.d.ts

@@ -1,4 +1,4 @@
 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 { createDevRuntime, type DevRuntime, type CreateDevRuntimeOptions, } from './dev-runtime.js';
 export { assembleRuntimeStorage, resolveRuntimeStorageProfile, resolveDevStorageDirs, type RuntimeStorageProfile, type AssembleRuntimeStorageOptions, type AssembledRuntimeStorage, } from './storage-profile.js';

package/dist/runtime/types.d.ts

@@ -6,7 +6,7 @@
  *
  * @see 04-runtime-core/design.md §1.5
  */
-import type { ExecutionContext, InvokeConfig, ResumeHitlResult } from '@gt-fe/eap-contracts';
+import type { ExecutionContext, InvokeConfig, ResumeHitlRequest, ResumeHitlResult } from '@gt-fe/eap-contracts';
 import type { InvokeResponseData } from '../api/routes/agent.routes.js';
 import type { GraphMessage } from '../graph/contracts/executable-graph.js';
 import type { SSEEvent } from '../sse/contracts/sse-emitter.contract.js';
@@ -28,21 +28,22 @@ export interface ExecuteParams {
      */
     traceId?: string;
     config?: InvokeConfig;
+    /** 请求级检索范围（前端圈定已向量化文件/目录；rag 节点本地检索源生效） */
+    ragScope?: {
+        fileIds?: string[];
+        dirPaths?: string[];
+    };
+    /** 会话级数据源勾选（数据源 id 列表；缺省 = 预定义目录全部启用） */
+    ragSources?: string[];
 }
 /** 同步执行结果 */
 export type ExecuteResult = InvokeResponseData;
 /** HITL 恢复结果（与 @gt-fe/eap-contracts ResumeHitlResult 对齐） */
 export type { ResumeHitlResult };
-/** HITL 用户响应 */
-export interface HitlResponse {
+/** HITL 用户响应（与 @gt-fe/eap-contracts ResumeHitlRequest 对齐；userId 必填） */
+export interface HitlResponse extends ResumeHitlRequest {
     choice: string;
     userId: string;
-    executionContext?: ExecutionContext;
-    /**
-     * Checkpoint thread_id 提示（冷恢复）。
-     * Hosting 可从 tasks.output.hitlThreadId 注入；优先于 sessionId。
-     */
-    threadId?: string;
 }
 /** Fork 入参：上层先发 taskId / traceId，Runtime 不再 createFlow */
 export interface ForkParams {

package/dist/session/apply-session-compression.d.ts

@@ -0,0 +1,85 @@
+/**
+ * execute/stream 装载历史后的压缩入口。默认关。
+ *
+ * C-1a 开关：options.enabled 或 EAP_RUNTIME_COMPRESSION=1
+ * C-1b 有窗口：用上一轮 llm_turns 的 used/window，不用字符估窗
+ * C-1c 无窗口：只按轮次上限，不按窗压
+ * C-1d 摘要只走 ILLMProvider；失败则不压缩
+ * C-1e 默认只改本轮内存历史；persistCompressed 时必须能写 compression record
+ * C-1f 流式路径在摘要前产出 session.compression.started，结束后产出 completed。
+ *      不新开「占用 ≥ 80% 再 compact」链；触发仍是 C-1b/c。
+ */
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+import type { ILLMProvider } from '../graph/nodes/llm-node.js';
+import type { ILlmTurnLog } from '../debug/llm-turn-log.js';
+import { type CompressionRecord } from '../memory/message-compression.service.js';
+import type { ICompressionRepository } from '../memory/compression/compression.repository.js';
+import type { SessionCompressionCompletedPayload, SessionCompressionReason, SessionCompressionStartedPayload } from '../sse/events/session-events.js';
+export interface SessionCompressionOptions {
+    enabled?: boolean;
+    persistCompressed?: boolean;
+    provider?: ILLMProvider;
+    turnLog?: ILlmTurnLog;
+    compressionRepository?: ICompressionRepository;
+    maxRounds?: number;
+    preserveRecentRounds?: number;
+    /** 摘要模型；与图节点同一套：Agent `models.default`。不要传字符串 `default`。 */
+    summaryModel?: string;
+}
+export interface RunSessionCompressionParams {
+    history: GraphMessage[];
+    sessionId: string;
+    userId?: string;
+    taskId?: string;
+    options?: SessionCompressionOptions;
+    env?: NodeJS.ProcessEnv;
+}
+export interface RunSessionCompressionResult {
+    messages: GraphMessage[];
+    compressed: boolean;
+    record?: CompressionRecord;
+    completed?: SessionCompressionCompletedPayload;
+}
+export interface SessionCompressionDecision {
+    needed: boolean;
+    originalMessageCount: number;
+    reason?: SessionCompressionReason;
+    used?: number;
+    window?: number;
+    percent?: number;
+    threshold?: number;
+    started?: SessionCompressionStartedPayload;
+}
+export type SessionCompressionStep = {
+    kind: 'started';
+    payload: SessionCompressionStartedPayload;
+} | {
+    kind: 'completed';
+    payload: SessionCompressionCompletedPayload;
+} | {
+    kind: 'history';
+    messages: GraphMessage[];
+};
+export declare function isRuntimeCompressionEnabled(explicit?: boolean, env?: NodeJS.ProcessEnv): boolean;
+export declare function isRuntimeCompressionPersist(explicit?: boolean, env?: NodeJS.ProcessEnv): boolean;
+export declare function formatCompressionStartedMessage(input: {
+    percent?: number;
+    reason: SessionCompressionReason;
+    threshold?: number;
+}): string;
+export declare function formatCompressionCompletedMessage(input: {
+    success: boolean;
+    originalMessageCount: number;
+    compressedMessageCount: number;
+    error?: string;
+}): string;
+export declare function applySessionCompression(params: RunSessionCompressionParams): Promise<GraphMessage[]>;
+/** 未显式 summaryModel 时写入 Agent `models.default`。压缩未开则不解析。 */
+export declare function withCompressionSummaryModel(options: SessionCompressionOptions | undefined, resolveDefaultModel: () => Promise<string | undefined>, env?: NodeJS.ProcessEnv): Promise<SessionCompressionOptions | undefined>;
+/**
+ * 流式入口用：先产出 started，再跑摘要，再产出 completed，最后给出本轮历史。
+ * SDK `stream` 可在 started 之后才继续 next()，HTTP SSE 可立刻 emit。
+ */
+export declare function iterSessionCompression(params: RunSessionCompressionParams): AsyncGenerator<SessionCompressionStep>;
+export declare function runSessionCompression(params: RunSessionCompressionParams): Promise<RunSessionCompressionResult>;
+export declare function decideSessionCompression(params: RunSessionCompressionParams): Promise<SessionCompressionDecision>;