@gt-fe/eap-runtime 0.0.8

package/dist/registry/deployment-snapshot.js

@@ -0,0 +1,542 @@
+/**
+ * Deployment 预装快照读取（RT-4 / 04 Req 8.1 / 联调契约）
+ *
+ * 目录（Agent 自包含，无全局共享层）：
+ *   {root}/agents/<agentCode>/<version>/preinstall/tools/<toolsetCode>/
+ *   {root}/agents/<agentCode>/<version>/preinstall/skills/<skillCode>/
+ *   {root}/agents/<agentCode>/<version>/users/<userId>/skills/<skillCode>/
+ *
+ * 命名：agentCode / toolsetCode / skillCode / toolName 均为语义化小写标识；
+ * Skill 目录无版本层（维护形态为 ZIP 上传整包替换，包内必含 skill.md）。
+ */
+import { readdir, readFile, access } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { constants as fsConstants } from 'node:fs';
+import { preloadMissing, preloadPackageCorrupt, } from './preload-errors.js';
+import { isRequireChecksum, resolvePreloadBehaviorFlags, } from './preload-flags.js';
+async function pathExists(p) {
+    try {
+        await access(p, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readTextFile(filePath) {
+    try {
+        return await readFile(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+async function readJsonFile(filePath) {
+    const raw = await readTextFile(filePath);
+    if (raw == null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** JSON 优先；.yaml/.yml 尝试动态加载 yaml 包，失败则视为损坏 */
+async function readDataFile(filePath) {
+    const raw = await readTextFile(filePath);
+    if (raw == null)
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // continue to yaml
+    }
+    const lower = filePath.toLowerCase();
+    if (!lower.endsWith('.yaml') && !lower.endsWith('.yml')) {
+        throw preloadPackageCorrupt(`无法解析预装文件（非合法 JSON）: ${filePath}`);
+    }
+    // yaml 依赖：已列入 package.json；解析失败仍报 package_corrupt
+    try {
+        const yamlMod = await import('yaml');
+        const parsed = yamlMod.parse(trimmed);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        throw preloadPackageCorrupt(`YAML 根节点须为对象: ${filePath}`);
+    }
+    catch (err) {
+        if (err && typeof err === 'object' && 'code' in err)
+            throw err;
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Cannot find package') || msg.includes('Cannot find module')) {
+            throw preloadPackageCorrupt(`未安装 yaml 依赖，无法解析 ${filePath}；请改用 graph.json 或安装 yaml`);
+        }
+        throw preloadPackageCorrupt(`无法解析 YAML: ${filePath}`, { cause: msg });
+    }
+}
+function isPathInside(root, target) {
+    const relativePath = path.relative(path.resolve(root), path.resolve(target));
+    return relativePath === '' || (!relativePath.startsWith(`..${path.sep}`) && relativePath !== '..');
+}
+/** 规范化摘要：去 sha256: 前缀、空白，转小写 hex */
+export function normalizeDigest(value) {
+    if (typeof value !== 'string')
+        return null;
+    let s = value.trim();
+    if (!s)
+        return null;
+    if (s.toLowerCase().startsWith('sha256:'))
+        s = s.slice(7).trim();
+    s = s.toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(s))
+        return null;
+    return s;
+}
+async function sha256OfFile(filePath) {
+    const buf = await readFile(filePath);
+    return createHash('sha256').update(buf).digest('hex');
+}
+async function findDigestMatch(items, expectedRaw) {
+    const expected = normalizeDigest(expectedRaw);
+    if (!expected)
+        return undefined;
+    for (const item of items) {
+        const actual = await sha256OfFile(item.path);
+        if (normalizeDigest(actual) === expected)
+            return item;
+    }
+    return undefined;
+}
+async function assertDigestMatch(expectedRaw, actualHex, label, details) {
+    const expected = normalizeDigest(expectedRaw);
+    if (!expected)
+        return;
+    if (expected !== actualHex.toLowerCase()) {
+        throw preloadPackageCorrupt(`预装校验和不匹配: ${label}`, {
+            expected,
+            actual: actualHex.toLowerCase(),
+            ...details,
+        });
+    }
+}
+async function pickLatestVersionDir(parent) {
+    if (!(await pathExists(parent)))
+        return null;
+    const entries = await readdir(parent, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    if (dirs.includes('current')) {
+        return path.join(parent, 'current');
+    }
+    if (dirs.length === 0)
+        return null;
+    dirs.sort();
+    return path.join(parent, dirs[dirs.length - 1]);
+}
+function skillRefsFromManifest(manifest) {
+    const raw = manifest.skillRefs ?? manifest.skills;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const item of raw) {
+        if (typeof item === 'string') {
+            out.push({ skillId: item });
+            continue;
+        }
+        if (item && typeof item === 'object') {
+            const o = item;
+            const skillId = String(o.skill ?? o.skillId ?? o.skillCode ?? o.id ?? '');
+            if (!skillId)
+                continue;
+            out.push({
+                skillId,
+                name: o.name != null ? String(o.name) : undefined,
+                version: o.version != null ? String(o.version) : undefined,
+                description: o.description != null ? String(o.description) : undefined,
+                sha256: typeof o.sha256 === 'string' ? o.sha256 : undefined,
+            });
+        }
+    }
+    return out;
+}
+function parseStringList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = value.filter((x) => typeof x === 'string' && x.length > 0);
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * 装配引用（toolRefs / 简写 tools[]）vs 内联完整 ToolManifest。
+ * 含 type/execution 的视为内联定义；仅 toolset/name/version/enabledTools 等视为引用。
+ */
+export function isInlineToolDeclaration(item) {
+    if (!item || typeof item !== 'object' || Array.isArray(item))
+        return false;
+    const o = item;
+    return o.type != null || o.execution != null;
+}
+function parseToolAssemblyRef(item) {
+    if (typeof item === 'string') {
+        return item ? { name: item } : null;
+    }
+    if (!item || typeof item !== 'object' || Array.isArray(item))
+        return null;
+    if (isInlineToolDeclaration(item))
+        return null;
+    const o = item;
+    const name = String(o.toolset ?? o.name ?? o.toolId ?? o.id ?? '');
+    if (!name)
+        return null;
+    return {
+        name,
+        toolId: o.toolId != null ? String(o.toolId) : undefined,
+        version: o.version != null ? String(o.version) : undefined,
+        sha256: typeof o.sha256 === 'string' ? o.sha256 : undefined,
+        enabledTools: parseStringList(o.enabledTools),
+        autoApprove: parseStringList(o.autoApprove),
+    };
+}
+/**
+ * 从 agent.manifest 收集工具集装配引用：优先 toolRefs[]，再合并简写 tools[]（非内联项）。
+ */
+function toolRefsFromManifest(manifest) {
+    const out = [];
+    const byName = new Map();
+    const upsert = (ref) => {
+        const prev = byName.get(ref.name);
+        if (!prev) {
+            byName.set(ref.name, ref);
+            out.push(ref);
+            return;
+        }
+        // 后写补全白名单等字段，不覆盖已有显式值
+        if (!prev.enabledTools && ref.enabledTools)
+            prev.enabledTools = ref.enabledTools;
+        if (!prev.autoApprove && ref.autoApprove)
+            prev.autoApprove = ref.autoApprove;
+        if (!prev.version && ref.version)
+            prev.version = ref.version;
+        if (!prev.sha256 && ref.sha256)
+            prev.sha256 = ref.sha256;
+        if (!prev.toolId && ref.toolId)
+            prev.toolId = ref.toolId;
+    };
+    for (const item of Array.isArray(manifest.toolRefs) ? manifest.toolRefs : []) {
+        const ref = parseToolAssemblyRef(item);
+        if (ref)
+            upsert(ref);
+    }
+    for (const item of Array.isArray(manifest.tools) ? manifest.tools : []) {
+        const ref = parseToolAssemblyRef(item);
+        if (ref)
+            upsert(ref);
+    }
+    return out;
+}
+/**
+ * 将 agent.manifest.toolRefs 上的 enabledTools/autoApprove 叠到 snapshot.tools[]（snapshot 未带时）。
+ */
+export function overlayToolRefPolicies(snapTools, manifest) {
+    if (!manifest)
+        return snapTools;
+    const fromManifest = toolRefsFromManifest(manifest);
+    if (fromManifest.length === 0)
+        return snapTools;
+    const byName = new Map(fromManifest.map((r) => [r.name, r]));
+    return snapTools.map((t) => {
+        const m = byName.get(t.name) ?? (t.toolId ? byName.get(t.toolId) : undefined);
+        if (!m)
+            return t;
+        return {
+            ...t,
+            enabledTools: t.enabledTools ?? m.enabledTools,
+            autoApprove: t.autoApprove ?? m.autoApprove,
+        };
+    });
+}
+function normalizeSnapshotToolRefs(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    for (const item of raw) {
+        const ref = parseToolAssemblyRef(item);
+        if (ref)
+            out.push(ref);
+    }
+    return out;
+}
+function normalizeSnapshotSkillRefs(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    for (const item of raw) {
+        if (typeof item === 'string') {
+            out.push({ skillId: item });
+            continue;
+        }
+        if (item && typeof item === 'object') {
+            const o = item;
+            const skillId = String(o.skill ?? o.skillId ?? o.code ?? o.skillCode ?? o.id ?? '');
+            if (!skillId)
+                continue;
+            out.push({
+                skillId,
+                name: o.name != null ? String(o.name) : undefined,
+                version: o.version != null ? String(o.version) : undefined,
+                description: o.description != null ? String(o.description) : undefined,
+                sha256: typeof o.sha256 === 'string' ? o.sha256 : undefined,
+            });
+        }
+    }
+    return out;
+}
+export class FileSystemDeploymentSnapshot {
+    root;
+    flags;
+    constructor(root, options = {}) {
+        this.root = root;
+        this.flags = resolvePreloadBehaviorFlags({
+            requireReady: options.requireReady,
+            requireChecksum: options.requireChecksum,
+        });
+    }
+    get requireReady() {
+        return this.flags.requireReady;
+    }
+    async assertReadyIfRequired(bundlePath, label) {
+        if (!this.requireReady)
+            return;
+        const readyPath = path.join(bundlePath, '.ready');
+        if (!(await pathExists(readyPath))) {
+            throw preloadMissing(`预装未就绪（缺少 .ready）: ${label}`, { path: readyPath });
+        }
+    }
+    async verifySnapshotIntegrity(agentDir, snap) {
+        const expectedPkg = normalizeDigest(snap.sha256 ?? snap.packageSha256);
+        const artifacts = snap.artifacts;
+        const hasArtifacts = Array.isArray(artifacts) && artifacts.length > 0;
+        if (this.flags.requireChecksum || isRequireChecksum()) {
+            if (!expectedPkg && !hasArtifacts) {
+                throw preloadPackageCorrupt('已启用 requireChecksum，snapshot 须含 sha256/packageSha256 或非空 artifacts[]', { agentDir });
+            }
+        }
+        if (expectedPkg) {
+            const pkgFile = path.join(agentDir, '.package.sha256');
+            if (await pathExists(pkgFile)) {
+                const raw = (await readTextFile(pkgFile))?.trim() ?? '';
+                const fileDigest = normalizeDigest(raw);
+                if (!fileDigest) {
+                    throw preloadPackageCorrupt(`.package.sha256 内容非法`, { path: pkgFile });
+                }
+                if (fileDigest !== expectedPkg) {
+                    throw preloadPackageCorrupt(`snapshot.sha256 与 .package.sha256 不一致（以 snapshot 为准核对）`, {
+                        expected: expectedPkg,
+                        actual: fileDigest,
+                        path: pkgFile,
+                    });
+                }
+            }
+        }
+        if (!Array.isArray(artifacts))
+            return;
+        for (const item of artifacts) {
+            if (!item || typeof item !== 'object')
+                continue;
+            const o = item;
+            const rel = typeof o.path === 'string' ? o.path : typeof o.file === 'string' ? o.file : null;
+            const expected = normalizeDigest(o.sha256 ?? o.digest);
+            if (!rel || !expected)
+                continue;
+            const full = path.resolve(agentDir, rel);
+            if (!isPathInside(agentDir, full)) {
+                throw preloadPackageCorrupt(`artifacts.path 越出 agent 包目录: ${rel}`);
+            }
+            if (!(await pathExists(full))) {
+                throw preloadPackageCorrupt(`artifacts 指向的文件不存在: ${rel}`, { path: full });
+            }
+            const actual = await sha256OfFile(full);
+            await assertDigestMatch(expected, actual, `artifact ${rel}`, { path: full });
+        }
+    }
+    async resolveAgentDir(agentCode, version) {
+        const agentRoot = path.join(this.root, 'agents', agentCode);
+        if (version) {
+            const exact = path.join(agentRoot, version);
+            return (await pathExists(exact)) ? exact : null;
+        }
+        return pickLatestVersionDir(agentRoot);
+    }
+    async loadAgentManifest(agentDir) {
+        return ((await readJsonFile(path.join(agentDir, 'agent.manifest.json'))) ??
+            (await readJsonFile(path.join(agentDir, 'manifest.json'))));
+    }
+    async loadGraphDocument(agentDir, manifest) {
+        const relative = typeof manifest?.graph === 'string'
+            ? manifest.graph
+            : typeof manifest?.graphPath === 'string'
+                ? String(manifest.graphPath)
+                : null;
+        const candidates = [];
+        if (relative)
+            candidates.push(path.join(agentDir, relative));
+        candidates.push(path.join(agentDir, 'graph.json'), path.join(agentDir, 'graph.yaml'), path.join(agentDir, 'graph.yml'), path.join(agentDir, 'graph.yaml.json'));
+        for (const filePath of candidates) {
+            if (!(await pathExists(filePath)))
+                continue;
+            try {
+                const doc = await readDataFile(filePath);
+                if (doc)
+                    return doc;
+            }
+            catch (err) {
+                throw err;
+            }
+        }
+        return null;
+    }
+    async loadAgentSnapshot(agentCode, version) {
+        const agentDir = await this.resolveAgentDir(agentCode, version);
+        if (!agentDir)
+            return null;
+        await this.assertReadyIfRequired(agentDir, `agent ${agentCode}`);
+        const snap = (await readJsonFile(path.join(agentDir, 'snapshot.json'))) ??
+            (await readJsonFile(path.join(agentDir, 'eap.snapshot.json')));
+        const manifest = await this.loadAgentManifest(agentDir);
+        const resolvedVersion = version ?? path.basename(agentDir);
+        if (snap) {
+            await this.verifySnapshotIntegrity(agentDir, snap);
+            let graph = snap.graph;
+            if (!graph || typeof graph !== 'object') {
+                graph = (await this.loadGraphDocument(agentDir, manifest)) ?? undefined;
+            }
+            return {
+                agentCode,
+                version: String(snap.version ?? resolvedVersion),
+                tools: normalizeSnapshotToolRefs(snap.tools) ?? toolRefsFromManifest(manifest ?? {}),
+                skills: normalizeSnapshotSkillRefs(snap.skills) ?? skillRefsFromManifest(manifest ?? {}),
+                graph,
+                agentDir,
+                manifest: manifest ?? undefined,
+            };
+        }
+        const graph = (await this.loadGraphDocument(agentDir, manifest)) ?? undefined;
+        return {
+            agentCode,
+            version: resolvedVersion,
+            tools: toolRefsFromManifest(manifest ?? {}),
+            skills: skillRefsFromManifest(manifest ?? {}),
+            graph,
+            agentDir,
+            manifest: manifest ?? undefined,
+        };
+    }
+    async loadToolManifest(ref, agentDir) {
+        const candidates = [];
+        if (agentDir) {
+            // Agent 自包含：唯一查找位置为 preinstall/tools/<toolsetCode>（语义化小写标识）
+            candidates.push(path.join(agentDir, 'preinstall', 'tools', ref.name));
+            if (ref.toolId && ref.toolId !== ref.name) {
+                candidates.push(path.join(agentDir, 'preinstall', 'tools', ref.toolId));
+            }
+        }
+        for (const bundlePath of candidates) {
+            if (!(await pathExists(bundlePath)))
+                continue;
+            await this.assertReadyIfRequired(bundlePath, `tool ${ref.name}`);
+            const manifestPathCandidates = [
+                path.join(bundlePath, 'toolset.manifest.json'),
+                path.join(bundlePath, 'tool.manifest.json'),
+                path.join(bundlePath, 'manifest.json'),
+            ];
+            const existingManifests = [];
+            for (const mp of manifestPathCandidates) {
+                const doc = await readJsonFile(mp);
+                if (doc)
+                    existingManifests.push({ path: mp, doc });
+            }
+            if (existingManifests.length === 0)
+                continue;
+            let chosen = existingManifests[0];
+            if (ref.sha256) {
+                const matched = await findDigestMatch(existingManifests, ref.sha256);
+                if (!matched) {
+                    await assertDigestMatch(ref.sha256, await sha256OfFile(existingManifests[0].path), `tool ${ref.name}`, { path: existingManifests[0].path });
+                }
+                chosen = matched ?? existingManifests[0];
+            }
+            const manifest = chosen.doc;
+            return {
+                toolId: String(manifest.id ?? ref.toolId ?? manifest.code ?? ref.name),
+                name: String(manifest.code ?? manifest.name ?? ref.name),
+                version: String(manifest.version ?? ref.version ?? path.basename(bundlePath)),
+                manifest,
+                bundlePath,
+            };
+        }
+        return null;
+    }
+    async loadSkillManifest(ref, agentDir, userId, extraRoots = []) {
+        if (!agentDir)
+            return null;
+        // 用户装配 → 开发态作者源 extraRoots → Agent 预装
+        const candidates = [];
+        if (userId != null && userId !== '') {
+            candidates.push(path.join(agentDir, 'users', userId, 'skills', ref.skillId));
+        }
+        for (const root of extraRoots) {
+            if (root)
+                candidates.push(path.join(root, ref.skillId));
+        }
+        candidates.push(path.join(agentDir, 'preinstall', 'skills', ref.skillId));
+        for (const bundlePath of candidates) {
+            if (!(await pathExists(bundlePath)))
+                continue;
+            await this.assertReadyIfRequired(bundlePath, `skill ${ref.skillId}`);
+            const manifestPathCandidates = [
+                path.join(bundlePath, 'skill.manifest.json'),
+                path.join(bundlePath, 'skill.definition.json'),
+                path.join(bundlePath, 'manifest.json'),
+            ];
+            let manifest = null;
+            let manifestPath = null;
+            for (const mp of manifestPathCandidates) {
+                const doc = await readJsonFile(mp);
+                if (doc) {
+                    manifest = doc;
+                    manifestPath = mp;
+                    break;
+                }
+            }
+            if (!manifest || !manifestPath)
+                continue;
+            // 用户装配层跳过 sha256 校验（用户覆盖版本与预装快照散列不同是正常行为）
+            const isUserOverridePath = bundlePath.includes('/users/') || bundlePath.includes('\\users\\');
+            const isAuthorOverlay = extraRoots.some((root) => root && isPathInside(root, bundlePath));
+            if (ref.sha256 && !isUserOverridePath && !isAuthorOverlay) {
+                const actual = await sha256OfFile(manifestPath);
+                await assertDigestMatch(ref.sha256, actual, `skill ${ref.skillId}`, { path: manifestPath });
+            }
+            const skillId = String(manifest.code ?? manifest.skillId ?? manifest.skillCode ?? manifest.id ?? ref.skillId);
+            return {
+                skillId,
+                name: String(manifest.name ?? ref.name ?? skillId),
+                version: String(manifest.version ?? ref.version ?? path.basename(bundlePath)),
+                description: manifest.description ?? ref.description,
+                manifest,
+                bundlePath,
+            };
+        }
+        return null;
+    }
+}
+export function createDeploymentSnapshotFromEnv(explicitRoot, options) {
+    const root = explicitRoot ?? process.env.EAP_PREINSTALL_ROOT;
+    if (!root)
+        return undefined;
+    return new FileSystemDeploymentSnapshot(root, options);
+}

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

@@ -0,0 +1,134 @@
+/**
+ * GraphLoader — 从 Agent Registry / Deployment 预装快照加载 Graph DSL 与 Tool/Skill 定义
+ *
+ * 生产（server + EAP_PREINSTALL_ROOT）：以预装为准，缺失则失败（04 Req 8.1）。
+ * 开发态：Registry + 可选 ./tools 本地 manifest。
+ */
+import type { GraphDSL } from '../graph/contracts/executable-graph.js';
+import type { AgentRegistryClient } from './agent-registry-client.js';
+import type { DeploymentContext } from '../tool/tool-execution-router.js';
+import type { ILocalToolInstallStore } from '@gt-fe/eap-contracts';
+import { type LoadedToolDefinition } from '../tool/loaded-tool-definition.js';
+import type { LoadedSkillInfo } from '../tool/system-prompt-builder.js';
+import { type IDeploymentSnapshot } from './deployment-snapshot.js';
+export interface LoadAgentOptions {
+    /** 覆盖构造时 / 环境默认的 agentVersion */
+    agentVersion?: string;
+    /** 跳过读写进程内定义缓存 */
+    bypassCache?: boolean;
+}
+export interface GraphLoaderConfig {
+    registryClient?: AgentRegistryClient;
+    deploymentContext?: DeploymentContext;
+    localInstallStore?: ILocalToolInstallStore;
+    /** dev：本地 Tool manifest 目录，默认 `./tools` 或 `EAP_LOCAL_TOOLS_DIR` */
+    localToolsDir?: string;
+    /**
+     * dev：作者源 Skill 目录（工程 `skills/` 或 `EAP_LOCAL_SKILLS_DIR`）。
+     * 查找优先于预装树，低于 users/；生产不要设。
+     */
+    localSkillsDir?: string;
+    /**
+     * Deployment 预装根目录（或注入 IDeploymentSnapshot）。
+     * 也可用环境变量 EAP_PREINSTALL_ROOT。
+     */
+    preinstallRoot?: string;
+    deploymentSnapshot?: IDeploymentSnapshot;
+    /**
+     * server 且配置了预装时默认 true：缺失预装则失败，且不回退 Registry 拉定义。
+     * 显式 false 可回退 Registry（仅迁移/联调）。
+     */
+    strictPreinstall?: boolean;
+    /** Agent 版本目录名；缺省取 current/最新；可被单次 load 的 agentVersion 覆盖 */
+    agentVersion?: string;
+    /** 强制 .ready；默认 EAP_PRELOAD_REQUIRE_READY */
+    requireReady?: boolean;
+    /** 强制 snapshot 校验字段；默认 EAP_PRELOAD_REQUIRE_CHECKSUM */
+    requireChecksum?: boolean;
+    /**
+     * 进程内定义缓存。默认：存在预装根时开启。
+     * 环境变量 EAP_PRELOAD_DEFINITION_CACHE=0 关闭。
+     */
+    definitionCache?: boolean;
+    /**
+     * Skill 热加载：已装配目录 mtime 变化则丢缓存。
+     * 默认：deploymentContext=dev 开启；EAP_SKILL_HOT_RELOAD=0/1 可覆盖。
+     */
+    skillHotReload?: boolean;
+}
+export interface LoadToolDefinitionsOptions extends LoadAgentOptions {
+    /** 仅保留 status=active，默认 true */
+    activeOnly?: boolean;
+}
+export interface ExpandToolsetOptions {
+    /** 可选白名单；列出则仅启用所列子工具；省略 = 全部 */
+    enabledTools?: string[];
+    /** 免 HITL 确认的子工具名 */
+    autoApprove?: string[];
+}
+export declare class GraphLoader {
+    private readonly registryClient?;
+    private readonly deploymentContext;
+    private readonly localInstallStore?;
+    private readonly localToolsDir?;
+    private readonly localSkillsDir?;
+    private readonly deploymentSnapshot?;
+    private readonly strictPreinstall;
+    private readonly agentVersion?;
+    private readonly definitionCacheEnabled;
+    private readonly definitionCache;
+    private readonly skillHotReload;
+    constructor(config?: GraphLoaderConfig);
+    /** 严格预装：禁止用 Registry 拉可执行定义 */
+    private get blockRegistryDefinitions();
+    private resolveVersion;
+    /**
+     * 缓存主键版本：显式 version 优先；未传时落到 snapshot.version，
+     * 避免 warm(`1.0.0`) 与 load(无 version→@auto) 分属两个键。
+     */
+    private pinCacheVersion;
+    private useCache;
+    /** 上线 / 发版后预热进程内定义（模型 C） */
+    warmAgent(agentCode: string, options?: LoadAgentOptions & {
+        userId?: string;
+    }): Promise<{
+        graph: boolean;
+        tools: boolean;
+        skills: boolean;
+        skillWarnings: string[];
+    }>;
+    /** 版本切换 / 下线时失效缓存 */
+    invalidateAgent(agentCode: string, agentVersion?: string): void;
+    invalidateAllDefinitions(): void;
+    definitionCacheSize(): number;
+    private cloneCached;
+    loadGraph(agentCode: string, options?: LoadAgentOptions): Promise<GraphDSL>;
+    private loadGraphFromSource;
+    /**
+     * 解析 agent tools[] + graph tool 节点 union；
+     * server+预装：以预装 manifest 为准；desktop 合并 ILocalToolInstallStore。
+     */
+    loadToolDefinitions(agentCode: string, options?: LoadToolDefinitionsOptions): Promise<LoadedToolDefinition[]>;
+    private loadToolDefinitionsFromSource;
+    /**
+     * 从预装快照加载已装配 Skill 完整定义（workflow / prompt / toolRefs）
+     * @param options.userId 用于解析 users/<userId>/skills（优先于 preinstall/skills）
+     * @param options.allowMissingSkills 缺失时跳过而非抛错（warm 预热用）
+     */
+    loadSkillDefinitions(agentCode: string, options?: LoadAgentOptions & {
+        userId?: string;
+        allowMissingSkills?: boolean;
+        onMissingSkill?: (skillId: string) => void;
+    }): Promise<LoadedSkillInfo[]>;
+    private loadSkillDefinitionsFromSource;
+    private skillTreeStamp;
+    /**
+     * 候选集 = 装配白名单，否则 snapshot/manifest 声明。
+     * 磁盘多出来的未声明目录不进选择清单；正文热加载仍看已装配目录的 mtime。
+     */
+    private resolveSkillRefs;
+    private localSkillRoots;
+    resolveAgentDir(agentCode: string, version?: string): Promise<string | null>;
+    /** Agent 包目录 + 工程 prompts/（dev 作者源，与 EAP_LOCAL_SKILLS_DIR 同级） */
+    resolvePromptRoots(agentCode: string, version?: string): Promise<string[]>;
+}