@gt-fe/eap-runtime 0.0.8

package/dist/registry/index.d.ts

@@ -0,0 +1,9 @@
+export { resolveAgentPrimaryModel, resolveAgentModelAllowlist, resolveDeclaredModels } from './agent-models.js';
+export { createAgentRegistryClient, type AgentRegistryClient, type AgentRegistryRecord, type AgentManifest } from './agent-registry-client.js';
+export { GraphLoader, type GraphLoaderConfig, type LoadToolDefinitionsOptions, type LoadAgentOptions } from './graph-loader.js';
+export { PreinstallDefinitionCache, resolveDefinitionCacheEnabled, type CachedAgentDefinitions, } from './definition-cache.js';
+export { inspectAgentSkillTree, readSkillAssembly, resolveSkillHotReload, skillAssemblyStamp, watchAgentSkillDirs, watchPreinstallSkillRoot, watchSkillRoots, } from './skill-tree.js';
+export { FileSystemDeploymentSnapshot, createDeploymentSnapshotFromEnv, normalizeDigest, isInlineToolDeclaration, overlayToolRefPolicies, type IDeploymentSnapshot, type AgentSnapshotMeta, type SnapshotToolRef, type SnapshotSkillRef, type PreinstallToolManifest, type PreinstallSkillManifest, type DeploymentSnapshotOptions, } from './deployment-snapshot.js';
+export { preloadError, preloadMissing, preloadManifestNotFound, preloadGraphNotFound, preloadToolNotFound, preloadSkillNotFound, preloadPackageCorrupt, isRequireReady, } from './preload-errors.js';
+export { resolvePreloadBehaviorFlags, isValidateSkillIo, isRequireChecksum, type PreloadBehaviorFlags, } from './preload-flags.js';
+export { assertSkillIoIfEnabled, coerceSkillInputFromMessages, resolveSkillInputFromInvokeInput, } from './skill-io-guard.js';

package/dist/registry/index.js

@@ -0,0 +1,9 @@
+export { resolveAgentPrimaryModel, resolveAgentModelAllowlist, resolveDeclaredModels } from './agent-models.js';
+export { createAgentRegistryClient } from './agent-registry-client.js';
+export { GraphLoader } from './graph-loader.js';
+export { PreinstallDefinitionCache, resolveDefinitionCacheEnabled, } from './definition-cache.js';
+export { inspectAgentSkillTree, readSkillAssembly, resolveSkillHotReload, skillAssemblyStamp, watchAgentSkillDirs, watchPreinstallSkillRoot, watchSkillRoots, } from './skill-tree.js';
+export { FileSystemDeploymentSnapshot, createDeploymentSnapshotFromEnv, normalizeDigest, isInlineToolDeclaration, overlayToolRefPolicies, } from './deployment-snapshot.js';
+export { preloadError, preloadMissing, preloadManifestNotFound, preloadGraphNotFound, preloadToolNotFound, preloadSkillNotFound, preloadPackageCorrupt, isRequireReady, } from './preload-errors.js';
+export { resolvePreloadBehaviorFlags, isValidateSkillIo, isRequireChecksum, } from './preload-flags.js';
+export { assertSkillIoIfEnabled, coerceSkillInputFromMessages, resolveSkillInputFromInvokeInput, } from './skill-io-guard.js';

package/dist/registry/preload-errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 预装加载错误 — 对齐 runtime.preload.* / 联调契约
+ */
+import { AppError, type ErrorCode } from '@gt-fe/eap-contracts';
+export declare function preloadError(code: ErrorCode, message: string, details?: unknown): AppError;
+export declare function preloadMissing(message: string, details?: unknown): AppError;
+export declare function preloadManifestNotFound(message: string, details?: unknown): AppError;
+export declare function preloadGraphNotFound(message: string, details?: unknown): AppError;
+export declare function preloadToolNotFound(message: string, details?: unknown): AppError;
+export declare function preloadSkillNotFound(message: string, details?: unknown): AppError;
+export declare function preloadPackageCorrupt(message: string, details?: unknown): AppError;
+/** 是否强制校验 .ready（默认否） */
+export declare function isRequireReady(explicit?: boolean): boolean;

package/dist/registry/preload-errors.js

@@ -0,0 +1,35 @@
+/**
+ * 预装加载错误 — 对齐 runtime.preload.* / 联调契约
+ */
+import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
+export function preloadError(code, message, details) {
+    return new AppError(code, message, {
+        exposeMessage: true,
+        details,
+    });
+}
+export function preloadMissing(message, details) {
+    return preloadError(ErrorCodes.RUNTIME_PRELOAD_MISSING, message, details);
+}
+export function preloadManifestNotFound(message, details) {
+    return preloadError(ErrorCodes.RUNTIME_PRELOAD_MANIFEST_NOT_FOUND, message, details);
+}
+export function preloadGraphNotFound(message, details) {
+    return preloadError(ErrorCodes.RUNTIME_PRELOAD_GRAPH_NOT_FOUND, message, details);
+}
+export function preloadToolNotFound(message, details) {
+    return preloadError(ErrorCodes.RUNTIME_PRELOAD_TOOL_NOT_FOUND, message, details);
+}
+export function preloadSkillNotFound(message, details) {
+    return preloadError(ErrorCodes.RUNTIME_PRELOAD_SKILL_NOT_FOUND, message, details);
+}
+export function preloadPackageCorrupt(message, details) {
+    return preloadError(ErrorCodes.RUNTIME_PRELOAD_PACKAGE_CORRUPT, message, details);
+}
+/** 是否强制校验 .ready（默认否） */
+export function isRequireReady(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const v = process.env.EAP_PRELOAD_REQUIRE_READY;
+    return v === '1' || v === 'true' || v === 'yes';
+}

package/dist/registry/preload-flags.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 预装读侧行为开关（环境变量 / 显式配置）
+ *
+ * | 变量 | 默认 | 含义 |
+ * |------|------|------|
+ * | EAP_PRELOAD_REQUIRE_READY | 关 | 强制校验 .ready |
+ * | EAP_PRELOAD_VALIDATE_SKILL_IO | **开** | 执行子图前校验 skill inputDef.required；`0`/`false` 关闭 |
+ * | EAP_PRELOAD_REQUIRE_CHECKSUM | 关 | snapshot 必须带 sha256 或 artifacts[] |
+ * | EAP_PRELOAD_DEFINITION_CACHE | 有预装时开 | 进程内定义缓存；`0`/`false` 关闭 |
+ * | EAP_SKILL_HOT_RELOAD | **dev 开 / server 关** | 已装配 Skill 的目录 mtime 变化则丢缓存；未写入装配名单的目录不进清单 |
+ * | EAP_LOCAL_SKILLS_DIR | 关 | 开发态作者源 Skill 根；查找优先于 preinstall，低于 users/ |
+ *
+ * Skill 查找优先级固定为：用户装配（users/）> Agent 预装（preinstall/），无开关。
+ */
+export interface PreloadBehaviorFlags {
+    requireReady: boolean;
+    validateSkillIo: boolean;
+    requireChecksum: boolean;
+}
+export declare function resolvePreloadBehaviorFlags(explicit?: Partial<PreloadBehaviorFlags>): PreloadBehaviorFlags;
+export declare function isValidateSkillIo(explicit?: boolean): boolean;
+export declare function isRequireChecksum(explicit?: boolean): boolean;

package/dist/registry/preload-flags.js

@@ -0,0 +1,44 @@
+/**
+ * 预装读侧行为开关（环境变量 / 显式配置）
+ *
+ * | 变量 | 默认 | 含义 |
+ * |------|------|------|
+ * | EAP_PRELOAD_REQUIRE_READY | 关 | 强制校验 .ready |
+ * | EAP_PRELOAD_VALIDATE_SKILL_IO | **开** | 执行子图前校验 skill inputDef.required；`0`/`false` 关闭 |
+ * | EAP_PRELOAD_REQUIRE_CHECKSUM | 关 | snapshot 必须带 sha256 或 artifacts[] |
+ * | EAP_PRELOAD_DEFINITION_CACHE | 有预装时开 | 进程内定义缓存；`0`/`false` 关闭 |
+ * | EAP_SKILL_HOT_RELOAD | **dev 开 / server 关** | 已装配 Skill 的目录 mtime 变化则丢缓存；未写入装配名单的目录不进清单 |
+ * | EAP_LOCAL_SKILLS_DIR | 关 | 开发态作者源 Skill 根；查找优先于 preinstall，低于 users/ |
+ *
+ * Skill 查找优先级固定为：用户装配（users/）> Agent 预装（preinstall/），无开关。
+ */
+function envFlag(name) {
+    const v = process.env[name];
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/** 默认开启；仅当显式设为 0/false/no 时关闭 */
+function envFlagDefaultOn(name) {
+    const v = process.env[name];
+    if (v === undefined || v === '')
+        return true;
+    if (v === '0' || v === 'false' || v === 'no')
+        return false;
+    return v === '1' || v === 'true' || v === 'yes';
+}
+export function resolvePreloadBehaviorFlags(explicit = {}) {
+    return {
+        requireReady: explicit.requireReady !== undefined ? explicit.requireReady : envFlag('EAP_PRELOAD_REQUIRE_READY'),
+        validateSkillIo: explicit.validateSkillIo !== undefined
+            ? explicit.validateSkillIo
+            : envFlagDefaultOn('EAP_PRELOAD_VALIDATE_SKILL_IO'),
+        requireChecksum: explicit.requireChecksum !== undefined
+            ? explicit.requireChecksum
+            : envFlag('EAP_PRELOAD_REQUIRE_CHECKSUM'),
+    };
+}
+export function isValidateSkillIo(explicit) {
+    return resolvePreloadBehaviorFlags(explicit === undefined ? {} : { validateSkillIo: explicit }).validateSkillIo;
+}
+export function isRequireChecksum(explicit) {
+    return resolvePreloadBehaviorFlags(explicit === undefined ? {} : { requireChecksum: explicit }).requireChecksum;
+}

package/dist/registry/skill-io-guard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Skill inputDef / outputDef 轻量校验（默认开启；EAP_PRELOAD_VALIDATE_SKILL_IO=0 关闭）
+ */
+import type { LoadedSkillInfo } from '../tool/system-prompt-builder.js';
+/**
+ * 从 invoke/stream 的 input 解析 `state.skillInput`。
+ * - 对象且含 `skillInput` 对象 → 用嵌套字段
+ * - 普通对象 → 整包作为 skillInput（便于 `{"topic":"…","message":"…"}`）
+ * - JSON 对象字符串（Hosting 常把 body.input 序列化后再传入）→ 按上规则解析
+ * - 非 JSON 纯文本或非法 JSON → `{ text }`；空串 → undefined
+ */
+export declare function resolveSkillInputFromInvokeInput(input: unknown): Record<string, unknown> | undefined;
+/**
+ * 聊天口只补 `text`：最后一条 user 为非 JSON 纯文本，且 required 里缺的唯一字段是 `text`。
+ * `topic` 等其它键不猜；结构化 JSON 缺字段仍校验失败。
+ */
+export declare function coerceSkillInputFromMessages(skill: LoadedSkillInfo, skillInput: unknown, messages: Array<{
+    role?: unknown;
+    content?: unknown;
+}>): Record<string, unknown> | undefined;
+/**
+ * 若开启校验且 skill 声明了 inputDef.required，则要求 state.skillInput 含对应键。
+ * outputDef 仅做形态检查（须为 object schema），执行期出参校验留给后续。
+ */
+export declare function assertSkillIoIfEnabled(skill: LoadedSkillInfo, skillInput: unknown, explicitFlag?: boolean): void;

package/dist/registry/skill-io-guard.js

@@ -0,0 +1,98 @@
+/**
+ * Skill inputDef / outputDef 轻量校验（默认开启；EAP_PRELOAD_VALIDATE_SKILL_IO=0 关闭）
+ */
+import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
+import { isValidateSkillIo } from './preload-flags.js';
+function asRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+/**
+ * 从 invoke/stream 的 input 解析 `state.skillInput`。
+ * - 对象且含 `skillInput` 对象 → 用嵌套字段
+ * - 普通对象 → 整包作为 skillInput（便于 `{"topic":"…","message":"…"}`）
+ * - JSON 对象字符串（Hosting 常把 body.input 序列化后再传入）→ 按上规则解析
+ * - 非 JSON 纯文本或非法 JSON → `{ text }`；空串 → undefined
+ */
+export function resolveSkillInputFromInvokeInput(input) {
+    let value = input;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed)
+            return undefined;
+        if (!((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+            (trimmed.startsWith('[') && trimmed.endsWith(']')))) {
+            return { text: trimmed };
+        }
+        try {
+            value = JSON.parse(trimmed);
+        }
+        catch {
+            return { text: trimmed };
+        }
+    }
+    const rec = asRecord(value);
+    if (!rec)
+        return undefined;
+    const nested = asRecord(rec.skillInput);
+    return nested ?? rec;
+}
+function looksLikeJsonValue(text) {
+    const trimmed = text.trim();
+    return ((trimmed.startsWith('{') && trimmed.endsWith('}')) ||
+        (trimmed.startsWith('[') && trimmed.endsWith(']')));
+}
+/**
+ * 聊天口只补 `text`：最后一条 user 为非 JSON 纯文本，且 required 里缺的唯一字段是 `text`。
+ * `topic` 等其它键不猜；结构化 JSON 缺字段仍校验失败。
+ */
+export function coerceSkillInputFromMessages(skill, skillInput, messages) {
+    const base = asRecord(skillInput) ?? {};
+    const inputDef = asRecord(skill.inputDef);
+    const required = Array.isArray(inputDef?.required)
+        ? inputDef.required.filter((k) => typeof k === 'string' && k.length > 0)
+        : [];
+    const missing = required.filter((key) => base[key] === undefined);
+    if (missing.length !== 1 || missing[0] !== 'text') {
+        return Object.keys(base).length > 0 ? base : asRecord(skillInput) ?? undefined;
+    }
+    let lastUser;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg?.role === 'user' && typeof msg.content === 'string' && msg.content.trim()) {
+            lastUser = msg.content;
+            break;
+        }
+    }
+    if (!lastUser || looksLikeJsonValue(lastUser)) {
+        return Object.keys(base).length > 0 ? base : undefined;
+    }
+    return { ...base, text: lastUser };
+}
+/**
+ * 若开启校验且 skill 声明了 inputDef.required，则要求 state.skillInput 含对应键。
+ * outputDef 仅做形态检查（须为 object schema），执行期出参校验留给后续。
+ */
+export function assertSkillIoIfEnabled(skill, skillInput, explicitFlag) {
+    if (!isValidateSkillIo(explicitFlag))
+        return;
+    const inputDef = asRecord(skill.inputDef);
+    if (inputDef) {
+        const required = inputDef.required;
+        const input = asRecord(skillInput) ?? {};
+        if (Array.isArray(required)) {
+            const missing = required
+                .filter((k) => typeof k === 'string' && k.length > 0)
+                .filter((k) => input[k] === undefined);
+            if (missing.length > 0) {
+                throw new AppError(ErrorCodes.PARAMS_INVALID, `Skill ${skill.skillId} 缺少 inputDef.required 字段: ${missing.join(', ')}`, { exposeMessage: true, details: { skillId: skill.skillId, missing } });
+            }
+        }
+    }
+    const outputDef = skill.outputDef;
+    if (outputDef != null && (typeof outputDef !== 'object' || Array.isArray(outputDef))) {
+        throw new AppError(ErrorCodes.RUNTIME_PRELOAD_PACKAGE_CORRUPT, `Skill ${skill.skillId} outputDef 须为对象 schema`, { exposeMessage: true, details: { skillId: skill.skillId } });
+    }
+}

package/dist/registry/skill-tree.d.ts

@@ -0,0 +1,27 @@
+export interface AgentSkillTree {
+    codes: string[];
+    /** `${count}:${maxMtimeMs}`；增删改任一 skill 文件都会变 */
+    stamp: string;
+}
+export interface SkillAssembly {
+    skills: string[];
+    source: string;
+}
+/**
+ * 装配白名单：users/<id>/.assembly.json → agentDir/.assembly.json → assembly.json
+ * 未声明的磁盘目录不得进入选择清单。
+ */
+export declare function readSkillAssembly(agentDir: string, userId?: string): Promise<SkillAssembly | null>;
+export declare function skillAssemblyStamp(agentDir: string, userId?: string): Promise<string>;
+export declare function preinstallSkillsDir(agentDir: string): string;
+export declare function userSkillsDir(agentDir: string, userId: string): string;
+export declare function inspectAgentSkillTree(agentDir: string, userId?: string, extraRoots?: string[]): Promise<AgentSkillTree>;
+/**
+ * 监听整个预装根下任意 Agent 的 skills 目录（eap chat / createDevRuntime）。
+ * 失败时静默（PVC/NFS 上 watch 不可靠，请求入口仍靠 stamp）。
+ */
+export declare function watchPreinstallSkillRoot(preinstallRoot: string, onChange: () => void, debounceMs?: number): () => void;
+export declare function watchSkillRoots(roots: string[], onChange: () => void, debounceMs?: number): () => void;
+export declare function watchAgentSkillDirs(agentDir: string, onChange: () => void, debounceMs?: number, extraRoots?: string[]): () => void;
+/** EAP_SKILL_HOT_RELOAD：dev 默认开；server/desktop 默认关 */
+export declare function resolveSkillHotReload(deploymentContext: string, explicit?: boolean): boolean;

package/dist/registry/skill-tree.js

@@ -0,0 +1,183 @@
+/**
+ * Agent 自带 Skill 目录扫描（§3.1）
+ *
+ *   agents/<code>/<ver>/preinstall/skills/<skillCode>/
+ *   agents/<code>/<ver>/users/<userId>/skills/<skillCode>/   同名覆盖
+ *
+ * 热加载用 stamp：目录/文件 mtime 变化则缓存失效。
+ */
+import { readdir, stat, access, readFile } from 'node:fs/promises';
+import { watch } from 'node:fs';
+import { constants as fsConstants } from 'node:fs';
+import path from 'node:path';
+const SKILL_CODE = /^[a-z0-9][a-z0-9-]*$/;
+async function exists(p) {
+    try {
+        await access(p, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function maxMtime(filePath, fallback = 0) {
+    try {
+        const info = await stat(filePath);
+        return info.mtimeMs;
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * 装配白名单：users/<id>/.assembly.json → agentDir/.assembly.json → assembly.json
+ * 未声明的磁盘目录不得进入选择清单。
+ */
+export async function readSkillAssembly(agentDir, userId) {
+    const candidates = [];
+    const uid = userId?.trim();
+    if (uid)
+        candidates.push(path.join(agentDir, 'users', uid, '.assembly.json'));
+    candidates.push(path.join(agentDir, '.assembly.json'), path.join(agentDir, 'assembly.json'));
+    for (const file of candidates) {
+        const parsed = await readAssemblyFile(file);
+        if (parsed)
+            return parsed;
+    }
+    return null;
+}
+async function readAssemblyFile(file) {
+    try {
+        const raw = JSON.parse(await readFile(file, 'utf8'));
+        if (!Array.isArray(raw.skills))
+            return null;
+        const skills = raw.skills
+            .filter((item) => typeof item === 'string' && SKILL_CODE.test(item))
+            .filter((item, index, all) => all.indexOf(item) === index);
+        return { skills, source: file };
+    }
+    catch {
+        return null;
+    }
+}
+export async function skillAssemblyStamp(agentDir, userId) {
+    const candidates = [];
+    const uid = userId?.trim();
+    if (uid)
+        candidates.push(path.join(agentDir, 'users', uid, '.assembly.json'));
+    candidates.push(path.join(agentDir, '.assembly.json'), path.join(agentDir, 'assembly.json'));
+    let latest = 0;
+    for (const file of candidates) {
+        latest = Math.max(latest, await maxMtime(file, 0));
+    }
+    return String(Math.floor(latest));
+}
+export function preinstallSkillsDir(agentDir) {
+    return path.join(agentDir, 'preinstall', 'skills');
+}
+export function userSkillsDir(agentDir, userId) {
+    return path.join(agentDir, 'users', userId, 'skills');
+}
+export async function inspectAgentSkillTree(agentDir, userId, extraRoots = []) {
+    const roots = [preinstallSkillsDir(agentDir), ...extraRoots.filter(Boolean)];
+    const uid = userId?.trim();
+    if (uid)
+        roots.push(userSkillsDir(agentDir, uid));
+    const codes = new Set();
+    let latest = 0;
+    for (const root of roots) {
+        latest = Math.max(latest, await maxMtime(root, 0));
+        let names = [];
+        try {
+            names = await readdir(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (!SKILL_CODE.test(name))
+                continue;
+            const bundle = path.join(root, name);
+            const bundleStat = await stat(bundle).catch(() => undefined);
+            if (!bundleStat?.isDirectory())
+                continue;
+            const hasMain = (await exists(path.join(bundle, 'skill.md'))) ||
+                (await exists(path.join(bundle, 'skill.manifest.json')));
+            if (!hasMain)
+                continue;
+            codes.add(name);
+            latest = Math.max(latest, bundleStat.mtimeMs);
+            const files = await readdir(bundle).catch(() => []);
+            for (const file of files) {
+                latest = Math.max(latest, await maxMtime(path.join(bundle, file), 0));
+            }
+        }
+    }
+    const sorted = [...codes].sort();
+    return { codes: sorted, stamp: `${sorted.length}:${Math.floor(latest)}` };
+}
+/**
+ * 监听整个预装根下任意 Agent 的 skills 目录（eap chat / createDevRuntime）。
+ * 失败时静默（PVC/NFS 上 watch 不可靠，请求入口仍靠 stamp）。
+ */
+export function watchPreinstallSkillRoot(preinstallRoot, onChange, debounceMs = 200) {
+    const agentsRoot = path.join(preinstallRoot, 'agents');
+    let timer;
+    const fire = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(onChange, debounceMs);
+    };
+    try {
+        const watcher = watch(agentsRoot, { recursive: true, persistent: false }, (_event, filename) => {
+            const norm = String(filename ?? '').replace(/\\/g, '/');
+            if (!norm || norm.includes('/skills/') || /(^|\/)skills$/.test(norm))
+                fire();
+        });
+        return () => {
+            if (timer)
+                clearTimeout(timer);
+            watcher.close();
+        };
+    }
+    catch {
+        return () => { };
+    }
+}
+export function watchSkillRoots(roots, onChange, debounceMs = 200) {
+    const watchers = [];
+    let timer;
+    const fire = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(onChange, debounceMs);
+    };
+    for (const target of roots.filter(Boolean)) {
+        try {
+            watchers.push(watch(target, { recursive: true, persistent: false }, fire));
+        }
+        catch {
+            // ignore missing dir / unsupported recursive watch
+        }
+    }
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        for (const watcher of watchers)
+            watcher.close();
+    };
+}
+export function watchAgentSkillDirs(agentDir, onChange, debounceMs = 200, extraRoots = []) {
+    return watchSkillRoots([preinstallSkillsDir(agentDir), path.join(agentDir, 'users'), ...extraRoots], onChange, debounceMs);
+}
+/** EAP_SKILL_HOT_RELOAD：dev 默认开；server/desktop 默认关 */
+export function resolveSkillHotReload(deploymentContext, explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    const v = process.env.EAP_SKILL_HOT_RELOAD;
+    if (v === '0' || v === 'false' || v === 'no')
+        return false;
+    if (v === '1' || v === 'true' || v === 'yes')
+        return true;
+    return deploymentContext === 'dev';
+}

package/dist/runtime/agent-runtime.d.ts

@@ -0,0 +1,106 @@
+/**
+ * AgentRuntime — Runtime SDK 门面
+ *
+ * Hosting 内嵌调用入口：execute / stream / resumeHitl / fork。
+ * 对外 HTTP 由 Hosting 提供；本地 eap dev 亦可直接实例化本类。
+ *
+ * @see 04-runtime-core/design.md §1.5 / §1.7
+ */
+import type { InvokeOrchestrator } from '../api/handlers/invoke.handler.js';
+import type { ICheckpointSaver } from '../checkpoint/contracts/checkpoint-saver.contract.js';
+import type { ITraceCollector } from '../contracts/trace-collector.js';
+import type { IStateGraphEngine } from '../graph/contracts/state-graph.contract.js';
+import { HitlHandler } from '../graph/hitl/hitl-handler.js';
+import type { GraphLoader } from '../registry/graph-loader.js';
+import type { SessionContextService } from '../session/session-context.service.js';
+import type { MessageService } from '../session/message.service.js';
+import type { SSEEvent } from '../sse/contracts/sse-emitter.contract.js';
+import type { TaskService } from '../task/task.service.js';
+import type { ExecuteParams, ExecuteResult, ForkOverrides, ForkResult, HitlResponse, ResumeHitlResult, SeedSessionMessagesParams, SeedSessionMessagesResult } from './types.js';
+export interface ForkRelationRecord {
+    originalTraceId: string;
+    forkedTraceId: string;
+    checkpointId: string;
+    overrides?: ForkOverrides;
+}
+export type RecordForkRelation = (record: ForkRelationRecord) => Promise<void>;
+export interface AgentRuntimeDeps {
+    invokeOrchestrator: InvokeOrchestrator;
+    sessionContextService: SessionContextService;
+    taskService: TaskService;
+    graphEngine: IStateGraphEngine;
+    checkpointSaver: ICheckpointSaver;
+    hitlHandler: HitlHandler;
+    graphLoader?: GraphLoader;
+    /** 多轮短期记忆写回；未注入时 AgentRuntime.stream 跳过持久化 */
+    messageService?: MessageService;
+    /**
+     * Hosting 注入的 Trace 采集器。与 ExecuteParams.traceId 同时存在时，
+     * Skill/Tool 节点会 createNode/completeNode。不注入则只发 SSE，不写 Span。
+     */
+    traceCollector?: ITraceCollector;
+    recordForkRelation?: RecordForkRelation;
+}
+/**
+ * AgentRuntime — 管理 Graph 执行的 SDK 门面
+ */
+export declare class AgentRuntime {
+    private readonly deps;
+    constructor(deps: AgentRuntimeDeps);
+    /** 从 GraphLoader 解析 tool manifest 映射（invoke/stream/resume/fork 共用） */
+    private resolveLoadedTools;
+    /** 从预装重载 Skill 定义（HITL/Fork 时 ephemeral 字段可能丢失） */
+    private resolveLoadedSkills;
+    /**
+     * 向会话预置种子消息（开发者 few-shot / 开场白）
+     *
+     * 专为 SDK `createAgentService({ messages })` 提供：在首条真实用户输入之前
+     * 一次性将开发者提供的对话上下文写入 session，后续 execute/stream 直接沿用现有
+     * “Session 历史 + 当前输入”途径。
+     *
+     * 行为：
+     * - `role` 仅接受 `user` / `assistant`；`system` 应写入 graph.json LLM 节点的
+     *   `config.systemPrompt`（由 SystemPromptBuilder 拼平台规则 + 开发者提示词）；
+     *   `tool` 必须与前置 assistant.toolCalls 严格配对，不得单独作为种子。
+     * - 幂等语义（exactly-once）：当 session 已存在任何历史消息时，直接返回
+     *   `seeded: false`，不重复写入。
+     *
+     * @throws PARAMS_INVALID messages 为空、role 不在白名单、content 非字符串或为空
+     * @throws PARAMS_INVALID messageService 未注入（无存储无法写入）
+     */
+    seedSessionMessages(params: SeedSessionMessagesParams): Promise<SeedSessionMessagesResult>;
+    /** 同步执行 Graph（经 InvokeOrchestrator，内含 loadedTools 注入） */
+    execute(params: ExecuteParams): Promise<ExecuteResult>;
+    /**
+     * 流式执行 Graph，产出 SSE 事件序列
+     */
+    stream(params: ExecuteParams): AsyncIterable<SSEEvent>;
+    /**
+     * HITL 用户响应后继续执行（同步结果）。
+     *
+     * 内部消费 `streamResumeHitl`：成功为 success；再次确认暂停为 waiting_hitl（不抛错）。
+     * 需要过程事件（`hitl.resumed` / `tool.result` / `skill.completed`）时请直接迭代 streamResumeHitl。
+     */
+    resumeHitl(taskId: string, response: HitlResponse): Promise<ResumeHitlResult>;
+    /**
+     * HITL 恢复的流式入口：新开一条 SSE（第一条 stream 在 `hitl.waited` 后已结束）。
+     *
+     * 事件顺序：`hitl.resumed` → 图内 `tool.*` / `skill.*` / `response.*` → `task.completed`
+     * 或再次 `hitl.waited`。拒绝/失败会发出同 `toolCallId` 的 `tool.error`。
+     *
+     * 从 GraphLoader `buildGraph` + Checkpoint GraphState 续跑，不用空的 `restore()`。
+     */
+    streamResumeHitl(taskId: string, response: HitlResponse): AsyncIterable<SSEEvent>;
+    /**
+     * 从 Checkpoint Fork 并真实重新执行
+     */
+    fork(checkpointId: string, overrides?: ForkOverrides): Promise<ForkResult>;
+    private prepareHitlResume;
+    private rebuildExecutableGraph;
+    private handleHitlTimeout;
+    private finalizeHitlTimeout;
+    private toSSE;
+    private runtimeEventToSSE;
+}
+/** 工厂：从运行时依赖组装 AgentRuntime */
+export declare function createAgentRuntime(deps: AgentRuntimeDeps): AgentRuntime;