@gt-fe/eap-runtime 0.0.21 → 0.0.23

package/dist/graph/adapters/subgraph-compiler.js

@@ -8,7 +8,6 @@
  * @see design.md §1.4 子图嵌套: Skill作为子图嵌入主Graph
  * @see requirements.md Requirement 1 AC2 — 子图嵌套（Skill作为子图）
  */
-import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 import { assertSkillPermission } from '../../governance/permission-guard.js';
 import { LangGraphAdapter } from './langgraph.adapter.js';
 import { assertSkillGraphHasNoSubgraphNodes } from './graph-nesting.js';
@@ -18,7 +17,7 @@ import { filterLoadedToolsForSkill, } from '../../tool/system-prompt-builder.js'
 import { unwrapHitlPaused } from '../hitl/hitl-handler.js';
 import { pickContextFields } from '../../token/context-window.js';
 import { assertSkillIoIfEnabled, coerceSkillInputFromMessages, } from '../../registry/skill-io-guard.js';
-import { isolatedSkillMessages, isolatedSkillOutput, SKILL_ISOLATE_HITL_MESSAGE, } from './skill-isolate.js';
+import { isolatedSkillMessages, isolatedSkillOutput, } from './skill-isolate.js';
 /**
  * SubGraphCompiler — 子图编译器
  *
@@ -150,15 +149,15 @@ export class SubGraphCompiler {
                     : parentMessages;
                 const subGraphState = {
                     messages: subMessagesIn,
-                    // 默认同父 session thread；隔离时不写父 Checkpoint，避免短历史覆盖父对话
+                    // 同父 session；checkpointNs=父节点 id → 子图槽 thread_id#父节点id（HITL 同槽，含 isolate）。
                     replaceCheckpointMessages: !isolateContext,
                     userId,
                     delegationToken,
                     agentCode,
                     taskId: state['taskId'],
                     correlationId: state['correlationId'],
-                    sessionId: isolateContext ? undefined : state['sessionId'],
-                    // ToolNode 用此标志在 interrupt 前拒绝 HITL
+                    sessionId: state['sessionId'],
+                    checkpointNs: options?.parentNodeId,
                     skillIsolateContext: isolateContext || undefined,
                     executionContext: state['executionContext'],
                     loadedTools: scopedTools,
@@ -175,6 +174,8 @@ export class SubGraphCompiler {
                     lastSpanId: skillSpanId ?? state['lastSpanId'],
                     hitlChoice: state['hitlChoice'],
                     hitlRespondedBy: state['hitlRespondedBy'],
+                    toolSpanId: typeof state['toolSpanId'] === 'string' ? state['toolSpanId'] : undefined,
+                    hitlToolCallId: typeof state['hitlToolCallId'] === 'string' ? state['hitlToolCallId'] : undefined,
                 };
                 const result = await adapter.runIsolatedLlmStreamFlags(() => adapter.invoke(subGraph, subGraphState));
                 // 进程内调试记录；生产记录是上面的 skill Span
@@ -229,10 +230,12 @@ export class SubGraphCompiler {
                 const nestedLastSpanId = (typeof result.finalState?.lastSpanId === 'string' && result.finalState.lastSpanId) ||
                     skillSpanId ||
                     undefined;
+                const parentNodeId = options?.parentNodeId
+                    || (dsl.name ? `subgraph:${dsl.name}` : 'subgraph');
                 return {
                     messages: outputMessages,
-                    currentNode: options?.parentNodeId
-                        || (dsl.name ? `subgraph:${dsl.name}` : 'subgraph'),
+                    currentNode: parentNodeId,
+                    historyPath: [parentNodeId],
                     ...(nestedLastSpanId ? { lastSpanId: nestedLastSpanId } : {}),
                     ...(Array.isArray(perNode) && perNode.length > 0
                         ? {
@@ -249,16 +252,10 @@ export class SubGraphCompiler {
             }
             catch (err) {
                 const hitlPaused = unwrapHitlPaused(err);
-                // 未隔离：HITL 暂停原样上抛。隔离：转 GRAPH_EXECUTION_ERROR，走 skill.failed，不当 waiting_hitl。
-                if (hitlPaused && !isolateContext) {
+                if (hitlPaused) {
                     throw err;
                 }
-                const failErr = hitlPaused && isolateContext
-                    ? new AppError(ErrorCodes.GRAPH_EXECUTION_ERROR, SKILL_ISOLATE_HITL_MESSAGE, {
-                        exposeMessage: true,
-                        cause: err,
-                    })
-                    : err;
+                const failErr = err;
                 const failMessage = failErr instanceof Error ? failErr.message : String(failErr);
                 await auditCtx?.finish({
                     status: 'failed',

package/dist/graph/contracts/executable-graph.d.ts

@@ -243,6 +243,12 @@ export interface GraphState {
      * 仅 stream/invoke 入口使用，不入持久化语义。
      */
     replaceCheckpointMessages?: boolean;
+    /**
+     * 子图 invoke 写入 LangGraph `checkpoint_ns`。
+     * 父图为空；子图为父节点 id。存储槽与父 thread 分开，不覆盖父 latest。
+     * HITL interrupt 用同一槽；resume 返回给父图入口的 GraphState 不含本字段，也不含内层 historyPath / currentNode。
+     */
+    checkpointNs?: string;
     [key: string]: unknown;
 }
 /** Graph 内部消息格式 */

package/dist/graph/hitl/hitl-handler.d.ts

@@ -13,7 +13,7 @@
 import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
 import type { ITraceCollector } from '../../contracts/trace-collector.js';
 import type { ISSEEmitter } from '../../sse/contracts/sse-emitter.contract.js';
-import type { GraphState } from '../contracts/executable-graph.js';
+import type { GraphState, CheckpointData } from '../contracts/executable-graph.js';
 /** HITL 默认等待时长（毫秒）= 300 秒。SSE `hitl.waited.timeout` 对外用秒。 */
 export declare const DEFAULT_HITL_TIMEOUT_MS = 300000;
 /** 超时收口对外文案（Task / Trace / AppError）；枚举走 `hitl_timeout`。 */
@@ -106,6 +106,8 @@ export declare class HitlPausedError extends Error {
 export declare function unwrapHitlPaused(error: unknown): HitlPausedError | null;
 /** Checkpoint state 中持久化的 HITL 等待元数据（进程重启 / 无内存 Map 时冷恢复） */
 export declare const HITL_WAITING_STATE_KEY = "__hitlWaiting";
+/** 父槽上的指针：子图 HITL 的 waiting 在 `sessionId#父节点id`，冷恢复只带 sessionId 时跟随此键。 */
+export declare const HITL_WAITING_SLOT_KEY = "__hitlWaitingSlot";
 export interface PersistedHitlWaiting {
     taskId: string;
     threadId: string;
@@ -141,6 +143,12 @@ export declare function toHitlTimeoutMs(timeoutMs?: number): number;
 export declare function toHitlTimeoutSeconds(timeoutMs?: number): number;
 export declare function isHitlDeadlinePassed(persisted: Pick<PersistedHitlWaiting, 'deadlineAt'> | undefined, now?: number): boolean;
 export declare function readPersistedHitlWaiting(state: unknown): PersistedHitlWaiting | undefined;
+export declare function readHitlWaitingSlot(state: unknown): string | undefined;
+/** 父槽有 waiting 用父槽；否则跟随 `__hitlWaitingSlot` 到子图槽。 */
+export declare function loadHitlCheckpoint(saver: ICheckpointSaver, threadId: string): Promise<{
+    threadId: string;
+    checkpoint: CheckpointData | null;
+}>;
 /** 门面 stream / HTTP StreamOrchestrator / streamResumeHitl 共用 */
 export declare function buildHitlWaitedPayload(paused: HitlPausedError): {
     question: string;
@@ -177,9 +185,10 @@ export declare class HitlHandler {
     /**
      * 中断 Graph 执行，等待人工确认
      *
-     * 写入 `__hitlWaiting`（含 deadlineAt）到同一 thread 的 Checkpoint。
-     * 不保留 LangGraph `engineSnapshot`：子图与父图共用 session thread，
-     * resume 时用 GraphState 从父图入口重入（skillSpanId / hitlChoice 防重复 span）。
+     * 写入 `__hitlWaiting`（含 deadlineAt）到当前执行图的 Checkpoint 槽。
+     * 父图槽=sessionId；子图槽=sessionId#父节点id（与 LangGraph put 同一把钥匙）。
+     * 不保留 LangGraph `engineSnapshot`：resume 从父图入口重入
+     *（skillSpanId / hitlChoice 防重复 span；子图 resume 去掉 checkpointNs / 内层 historyPath / currentNode）。
      */
     interrupt(taskId: string, threadId: string, state: GraphState, config: HitlInterruptConfig, extras?: HitlInterruptExtras): Promise<void>;
     private interruptCore;

package/dist/graph/hitl/hitl-handler.js

@@ -118,6 +118,8 @@ export function unwrapHitlPaused(error) {
 }
 /** Checkpoint state 中持久化的 HITL 等待元数据（进程重启 / 无内存 Map 时冷恢复） */
 export const HITL_WAITING_STATE_KEY = '__hitlWaiting';
+/** 父槽上的指针：子图 HITL 的 waiting 在 `sessionId#父节点id`，冷恢复只带 sessionId 时跟随此键。 */
+export const HITL_WAITING_SLOT_KEY = '__hitlWaitingSlot';
 export function toHitlTimeoutMs(timeoutMs) {
     if (typeof timeoutMs !== 'number' || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         return DEFAULT_HITL_TIMEOUT_MS;
@@ -142,6 +144,29 @@ export function readPersistedHitlWaiting(state) {
         return undefined;
     return raw;
 }
+export function readHitlWaitingSlot(state) {
+    if (!state || typeof state !== 'object')
+        return undefined;
+    const raw = state[HITL_WAITING_SLOT_KEY];
+    if (typeof raw === 'string' && raw.trim())
+        return raw.trim();
+    return undefined;
+}
+/** 父槽有 waiting 用父槽；否则跟随 `__hitlWaitingSlot` 到子图槽。 */
+export async function loadHitlCheckpoint(saver, threadId) {
+    const first = await saver.load(threadId);
+    if (readPersistedHitlWaiting(first?.state)) {
+        return { threadId, checkpoint: first };
+    }
+    const slot = readHitlWaitingSlot(first?.state);
+    if (slot && slot !== threadId) {
+        const nested = await saver.load(slot);
+        if (readPersistedHitlWaiting(nested?.state)) {
+            return { threadId: slot, checkpoint: nested };
+        }
+    }
+    return { threadId, checkpoint: first };
+}
 /** 门面 stream / HTTP StreamOrchestrator / streamResumeHitl 共用 */
 export function buildHitlWaitedPayload(paused) {
     return {
@@ -243,9 +268,10 @@ export class HitlHandler {
     /**
      * 中断 Graph 执行，等待人工确认
      *
-     * 写入 `__hitlWaiting`（含 deadlineAt）到同一 thread 的 Checkpoint。
-     * 不保留 LangGraph `engineSnapshot`：子图与父图共用 session thread，
-     * resume 时用 GraphState 从父图入口重入（skillSpanId / hitlChoice 防重复 span）。
+     * 写入 `__hitlWaiting`（含 deadlineAt）到当前执行图的 Checkpoint 槽。
+     * 父图槽=sessionId；子图槽=sessionId#父节点id（与 LangGraph put 同一把钥匙）。
+     * 不保留 LangGraph `engineSnapshot`：resume 从父图入口重入
+     *（skillSpanId / hitlChoice 防重复 span；子图 resume 去掉 checkpointNs / 内层 historyPath / currentNode）。
      */
     async interrupt(taskId, threadId, state, config, extras = {}) {
         const work = () => this.interruptCore(taskId, threadId, state, config, extras);
@@ -300,6 +326,28 @@ export class HitlHandler {
         };
         const persistedCheckpoint = stripCheckpointCollectors(checkpointData);
         await this.checkpointSaver.save(threadId, persistedCheckpoint);
+        const parentSessionId = typeof state.sessionId === 'string' && state.sessionId.trim()
+            ? state.sessionId.trim()
+            : '';
+        if (parentSessionId && threadId !== parentSessionId) {
+            const parent = await this.checkpointSaver.load(parentSessionId);
+            const pointerState = {
+                ...(parent?.state ?? { messages: [], userId: state.userId ?? '', sessionId: parentSessionId }),
+                [HITL_WAITING_SLOT_KEY]: threadId,
+            };
+            await this.checkpointSaver.save(parentSessionId, stripCheckpointCollectors({
+                checkpointId: parent?.checkpointId ?? `hitl-slot-${taskId}`,
+                threadId: parentSessionId,
+                currentNodeId: parent?.currentNodeId ?? '__hitl_waiting__',
+                historyPath: parent?.historyPath ?? [],
+                state: pointerState,
+                createdBy: parent?.createdBy ?? 'system',
+                createdAt: parent?.createdAt ?? now,
+                updatedBy: 'system',
+                updatedAt: now,
+                isDeleted: false,
+            }));
+        }
         const liveCollector = getExecutionTrace()?.collector;
         if (liveCollector) {
             this.waitingCollectors.set(taskId, liveCollector);
@@ -352,13 +400,14 @@ export class HitlHandler {
     async resume(taskId, choice, userId, threadIdHint) {
         return this.withTaskLock(taskId, async () => {
             let waiting = this.waitingTasks.get(taskId);
-            const threadId = waiting?.threadId ?? threadIdHint;
-            if (!threadId) {
+            const hinted = waiting?.threadId ?? threadIdHint;
+            if (!hinted) {
                 throw new HitlNotWaitingError(taskId);
             }
-            const checkpoint = await this.checkpointSaver.load(threadId);
+            const resolved = await loadHitlCheckpoint(this.checkpointSaver, hinted);
+            const checkpoint = resolved.checkpoint;
             if (!checkpoint) {
-                throw new Error(`Checkpoint not found for thread: ${threadId}`);
+                throw new Error(`Checkpoint not found for thread: ${resolved.threadId}`);
             }
             const persisted = readPersistedHitlWaiting(checkpoint.state);
             if (persisted?.timedOut) {
@@ -380,6 +429,13 @@ export class HitlHandler {
             const baseState = prepareHitlCheckpointState(checkpoint.state);
             const cleaned = { ...baseState };
             delete cleaned[HITL_WAITING_STATE_KEY];
+            const subgraphNs = typeof cleaned['checkpointNs'] === 'string' ? String(cleaned['checkpointNs']).trim() : '';
+            delete cleaned['checkpointNs'];
+            if (subgraphNs) {
+                // 父图入口重入：内层路径不能带进父图，否则 historyPath 混入子图节点。
+                delete cleaned['historyPath'];
+                delete cleaned['currentNode'];
+            }
             const resumedState = {
                 ...cleaned,
                 hitlChoice: choice,
@@ -395,6 +451,21 @@ export class HitlHandler {
                 updatedBy: userId,
                 updatedAt: now,
             }));
+            const parentSessionId = typeof resumedState.sessionId === 'string' && resumedState.sessionId.trim()
+                ? resumedState.sessionId.trim()
+                : '';
+            if (parentSessionId && waiting.threadId !== parentSessionId) {
+                const parent = await this.checkpointSaver.load(parentSessionId);
+                if (readHitlWaitingSlot(parent?.state) === waiting.threadId && parent) {
+                    const parentState = { ...parent.state };
+                    delete parentState[HITL_WAITING_SLOT_KEY];
+                    await this.checkpointSaver.save(parentSessionId, stripCheckpointCollectors({
+                        ...parent,
+                        state: parentState,
+                        updatedAt: now,
+                    }));
+                }
+            }
             const hitlSpanId = waiting.hitlSpanId ?? persisted?.hitlSpanId;
             const resumeTraceId = resolveTraceId(resumedState) ?? resolveTraceId(checkpoint.state);
             const resumeCtx = liveCollector && resumeTraceId

package/dist/graph/nodes/tool-node.js

@@ -16,12 +16,12 @@ import { inferHarnessSkillDir } from '../../tool/skill-dir-infer.js';
 import { isHitlDecision, unwrapHitlPaused } from '../hitl/hitl-handler.js';
 import { ToolConfirmationInterceptor } from '../../tool/tool-confirmation.js';
 import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.js';
-import { toolTraceIdentity } from '../../tool/mcp-list.js';
+import { mcpToolsetCode, toolTraceIdentity } from '../../tool/mcp-list.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
 import { emitRuntimeLog } from '../../common/logger.js';
 import { decideBeforeTool, } from '../../execution/interceptors.js';
 import { isRetryableToolFailure, resolveToolRetryConfig, sleepToolRetry, toolRetryDelayMs, } from '../../tool/tool-retry.js';
-import { assertIsolatedSkillAllowsHitl, isIsolatedSkillState } from '../adapters/skill-isolate.js';
+import { isIsolatedSkillState } from '../adapters/skill-isolate.js';
 function skillDirsFromState(state) {
     const defs = state['skillDefinitions'];
     return Object.values(defs ?? {})
@@ -92,6 +92,7 @@ export class ToolNode {
         // 4. 转换为 ToolCallRequest[]（附带 manifest 路由字段）
         const requests = lastAssistantMessage.toolCalls.map((tc) => {
             const loaded = loadedTools?.[tc.name];
+            const toolsetCode = mcpToolsetCode(loaded);
             const correlationId = String(state['correlationId'] ?? tc.id);
             const taskId = String(state['taskId'] ?? state['correlationId'] ?? tc.id);
             const command = typeof tc.arguments?.command === 'string' ? tc.arguments.command : undefined;
@@ -114,6 +115,7 @@ export class ToolNode {
                 // dev 上下文 DevMcpExecutor 直连所需；server 上下文会忽略
                 execution: loaded?.manifest.execution,
                 ...(loaded?.manifest.version ? { toolVersion: loaded.manifest.version } : {}),
+                ...(toolsetCode ? { toolsetCode } : {}),
                 correlationId,
                 taskId,
                 ...(jail.workdir ? { jailWorkdir: jail.workdir } : {}),
@@ -231,10 +233,6 @@ export class ToolNode {
                 else {
                     const askHitl = gate.action === 'ask' || (needsHitl && confirmationTools.has(req.toolName));
                     if (askHitl && this.hitlHandler) {
-                        // 隔离子图未按独立 HITL 线程设计；interrupt 前拒绝，避免写错父 Checkpoint。
-                        if (!resumingHitl) {
-                            assertIsolatedSkillAllowsHitl(state);
-                        }
                         const confirmSet = new Set(confirmationTools);
                         if (gate.action === 'ask')
                             confirmSet.add(req.toolName);
@@ -510,10 +508,17 @@ export class ToolNode {
         const delegationToken = String(executionContext?.delegationToken ??
             state['delegationToken'] ??
             this.defaultAuthContext.delegationToken);
+        const fromState = typeof state['agentVersion'] === 'string' ? state['agentVersion'].trim() : '';
+        const agentDir = typeof state['agentDir'] === 'string' ? state['agentDir'].trim() : '';
+        const fromDir = agentDir
+            ? agentDir.split(/[/\\]/).filter(Boolean).pop()
+            : undefined;
+        const agentVersion = fromState || fromDir;
         return {
             userId,
             delegationToken,
             agentCode,
+            ...(agentVersion ? { agentVersion } : {}),
         };
     }
     shouldForceServer(state, toolName) {

package/dist/providers/index.d.ts

@@ -2,6 +2,6 @@ export { EchoLLMProvider, createDefaultLLMProvider } from './echo-llm-provider.j
 export { HttpLLMProvider, DEFAULT_LLM_HTTP_TIMEOUT_MS, type HttpLLMProviderConfig } from './http-llm-provider.js';
 export { RoutingLLMProvider, type RoutingLLMProviderConfig, assertFoundationModelsInvokeAllowsStream, isFoundationModelsInvokeEnabled, MODELS_INVOKE_STREAM_MESSAGE, } from './routing-llm-provider.js';
 export { resolveLlmModelName, canOverrideGraphModel } from './resolve-llm-model.js';
-export { createLocalLlmProvider, requireLocalLlmConnections, resolveLocalLlmConnection, parseLocalLlmConnectionRefs, hydrateLocalLlmConnections, LLM_CONNECTIONS_ENV, } from './local-llm-provider.js';
+export { createLocalLlmProvider, createOptionalLocalLlmProvider, requireLocalLlmConnections, resolveLocalLlmConnection, parseLocalLlmConnectionRefs, hydrateLocalLlmConnections, hasLocalLlmConnection, LLM_CONNECTIONS_ENV, } from './local-llm-provider.js';
 export type { LocalLlmConnection, LocalLlmConnectionRef, LocalLlmConnectionRefs, LocalLlmConnections, } from './local-llm-provider.js';
 export type { LLMToolDefinition } from '../graph/nodes/llm-node.js';

package/dist/providers/index.js

@@ -2,4 +2,4 @@ export { EchoLLMProvider, createDefaultLLMProvider } from './echo-llm-provider.j
 export { HttpLLMProvider, DEFAULT_LLM_HTTP_TIMEOUT_MS } from './http-llm-provider.js';
 export { RoutingLLMProvider, assertFoundationModelsInvokeAllowsStream, isFoundationModelsInvokeEnabled, MODELS_INVOKE_STREAM_MESSAGE, } from './routing-llm-provider.js';
 export { resolveLlmModelName, canOverrideGraphModel } from './resolve-llm-model.js';
-export { createLocalLlmProvider, requireLocalLlmConnections, resolveLocalLlmConnection, parseLocalLlmConnectionRefs, hydrateLocalLlmConnections, LLM_CONNECTIONS_ENV, } from './local-llm-provider.js';
+export { createLocalLlmProvider, createOptionalLocalLlmProvider, requireLocalLlmConnections, resolveLocalLlmConnection, parseLocalLlmConnectionRefs, hydrateLocalLlmConnections, hasLocalLlmConnection, LLM_CONNECTIONS_ENV, } from './local-llm-provider.js';

package/dist/providers/local-llm-provider.d.ts

@@ -29,6 +29,12 @@ export interface LocalLlmConnections {
 export declare const LLM_CONNECTIONS_ENV = "EAP_LLM_CONNECTIONS";
 export declare function parseLocalLlmConnectionRefs(env?: NodeJS.ProcessEnv): LocalLlmConnectionRefs;
 export declare function hydrateLocalLlmConnections(refs: LocalLlmConnectionRefs, env?: NodeJS.ProcessEnv): LocalLlmConnections;
+export declare function hasLocalLlmConnection(connections: LocalLlmConnections): boolean;
 export declare function requireLocalLlmConnections(env?: NodeJS.ProcessEnv): LocalLlmConnections;
+/**
+ * Routing 的可选 fallback：有可用本地连接才返回 Provider。
+ * 连接表 JSON 损坏仍抛错；解不出密钥则视为没有本地网关。
+ */
+export declare function createOptionalLocalLlmProvider(turnLog?: ILlmTurnLog, env?: NodeJS.ProcessEnv): ILLMProvider | undefined;
 export declare function resolveLocalLlmConnection(connections: LocalLlmConnections, model?: string): LocalLlmConnection;
 export declare function createLocalLlmProvider(connections?: LocalLlmConnections, turnLog?: ILlmTurnLog): ILLMProvider;

package/dist/providers/local-llm-provider.js

@@ -63,10 +63,13 @@ export function hydrateLocalLlmConnections(refs, env = process.env) {
     }
     return { default: hydrate(refs.default), byModel };
 }
+export function hasLocalLlmConnection(connections) {
+    return Boolean(connections.default?.apiKey) || Object.keys(connections.byModel ?? {}).length > 0;
+}
 export function requireLocalLlmConnections(env = process.env) {
     const refs = parseLocalLlmConnectionRefs(env);
     const connections = hydrateLocalLlmConnections(refs, env);
-    if (!connections.default && Object.keys(connections.byModel ?? {}).length === 0) {
+    if (!hasLocalLlmConnection(connections)) {
         const wanted = [
             refs.default?.apiKeyEnv,
             ...Object.values(refs.byModel ?? {}).map((ref) => ref.apiKeyEnv),
@@ -75,13 +78,34 @@ export function requireLocalLlmConnections(env = process.env) {
     }
     return connections;
 }
+/**
+ * Routing 的可选 fallback：有可用本地连接才返回 Provider。
+ * 连接表 JSON 损坏仍抛错；解不出密钥则视为没有本地网关。
+ */
+export function createOptionalLocalLlmProvider(turnLog, env = process.env) {
+    const refs = parseLocalLlmConnectionRefs(env);
+    const connections = hydrateLocalLlmConnections(refs, env);
+    if (!hasLocalLlmConnection(connections))
+        return undefined;
+    return createLocalLlmProvider(connections, turnLog);
+}
+function namedLocalModel(model) {
+    const trimmed = model?.trim();
+    if (!trimmed || trimmed.toLowerCase() === 'default')
+        return undefined;
+    return trimmed;
+}
 export function resolveLocalLlmConnection(connections, model) {
-    const named = model ? connections.byModel?.[model] : undefined;
+    const wanted = namedLocalModel(model);
+    const named = wanted ? connections.byModel?.[wanted] : undefined;
     const connection = named ?? connections.default;
     if (!connection?.apiKey) {
-        throw new Error(model
-            ? `No local LLM gateway for model ${model}. Set runtime.llm.models["${model}"] in eap.config.json.`
-            : 'No local LLM gateway. Set runtime.llm in eap.config.json.');
+        const available = Object.keys(connections.byModel ?? {}).sort();
+        const availableHint = available.length > 0 ? ` Available: ${available.join(', ')}.` : '';
+        if (wanted) {
+            throw new Error(`No local LLM gateway for model ${wanted}. Set runtime.llm.models["${wanted}"] in eap.config.json.${availableHint}`);
+        }
+        throw new Error(`No local LLM gateway. Set runtime.llm.models.default or runtime.llm.baseUrl in eap.config.json.${availableHint}`);
     }
     return connection;
 }

package/dist/providers/routing-llm-provider.d.ts

@@ -7,9 +7,9 @@
  * 3. 用返回的连接配置创建 HttpLLMProvider，发送请求
  *
  * 设计原则：
- * - Runtime 不存任何 LLM 凭证，全部从 Foundation 获取
+ * - 生产路径：Foundation `/models/select` 返回连接，本机 HTTP
+ * - select 失败或没有连接：走构造时注入的 fallback（dev 为 LocalLlmProvider / `resolveLocalLlmConnection`）
  * - 支持任意 OpenAI 兼容 API（OpenAI / DeepSeek / 本地 Ollama 等）
- * - 连接配置由 Foundation 统一管理，Runtime 无感知
  */
 import type { GraphMessage } from '../graph/contracts/executable-graph.js';
 import type { ILLMProvider, LLMNodeConfig, LLMResponse, LLMChunk } from '../graph/nodes/llm-node.js';

package/dist/providers/routing-llm-provider.js

@@ -7,9 +7,9 @@
  * 3. 用返回的连接配置创建 HttpLLMProvider，发送请求
  *
  * 设计原则：
- * - Runtime 不存任何 LLM 凭证，全部从 Foundation 获取
+ * - 生产路径：Foundation `/models/select` 返回连接，本机 HTTP
+ * - select 失败或没有连接：走构造时注入的 fallback（dev 为 LocalLlmProvider / `resolveLocalLlmConnection`）
  * - 支持任意 OpenAI 兼容 API（OpenAI / DeepSeek / 本地 Ollama 等）
- * - 连接配置由 Foundation 统一管理，Runtime 无感知
  */
 import { AppError, ErrorCodes, mergeModelCallParams } from '@gt-fe/eap-contracts';
 import { EchoLLMProvider } from './echo-llm-provider.js';
@@ -52,7 +52,7 @@ export class RoutingLLMProvider {
         return {
             ...config,
             ...merged,
-            model: selected.name,
+            model: selected.name || config.model,
             maxContextTokens: selected.maxContextTokens ?? config.maxContextTokens,
         };
     }
@@ -84,7 +84,7 @@ export class RoutingLLMProvider {
         catch {
             // fallback to local
         }
-        return { name: config.model ?? 'echo', provider: 'local', connection: null };
+        return { name: config.model ?? '', provider: 'local', connection: null };
     }
     useFoundationInvoke() {
         return isFoundationModelsInvokeEnabled();
@@ -93,7 +93,6 @@ export class RoutingLLMProvider {
         if (this.useFoundationInvoke()) {
             return new FoundationModelsInvokeProvider(this.foundationUrl, selected.name, this.turnLog);
         }
-        // 优先使用 Foundation 返回的连接配置
         if (selected.connection) {
             return new HttpLLMProvider({
                 apiKey: selected.connection.apiKey ?? '',
@@ -103,16 +102,7 @@ export class RoutingLLMProvider {
                 turnLog: this.turnLog,
             });
         }
-        // Fallback: 兼容旧逻辑（直接读 env）—— 开发环境快速启动用
-        if (process.env.OPENAI_API_KEY && selected.provider === 'openai') {
-            return new HttpLLMProvider({
-                apiKey: process.env.OPENAI_API_KEY,
-                baseUrl: process.env.OPENAI_BASE_URL,
-                defaultModel: selected.name,
-                timeoutMs: DEFAULT_LLM_HTTP_TIMEOUT_MS,
-                turnLog: this.turnLog,
-            });
-        }
+        // Foundation 未返回连接：与 LocalLlmProvider 同一把钥匙（由调用方注入 fallback）。
         return this.fallback;
     }
 }

package/dist/registry/deployment-snapshot.js

@@ -116,7 +116,7 @@ async function findDigestMatch(items, expectedRaw) {
     }
     return undefined;
 }
-async function warnIfDigestMismatch(expectedRaw, actualHex, label, details) {
+async function warnIfDigestMismatch(expectedRaw, actualHex, label, details, fail = false) {
     const expected = normalizeDigest(expectedRaw);
     if (!expected)
         return;
@@ -129,6 +129,13 @@ async function warnIfDigestMismatch(expectedRaw, actualHex, label, details) {
         actual,
         ...details,
     });
+    if (fail) {
+        throw preloadPackageCorrupt(`预装校验和不匹配: ${label}`, {
+            expected,
+            actual,
+            ...details,
+        });
+    }
 }
 async function pickLatestVersionDir(parent) {
     if (!(await pathExists(parent)))
@@ -373,6 +380,13 @@ export class FileSystemDeploymentSnapshot {
                         actual: fileDigest,
                         path: pkgFile,
                     });
+                    if (this.flags.requireChecksum || isRequireChecksum()) {
+                        throw preloadPackageCorrupt('snapshot.sha256 与 .package.sha256 不一致', {
+                            expected: expectedPkg,
+                            actual: fileDigest,
+                            path: pkgFile,
+                        });
+                    }
                 }
             }
         }
@@ -394,7 +408,7 @@ export class FileSystemDeploymentSnapshot {
                 throw preloadPackageCorrupt(`artifacts 指向的文件不存在: ${rel}`, { path: full });
             }
             const actual = await sha256OfFile(full);
-            await warnIfDigestMismatch(expected, actual, `artifact ${rel}`, { path: full });
+            await warnIfDigestMismatch(expected, actual, `artifact ${rel}`, { path: full }, this.flags.requireChecksum || isRequireChecksum());
         }
     }
     async resolveAgentDir(agentCode, version) {
@@ -499,7 +513,7 @@ export class FileSystemDeploymentSnapshot {
             if (ref.sha256) {
                 const matched = await findDigestMatch(existingManifests, ref.sha256);
                 if (!matched) {
-                    await warnIfDigestMismatch(ref.sha256, await sha256OfFile(existingManifests[0].path), `tool ${ref.name}`, { path: existingManifests[0].path });
+                    await warnIfDigestMismatch(ref.sha256, await sha256OfFile(existingManifests[0].path), `tool ${ref.name}`, { path: existingManifests[0].path }, this.flags.requireChecksum || isRequireChecksum());
                 }
                 chosen = matched ?? existingManifests[0];
             }
@@ -576,7 +590,7 @@ export class FileSystemDeploymentSnapshot {
                 !isAuthorOverlay &&
                 manifestPath.endsWith('.json')) {
                 const actual = await sha256OfFile(manifestPath);
-                await warnIfDigestMismatch(ref.sha256, actual, `skill ${ref.skillId}`, { path: manifestPath });
+                await warnIfDigestMismatch(ref.sha256, actual, `skill ${ref.skillId}`, { path: manifestPath }, this.flags.requireChecksum || isRequireChecksum());
             }
             const skillId = String(ref.skillId);
             return {

package/dist/registry/graph-loader.d.ts

@@ -108,6 +108,8 @@ export declare class GraphLoader {
     definitionCacheSize(): number;
     private cloneCached;
     loadGraph(agentCode: string, options?: LoadAgentOptions): Promise<GraphDSL>;
+    /** Agent `models.default`；无清单或未声明则 undefined。 */
+    resolveDefaultModel(agentCode: string, version?: string): Promise<string | undefined>;
     private loadGraphFromSource;
     /**
      * Agent 基线系统提示词（manifest.prompts.system）。