@gt-fe/eap-runtime 0.0.8 → 0.0.10

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,6 +23,7 @@ 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) |
@@ -82,7 +85,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 +178,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-存储装配策略)。
 
 ---
 

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,8 +174,7 @@ 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)
                 : [];

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

@@ -28,7 +28,8 @@ import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.
 import { ErrorCodes } from '@gt-fe/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,8 +196,7 @@ 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)
             : [];

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/contracts/trace-collector.d.ts

@@ -82,7 +82,7 @@ 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';
     /** Agent 对外主键 */
@@ -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[]>;
+}

package/dist/debug/llm-turn-log.js

@@ -0,0 +1,130 @@
+/**
+ * 本地 LLM 回合落盘：每次模型调用写一份 JSON（入参、响应、URL、脱敏密钥、system 段）。
+ * 默认 `.eap/llm-turns/{sessionId}/`。EAP_LLM_TURN_LOG=0 关闭。
+ */
+import { mkdir, readdir, readFile, appendFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export function finalizeLlmTurn(turn) {
+    const ts = turn.ts ?? new Date().toISOString();
+    const id = turn.id ?? `${ts.replace(/[:.]/g, '-')}-${turn.nodeId ?? 'llm'}`;
+    return { ...turn, id, ts };
+}
+export function toLlmTurnIndexEntry(record, file) {
+    return {
+        id: record.id,
+        ts: record.ts,
+        sessionId: record.sessionId,
+        taskId: record.taskId,
+        nodeId: record.nodeId,
+        model: record.model,
+        url: record.url,
+        file: file ?? `${sanitize(record.id)}.json`,
+        inputTokens: record.response.inputTokens,
+        outputTokens: record.response.outputTokens,
+    };
+}
+export function maskApiKey(key) {
+    if (!key)
+        return '';
+    if (key.length <= 6)
+        return '***';
+    // 例：sk-proj-… → sk-proj***；sk-abc123xyz → sk-abc1***
+    return `${key.slice(0, 7)}***`;
+}
+export function resolveLlmTurnDir(env = process.env, cwd = process.cwd()) {
+    return env.EAP_LLM_TURN_DIR?.trim() || path.join(cwd, '.eap', 'llm-turns');
+}
+export function createFileLlmTurnLogFromEnv(env = process.env) {
+    if (env.EAP_LLM_TURN_LOG === '0')
+        return undefined;
+    return new FileLlmTurnLog(resolveLlmTurnDir(env));
+}
+export class InMemoryLlmTurnLog {
+    kind = 'memory';
+    baseDir = 'memory://llm-turns';
+    bySession = new Map();
+    async record(turn) {
+        const record = finalizeLlmTurn(turn);
+        const sessionId = record.sessionId ?? 'no-session';
+        let bucket = this.bySession.get(sessionId);
+        if (!bucket) {
+            bucket = { records: new Map(), index: [] };
+            this.bySession.set(sessionId, bucket);
+        }
+        bucket.records.set(record.id, record);
+        bucket.index.push(toLlmTurnIndexEntry(record));
+        return record;
+    }
+    async list(sessionId) {
+        return [...(this.bySession.get(sessionId)?.index ?? [])];
+    }
+    async read(sessionId, turnId) {
+        return this.bySession.get(sessionId)?.records.get(turnId) ?? null;
+    }
+    async listSessions() {
+        return [...this.bySession.keys()].sort();
+    }
+}
+export class FileLlmTurnLog {
+    baseDir;
+    kind = 'file';
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    async record(turn) {
+        const record = finalizeLlmTurn(turn);
+        const sessionId = sanitize(record.sessionId ?? 'no-session');
+        const dir = path.join(this.baseDir, sessionId);
+        await mkdir(dir, { recursive: true });
+        const file = `${sanitize(record.id)}.json`;
+        const filePath = path.join(dir, file);
+        await writeFile(filePath, JSON.stringify(record, null, 2), 'utf8');
+        await appendFile(path.join(dir, 'index.jsonl'), `${JSON.stringify(toLlmTurnIndexEntry(record, file))}\n`, 'utf8');
+        return record;
+    }
+    async list(sessionId) {
+        const file = path.join(this.baseDir, sanitize(sessionId), 'index.jsonl');
+        try {
+            const raw = await readFile(file, 'utf8');
+            return raw
+                .split('\n')
+                .filter((line) => line.trim())
+                .map((line) => JSON.parse(line));
+        }
+        catch {
+            return [];
+        }
+    }
+    async read(sessionId, turnId) {
+        const dir = path.join(this.baseDir, sanitize(sessionId));
+        const direct = path.join(dir, `${sanitize(turnId)}.json`);
+        try {
+            return JSON.parse(await readFile(direct, 'utf8'));
+        }
+        catch {
+            // fall through
+        }
+        const entries = await this.list(sessionId);
+        const hit = entries.find((e) => e.id === turnId || e.file === turnId);
+        if (!hit)
+            return null;
+        try {
+            return JSON.parse(await readFile(path.join(dir, hit.file), 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    async listSessions() {
+        try {
+            const names = await readdir(this.baseDir);
+            return names.sort();
+        }
+        catch {
+            return [];
+        }
+    }
+}
+function sanitize(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, '_').slice(0, 180);
+}

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

@@ -0,0 +1,22 @@
+/**
+ * LLM 回合 Postgres 存储。与 FileLlmTurnLog / InMemoryLlmTurnLog 共用 ILlmTurnLog。
+ *
+ * 表结构见 runtime/docs/ddl.md（`llm_turns`）。启动时仍可 CREATE IF NOT EXISTS。
+ */
+import type { IPgPool } from '../session/pg-message.repository.js';
+import { type ILlmTurnLog, type LlmTurnIndexEntry, type LlmTurnRecord } from './llm-turn-log.js';
+export declare class PostgresLlmTurnLog implements ILlmTurnLog {
+    private readonly pool;
+    readonly kind: "postgres";
+    readonly baseDir = "postgres://llm_turns";
+    private ready;
+    constructor(pool: IPgPool);
+    private ensureTable;
+    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[]>;
+}

package/dist/debug/pg-llm-turn-log.js

@@ -0,0 +1,57 @@
+/**
+ * LLM 回合 Postgres 存储。与 FileLlmTurnLog / InMemoryLlmTurnLog 共用 ILlmTurnLog。
+ *
+ * 表结构见 runtime/docs/ddl.md（`llm_turns`）。启动时仍可 CREATE IF NOT EXISTS。
+ */
+import { finalizeLlmTurn, toLlmTurnIndexEntry, } from './llm-turn-log.js';
+const CREATE_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS llm_turns (
+  id          VARCHAR(180) PRIMARY KEY,
+  session_id  VARCHAR(64)  NOT NULL,
+  ts          TIMESTAMPTZ  NOT NULL,
+  payload     JSONB        NOT NULL
+)`;
+const CREATE_INDEX_SQL = 'CREATE INDEX IF NOT EXISTS idx_llm_turns_session_ts ON llm_turns (session_id, ts)';
+export class PostgresLlmTurnLog {
+    pool;
+    kind = 'postgres';
+    baseDir = 'postgres://llm_turns';
+    ready;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    ensureTable() {
+        this.ready ??= this.pool
+            .query(CREATE_TABLE_SQL)
+            .then(() => this.pool.query(CREATE_INDEX_SQL))
+            .then(() => undefined);
+        return this.ready;
+    }
+    async record(turn) {
+        await this.ensureTable();
+        const record = finalizeLlmTurn(turn);
+        await this.pool.query(`INSERT INTO llm_turns (id, session_id, ts, payload)
+       VALUES ($1, $2, $3, $4)
+       ON CONFLICT (id) DO UPDATE SET payload = EXCLUDED.payload, ts = EXCLUDED.ts, session_id = EXCLUDED.session_id`, [record.id, record.sessionId ?? 'no-session', record.ts, JSON.stringify(record)]);
+        return record;
+    }
+    async list(sessionId) {
+        await this.ensureTable();
+        const { rows } = await this.pool.query(`SELECT payload FROM llm_turns WHERE session_id = $1 ORDER BY ts ASC`, [sessionId]);
+        return rows.map((row) => toLlmTurnIndexEntry(parsePayload(row.payload)));
+    }
+    async read(sessionId, turnId) {
+        await this.ensureTable();
+        const { rows } = await this.pool.query(`SELECT payload FROM llm_turns WHERE session_id = $1 AND id = $2`, [sessionId, turnId]);
+        const row = rows[0];
+        return row ? parsePayload(row.payload) : null;
+    }
+    async listSessions() {
+        await this.ensureTable();
+        const { rows } = await this.pool.query(`SELECT DISTINCT session_id FROM llm_turns ORDER BY session_id`);
+        return rows.map((row) => row.session_id);
+    }
+}
+function parsePayload(payload) {
+    return typeof payload === 'string' ? JSON.parse(payload) : payload;
+}