@gt-fe/eap-runtime 0.0.8 → 0.0.11

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;
+}

package/dist/governance/governance-client.d.ts

@@ -1,7 +1,7 @@
 /**
  * 治理服务 HTTP 客户端（06-governance validateToken / checkPermission）
  */
-import type { ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult } from '@gt-fe/eap-contracts';
+import type { ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult } from '@eap/contracts';
 export interface HttpGovernanceClientOptions {
     baseUrl: string;
     timeout?: number;

package/dist/governance/governance-client.js

@@ -40,25 +40,29 @@ export class HttpGovernanceClient {
             if (response.status === 503 || response.status >= 500) {
                 return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
             }
+            if (response.status === 403) {
+                return { allowed: false, reason: await readDenyReason(response, 'NO_PERMISSION') };
+            }
             if (!response.ok) {
-                if (response.status === 403) {
-                    try {
-                        const errBody = (await response.json());
-                        const errData = errBody.data ?? errBody;
-                        return { allowed: false, reason: errData.reason ?? 'NO_PERMISSION' };
-                    }
-                    catch {
-                        return { allowed: false, reason: 'NO_PERMISSION' };
-                    }
-                }
-                return { allowed: false, reason: 'NO_PERMISSION' };
+                // 401/404/400 等是 Runtime→Foundation hop 失败，不是 C2「没工具权」
+                return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
+            }
+            let body;
+            try {
+                body = (await response.json());
+            }
+            catch {
+                return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
             }
-            const body = (await response.json());
             const data = body.data ?? body;
-            return {
-                allowed: data.allowed === true,
-                reason: data.allowed ? undefined : (data.reason ?? 'NO_PERMISSION'),
-            };
+            if (data.allowed === true) {
+                return { allowed: true };
+            }
+            const reason = asDenyReason(data.reason);
+            if (data.allowed === false && reason && reason !== 'GOVERNANCE_UNAVAILABLE') {
+                return { allowed: false, reason };
+            }
+            return { allowed: false, reason: 'GOVERNANCE_UNAVAILABLE' };
         }
         catch {
             clearTimeout(timeoutId);
@@ -66,6 +70,26 @@ export class HttpGovernanceClient {
         }
     }
 }
+const DENY_REASONS = new Set([
+    'NO_PERMISSION',
+    'DATA_SCOPE_DENIED',
+    'GOVERNANCE_UNAVAILABLE',
+]);
+function asDenyReason(value) {
+    return typeof value === 'string' && DENY_REASONS.has(value)
+        ? value
+        : undefined;
+}
+async function readDenyReason(response, fallback) {
+    try {
+        const errBody = (await response.json());
+        const errData = errBody.data ?? errBody;
+        return asDenyReason(errData.reason) ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
 /** 本地/测试：跳过远程校验 */
 export class AllowAllGovernanceClient {
     async checkPermission(_ctx, _params) {

package/dist/governance/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * 权限校验 — 对齐 06-governance R16.8
  */
-export type { CallerType, ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult, PermissionAction, PermissionDenyReason, PermissionResourceType, } from '@gt-fe/eap-contracts';
+export type { CallerType, ExecutionContext, GovernancePermissionCheckParams, GovernancePermissionCheckResult, PermissionAction, PermissionDenyReason, PermissionResourceType, } from '@eap/contracts';
 export type { IGovernanceClient } from './governance-client.js';
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, } from './governance-client.js';
-export { assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';
+export { assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';

package/dist/governance/index.js

@@ -2,4 +2,4 @@
  * 权限校验 — 对齐 06-governance R16.8
  */
 export { HttpGovernanceClient, AllowAllGovernanceClient, resolveExecutionContext, } from './governance-client.js';
-export { assertToolPermission, assertSkillPermission, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';
+export { assertToolPermission, assertSkillPermission, permissionMessage, PermissionDeniedError, GovernanceUnavailableError, } from './permission-guard.js';

package/dist/governance/permission-guard.d.ts

@@ -1,7 +1,7 @@
 /**
  * 执行期 Tool 权限守卫
  */
-import type { ExecutionContext, PermissionDenyReason } from '@gt-fe/eap-contracts';
+import type { ExecutionContext, PermissionDenyReason } from '@eap/contracts';
 import type { IGovernanceClient } from './governance-client.js';
 export declare class GovernanceUnavailableError extends Error {
     readonly reason: PermissionDenyReason;
@@ -11,6 +11,7 @@ export declare class PermissionDeniedError extends Error {
     readonly reason: PermissionDenyReason;
     constructor(reason?: PermissionDenyReason, message?: string);
 }
+export declare function permissionMessage(kind: 'tool' | 'skill', reason: PermissionDenyReason): string;
 export declare function assertToolPermission(client: IGovernanceClient | undefined, ctx: ExecutionContext, toolId: string, options?: {
     dataScope?: 'user-bound' | 'department-bound' | 'global';
     resourceOwnerId?: string;

package/dist/governance/permission-guard.js

@@ -3,7 +3,7 @@
  */
 export class GovernanceUnavailableError extends Error {
     reason = 'GOVERNANCE_UNAVAILABLE';
-    constructor(message = 'Governance service unavailable') {
+    constructor(message = '治理服务不可用') {
         super(message);
         this.name = 'GovernanceUnavailableError';
     }
@@ -11,11 +11,18 @@ export class GovernanceUnavailableError extends Error {
 export class PermissionDeniedError extends Error {
     reason;
     constructor(reason = 'NO_PERMISSION', message) {
-        super(message ?? reason);
+        super(message ?? permissionMessage('tool', reason));
         this.name = 'PermissionDeniedError';
         this.reason = reason;
     }
 }
+export function permissionMessage(kind, reason) {
+    if (reason === 'DATA_SCOPE_DENIED')
+        return '数据范围不足';
+    if (reason === 'GOVERNANCE_UNAVAILABLE')
+        return '治理服务不可用';
+    return kind === 'skill' ? '用户无该 Skill 使用权限' : '用户无该 Tool 执行权限';
+}
 export async function assertToolPermission(client, ctx, toolId, options) {
     if (!client) {
         return;
@@ -34,7 +41,8 @@ export async function assertToolPermission(client, ctx, toolId, options) {
         throw new GovernanceUnavailableError();
     }
     if (!result.allowed) {
-        throw new PermissionDeniedError(result.reason ?? 'NO_PERMISSION');
+        const reason = result.reason ?? 'NO_PERMISSION';
+        throw new PermissionDeniedError(reason, permissionMessage('tool', reason));
     }
 }
 /** Skill 激活守卫（04 R15.3） */
@@ -54,6 +62,7 @@ export async function assertSkillPermission(client, ctx, skillId) {
         throw new GovernanceUnavailableError();
     }
     if (!result.allowed) {
-        throw new PermissionDeniedError(result.reason ?? 'NO_PERMISSION');
+        const reason = result.reason ?? 'NO_PERMISSION';
+        throw new PermissionDeniedError(reason, permissionMessage('skill', reason));
     }
 }

package/dist/graph/adapters/langgraph-checkpointer.js

@@ -8,6 +8,7 @@
  * @see tasks.md Task 11.5
  */
 import { BaseCheckpointSaver, } from '@langchain/langgraph';
+import { notifyCheckpointRef, stripCheckpointCollectors, } from '../../checkpoint/checkpoint-ref-notify.js';
 /**
  * LangGraphCheckpointer — 桥接 LangGraph BaseCheckpointSaver → ICheckpointSaver
  *
@@ -42,7 +43,8 @@ export class LangGraphCheckpointer extends BaseCheckpointSaver {
     async put(config, checkpoint, metadata, _newVersions) {
         const threadId = this.extractThreadId(config) ?? `thread-${Date.now()}`;
         const data = this.checkpointToData(threadId, checkpoint, metadata);
-        await this.saver.save(threadId, data);
+        await this.saver.save(threadId, stripCheckpointCollectors(data));
+        await notifyCheckpointRef(data);
         return {
             ...config,
             configurable: {

package/dist/graph/adapters/langgraph.adapter.d.ts

@@ -64,6 +64,7 @@ export declare class LangGraphAdapter implements IStateGraphEngine {
     /**
      * Tool 节点执行旁路：started → tool.called + tool.progress；
      * completed/error → 对应终态 + tool.progress。同一 toolCallId。
+     * 读 SKILL.md / 技能包内文件：成功后再发 skill.loaded / skill.resource_read，同时保留 tool.*。
      */
     private emitToolExecutionEvents;
     /**