@gt-fe/eap-runtime 0.0.20 → 0.0.21

package/dist/runtime/dev-runtime.js

@@ -29,20 +29,24 @@ import { createLocalLlmProvider, requireLocalLlmConnections } from '../providers
 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
  */
-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();
@@ -76,12 +80,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 +98,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 +171,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 +194,8 @@ export function createDevRuntime() {
         messageService,
         graphLoader,
         checkpointSaver: storage.checkpointSaver,
+        sessionCompression,
+        sessionMemory,
     });
     const streamOrchestrator = new StreamOrchestrator({
         sessionContextService,
@@ -158,6 +207,8 @@ export function createDevRuntime() {
         messageService,
         graphLoader,
         checkpointSaver: storage.checkpointSaver,
+        sessionCompression,
+        sessionMemory,
     });
     const agentRuntime = createAgentRuntime({
         invokeOrchestrator,
@@ -170,6 +221,8 @@ export function createDevRuntime() {
         messageService,
         sessionService,
         turnLog,
+        sessionCompression,
+        sessionMemory,
     });
     return {
         invokeOrchestrator,
@@ -199,6 +252,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,81 @@
+/**
+ * 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;
+}
+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[]>;
+/**
+ * 流式入口用：先产出 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>;

package/dist/session/apply-session-compression.js

@@ -0,0 +1,262 @@
+/**
+ * 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 { EchoLLMProvider } from '../providers/echo-llm-provider.js';
+import { COMPRESSION_WINDOW_FACTOR, countRounds, DEFAULT_COMPRESSION_CONFIG, } from '../memory/message-compression.service.js';
+import { SlidingWindowCompression } from '../memory/compression/sliding-window.compression.js';
+import { emitRuntimeLog } from '../common/logger.js';
+export function isRuntimeCompressionEnabled(explicit, env = process.env) {
+    if (explicit === true)
+        return true;
+    if (explicit === false)
+        return false;
+    const raw = env.EAP_RUNTIME_COMPRESSION ?? env.EAP_COMPRESSION_ENABLED;
+    return raw === '1' || raw === 'true';
+}
+export function isRuntimeCompressionPersist(explicit, env = process.env) {
+    if (explicit === true)
+        return true;
+    if (explicit === false)
+        return false;
+    return env.EAP_RUNTIME_COMPRESSION_PERSIST === '1' || env.EAP_RUNTIME_COMPRESSION_PERSIST === 'true';
+}
+export function formatCompressionStartedMessage(input) {
+    if (typeof input.percent === 'number' && Number.isFinite(input.percent)) {
+        return `Context ${input.percent}% full. Compacting...`;
+    }
+    if (typeof input.threshold === 'number' && Number.isFinite(input.threshold)) {
+        return `Conversation exceeded ${input.threshold} rounds. Compacting...`;
+    }
+    return 'Compacting conversation history...';
+}
+export function formatCompressionCompletedMessage(input) {
+    if (!input.success) {
+        return input.error
+            ? 'Compression failed; using original history.'
+            : 'Compression skipped; using original history.';
+    }
+    return `Compressed ${input.originalMessageCount} → ${input.compressedMessageCount} messages.`;
+}
+export async function applySessionCompression(params) {
+    const result = await runSessionCompression(params);
+    return result.messages;
+}
+/**
+ * 流式入口用：先产出 started，再跑摘要，再产出 completed，最后给出本轮历史。
+ * SDK `stream` 可在 started 之后才继续 next()，HTTP SSE 可立刻 emit。
+ */
+export async function* iterSessionCompression(params) {
+    const history = params.history ?? [];
+    const decision = await decideSessionCompression(params);
+    if (!decision.needed || !decision.started) {
+        yield { kind: 'history', messages: history };
+        return;
+    }
+    yield { kind: 'started', payload: decision.started };
+    const result = await runDecidedSessionCompression(params, decision);
+    if (result.completed) {
+        yield { kind: 'completed', payload: result.completed };
+    }
+    yield { kind: 'history', messages: result.messages };
+}
+export async function runSessionCompression(params) {
+    const decision = await decideSessionCompression(params);
+    if (!decision.needed) {
+        return { messages: params.history ?? [], compressed: false };
+    }
+    return runDecidedSessionCompression(params, decision);
+}
+export async function decideSessionCompression(params) {
+    const history = params.history ?? [];
+    const originalMessageCount = history.length;
+    const options = params.options ?? {};
+    const env = params.env ?? process.env;
+    const enabled = isRuntimeCompressionEnabled(options.enabled, env);
+    if (!enabled || history.length === 0) {
+        return { needed: false, originalMessageCount };
+    }
+    const provider = options.provider;
+    if (!provider || provider instanceof EchoLLMProvider) {
+        return { needed: false, originalMessageCount };
+    }
+    const maxRounds = options.maxRounds ?? DEFAULT_COMPRESSION_CONFIG.maxRounds;
+    const last = await lastTurnUsage(options.turnLog, params.sessionId);
+    const needed = last?.window
+        ? last.used >= Math.floor(last.window * COMPRESSION_WINDOW_FACTOR)
+        : countRounds(history) > maxRounds;
+    if (!needed) {
+        return { needed: false, originalMessageCount };
+    }
+    const reason = last?.window ? 'window' : 'max_rounds';
+    const percent = last?.window && last.window > 0 ? Math.round((last.used / last.window) * 100) : undefined;
+    const threshold = last?.window
+        ? Math.floor(last.window * COMPRESSION_WINDOW_FACTOR)
+        : maxRounds;
+    const started = {
+        sessionId: params.sessionId,
+        ...(params.taskId ? { taskId: params.taskId } : {}),
+        reason,
+        originalMessageCount,
+        ...(last ? { used: last.used } : {}),
+        ...(last?.window ? { window: last.window } : {}),
+        ...(percent !== undefined ? { percent } : {}),
+        threshold,
+        displayMessage: formatCompressionStartedMessage({ percent, reason, threshold }),
+    };
+    return {
+        needed: true,
+        originalMessageCount,
+        reason,
+        used: last?.used,
+        window: last?.window,
+        percent,
+        threshold,
+        started,
+    };
+}
+async function runDecidedSessionCompression(params, decision) {
+    const history = params.history ?? [];
+    const options = params.options ?? {};
+    const env = params.env ?? process.env;
+    const provider = options.provider;
+    if (!provider || provider instanceof EchoLLMProvider || !decision.needed) {
+        return {
+            messages: history,
+            compressed: false,
+            completed: completedPayload(params, decision, {
+                success: false,
+                compressedMessageCount: history.length,
+                persisted: false,
+            }),
+        };
+    }
+    const persist = isRuntimeCompressionPersist(options.persistCompressed, env);
+    if (persist && !options.compressionRepository) {
+        emitRuntimeLog('warn', 'runtime.compression', 'persist requested without repository; memory only', {
+            event: 'runtime.compression.persist_skipped',
+            sessionId: params.sessionId,
+        });
+    }
+    const maxRounds = options.maxRounds ?? DEFAULT_COMPRESSION_CONFIG.maxRounds;
+    try {
+        const compression = new SlidingWindowCompression({
+            maxRounds,
+            preserveRecentRounds: options.preserveRecentRounds ?? DEFAULT_COMPRESSION_CONFIG.preserveRecentRounds,
+            ...(decision.window ? { maxContextTokens: decision.window } : {}),
+        }, async (msgs) => summarizeWithProvider(provider, msgs));
+        const compressed = await compression.compress(history);
+        if (compressed === history) {
+            return {
+                messages: history,
+                compressed: false,
+                completed: completedPayload(params, decision, {
+                    success: false,
+                    compressedMessageCount: history.length,
+                    persisted: false,
+                }),
+            };
+        }
+        const record = {
+            sessionId: params.sessionId,
+            taskId: params.taskId ?? null,
+            originalMessageCount: history.length,
+            compressedMessageCount: compressed.length,
+            originalTokens: decision.used ?? 0,
+            compressedTokens: 0,
+            strategy: 'sliding-window',
+            summaryContent: compressed[0]?.content ?? '',
+            createdBy: params.userId ?? 'system',
+            createdAt: new Date().toISOString(),
+        };
+        let persisted = false;
+        if (persist && options.compressionRepository) {
+            await options.compressionRepository.save(record);
+            persisted = true;
+        }
+        return {
+            messages: compressed,
+            compressed: true,
+            record,
+            completed: completedPayload(params, decision, {
+                success: true,
+                compressedMessageCount: compressed.length,
+                persisted,
+            }),
+        };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        emitRuntimeLog('warn', 'runtime.compression', 'compress failed; using original history', {
+            event: 'runtime.compression.failed',
+            sessionId: params.sessionId,
+            error,
+        });
+        return {
+            messages: history,
+            compressed: false,
+            completed: completedPayload(params, decision, {
+                success: false,
+                compressedMessageCount: history.length,
+                persisted: false,
+                error,
+            }),
+        };
+    }
+}
+function completedPayload(params, decision, outcome) {
+    const reason = decision.reason ?? 'max_rounds';
+    return {
+        sessionId: params.sessionId,
+        ...(params.taskId ? { taskId: params.taskId } : {}),
+        reason,
+        success: outcome.success,
+        originalMessageCount: decision.originalMessageCount,
+        compressedMessageCount: outcome.compressedMessageCount,
+        ...(decision.used !== undefined ? { used: decision.used } : {}),
+        ...(decision.window !== undefined ? { window: decision.window } : {}),
+        ...(decision.percent !== undefined ? { percent: decision.percent } : {}),
+        persisted: outcome.persisted,
+        ...(outcome.error ? { error: outcome.error } : {}),
+        displayMessage: formatCompressionCompletedMessage({
+            success: outcome.success,
+            originalMessageCount: decision.originalMessageCount,
+            compressedMessageCount: outcome.compressedMessageCount,
+            error: outcome.error,
+        }),
+    };
+}
+async function lastTurnUsage(turnLog, sessionId) {
+    if (!turnLog || !sessionId)
+        return undefined;
+    const index = await turnLog.list(sessionId);
+    const last = index[index.length - 1];
+    if (!last || typeof last.used !== 'number')
+        return undefined;
+    return { used: last.used, window: last.window };
+}
+async function summarizeWithProvider(provider, messages) {
+    const body = messages
+        .map((m) => `${m.role}: ${m.content}`)
+        .join('\n')
+        .slice(0, 12000);
+    const response = await provider.invoke([
+        {
+            role: 'system',
+            content: '将对话历史压成短摘要，保留用户需求、结论和未完成事项。',
+        },
+        { role: 'user', content: body },
+    ], { model: 'default', temperature: 0.2, maxTokens: 1024 });
+    const text = response.content?.trim();
+    if (!text) {
+        throw new Error('empty compression summary');
+    }
+    return text;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * execute/stream 装载历史后注入长期记忆。默认关。
+ * 只用关键词匹配；未注入真实 embedding 不做向量检索。
+ */
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+import { LongTermMemoryService, type MemoryRecord } from '../memory/long-term-memory.service.js';
+export interface SessionMemoryOptions {
+    enabled?: boolean;
+    service?: LongTermMemoryService;
+    limit?: number;
+}
+export declare function isRuntimeMemoryEnabled(explicit?: boolean, env?: NodeJS.ProcessEnv): boolean;
+export declare function applySessionMemory(params: {
+    history: GraphMessage[];
+    userId?: string;
+    agentCode?: string;
+    query?: string;
+    options?: SessionMemoryOptions;
+    env?: NodeJS.ProcessEnv;
+}): Promise<GraphMessage[]>;
+export declare function injectMemoryHits(history: GraphMessage[], memories: MemoryRecord[]): GraphMessage[];

package/dist/session/apply-session-memory.js

@@ -0,0 +1,48 @@
+/**
+ * execute/stream 装载历史后注入长期记忆。默认关。
+ * 只用关键词匹配；未注入真实 embedding 不做向量检索。
+ */
+import { SemanticRetrievalService } from '../memory/semantic-retrieval.service.js';
+export function isRuntimeMemoryEnabled(explicit, env = process.env) {
+    if (explicit === true)
+        return true;
+    if (explicit === false)
+        return false;
+    const raw = env.EAP_RUNTIME_MEMORY;
+    return raw === '1' || raw === 'true';
+}
+export async function applySessionMemory(params) {
+    const history = params.history ?? [];
+    const options = params.options ?? {};
+    const env = params.env ?? process.env;
+    if (!isRuntimeMemoryEnabled(options.enabled, env))
+        return history;
+    const service = options.service;
+    if (!service || !params.userId || !params.agentCode)
+        return history;
+    const query = params.query?.trim() ||
+        [...history].reverse().find((m) => m.role === 'user')?.content?.trim() ||
+        '';
+    if (!query)
+        return history;
+    const stored = await service.retrieve(params.userId, params.agentCode, 50);
+    if (stored.length === 0)
+        return history;
+    const retrieval = new SemanticRetrievalService({
+        strategy: 'keyword',
+        limit: options.limit ?? 10,
+    });
+    const hits = await retrieval.retrieve(query, stored);
+    if (hits.length === 0)
+        return history;
+    return injectMemoryHits(history, hits.map((h) => h.record));
+}
+export function injectMemoryHits(history, memories) {
+    if (memories.length === 0)
+        return history;
+    const memoryContent = memories.map((m) => `[${m.type}] ${m.content}`).join('\n');
+    return [
+        { role: 'system', content: `[Long-term Memory]\n${memoryContent}` },
+        ...history,
+    ];
+}

package/dist/session/index.d.ts

@@ -10,4 +10,6 @@ export type { FileMessageRepositoryOptions } from './file-message.repository.js'
 export { SessionContextService } from './session-context.service.js';
 export type { ResolveSessionParams, SessionContext, } from './session-context.service.js';
 export { CompressionMiddleware, createCompressionMiddleware } from './compression-middleware.js';
+export { applySessionCompression, runSessionCompression, decideSessionCompression, iterSessionCompression, formatCompressionStartedMessage, formatCompressionCompletedMessage, isRuntimeCompressionEnabled, isRuntimeCompressionPersist, type SessionCompressionOptions, type RunSessionCompressionParams, type RunSessionCompressionResult, type SessionCompressionDecision, type SessionCompressionStep, } from './apply-session-compression.js';
 export type { CompressionMiddlewareConfig } from './compression-middleware.js';
+export { applySessionMemory, isRuntimeMemoryEnabled, type SessionMemoryOptions, } from './apply-session-memory.js';

package/dist/session/index.js

@@ -10,3 +10,5 @@ export { FileMessageRepository } from './file-message.repository.js';
 export { SessionContextService } from './session-context.service.js';
 // 压缩中间件
 export { CompressionMiddleware, createCompressionMiddleware } from './compression-middleware.js';
+export { applySessionCompression, runSessionCompression, decideSessionCompression, iterSessionCompression, formatCompressionStartedMessage, formatCompressionCompletedMessage, isRuntimeCompressionEnabled, isRuntimeCompressionPersist, } from './apply-session-compression.js';
+export { applySessionMemory, isRuntimeMemoryEnabled, } from './apply-session-memory.js';