@gt-fe/eap-runtime 0.0.8

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

@@ -0,0 +1,69 @@
+/**
+ * createDevRuntime — 本地 dev 模式 Runtime SDK 装配工厂
+ *
+ * 将 server.ts 里的依赖注入装配逻辑抽成纯函数，让 CLI / 测试 / 宿主服务
+ * 可以**进程内嵌**调用 AgentRuntime.execute / stream，无需起 HTTP。
+ *
+ * 典型用法（dev-tools/packages/cli/src/commands/chat.ts --sdk 模式）：
+ *
+ * ```ts
+ * import { createDevRuntime } from '@eap/runtime';
+ *
+ * const rt = createDevRuntime();
+ * const result = await rt.invokeOrchestrator.execute(
+ *   { agentCode, input, sessionId, userId },
+ *   userId,
+ * );
+ * ```
+ *
+ * 装配策略（与 server.ts 一致）：
+ * - LLM Provider: Routing > HttpLLMProvider(OpenAI) > Echo 兜底
+ * - Tool Executor: mock（显式）/ DevToolExecutor（dev+mcp，缺配置失败）/ 通用路由
+ * - Governance: AllowAll(本地闭环默认) / HttpGovernance(显式 GOVERNANCE_DISABLED=0)
+ * - 存储: EAP_RUNTIME_STORAGE_PROFILE（默认 dev = File Session/Message/Checkpoint）
+ * - Registry: 本地闭环不装配，由 GraphLoader.deploymentSnapshot 兜底
+ */
+import { InvokeOrchestrator, StreamOrchestrator, SessionService, MessageService, SessionContextService, TaskService, TokenStatsService, GraphLoader } from '../index.js';
+import { type AgentRuntime } from './agent-runtime.js';
+import type { RuntimeStorageProfile } from './storage-profile.js';
+import type { HitlResponse, ResumeHitlResult, SSEEvent } from './types.js';
+/** createDevRuntime 返回值（CLI 嵌入用，可选字段后续扩展） */
+export interface DevRuntime {
+    invokeOrchestrator: InvokeOrchestrator;
+    streamOrchestrator: StreamOrchestrator;
+    /** SDK 门面：execute / stream / resumeHitl / fork */
+    agentRuntime: AgentRuntime;
+    /** 与 Graph 共用同一 HitlHandler 实例（等待态可 resume） */
+    resumeHitl: (taskId: string, response: HitlResponse) => Promise<ResumeHitlResult>;
+    /** HITL 恢复流式入口：新开一条 SSE（第一条 stream 已在 hitl.waited 结束） */
+    streamResumeHitl: (taskId: string, response: HitlResponse) => AsyncIterable<SSEEvent>;
+    sessionService: SessionService;
+    messageService: MessageService;
+    sessionContextService: SessionContextService;
+    taskService: TaskService;
+    tokenStatsService: TokenStatsService;
+    graphLoader: GraphLoader;
+    /** 停止 Skill 目录 watch；未开启热加载时为 no-op */
+    dispose: () => void;
+    /** 装配期诊断摘要（CLI 启动时打印，便于排查环境问题） */
+    diagnostics: {
+        deploymentContext: string;
+        toolExecutionMode: string;
+        llmProviderKind: 'routing' | 'openai-http' | 'echo';
+        llmDefaultModel: string;
+        governanceKind: 'AllowAll' | 'Http';
+        storageProfile: RuntimeStorageProfile;
+        sessionStoreKind: 'file' | 'in-memory';
+        messageStoreKind: 'memory' | 'file' | 'postgres';
+        checkpointKind: 'memory' | 'file' | 'redis+pg' | 'pg';
+        foundationConfigured: boolean;
+        skillHotReload: boolean;
+    };
+}
+/**
+ * 装配本地 dev 模式所需的全部 Runtime 依赖
+ *
+ * @returns DevRuntime（含 invokeOrchestrator / streamOrchestrator / 诊断摘要）
+ * @throws EAP_LLM_MODE=local 但解不出任何密钥时抛错，避免静默 Echo
+ */
+export declare function createDevRuntime(): DevRuntime;

package/dist/runtime/dev-runtime.js

@@ -0,0 +1,199 @@
+/**
+ * createDevRuntime — 本地 dev 模式 Runtime SDK 装配工厂
+ *
+ * 将 server.ts 里的依赖注入装配逻辑抽成纯函数，让 CLI / 测试 / 宿主服务
+ * 可以**进程内嵌**调用 AgentRuntime.execute / stream，无需起 HTTP。
+ *
+ * 典型用法（dev-tools/packages/cli/src/commands/chat.ts --sdk 模式）：
+ *
+ * ```ts
+ * import { createDevRuntime } from '@eap/runtime';
+ *
+ * const rt = createDevRuntime();
+ * const result = await rt.invokeOrchestrator.execute(
+ *   { agentCode, input, sessionId, userId },
+ *   userId,
+ * );
+ * ```
+ *
+ * 装配策略（与 server.ts 一致）：
+ * - LLM Provider: Routing > HttpLLMProvider(OpenAI) > Echo 兜底
+ * - Tool Executor: mock（显式）/ DevToolExecutor（dev+mcp，缺配置失败）/ 通用路由
+ * - Governance: AllowAll(本地闭环默认) / HttpGovernance(显式 GOVERNANCE_DISABLED=0)
+ * - 存储: EAP_RUNTIME_STORAGE_PROFILE（默认 dev = File Session/Message/Checkpoint）
+ * - Registry: 本地闭环不装配，由 GraphLoader.deploymentSnapshot 兜底
+ */
+import { createDefaultLLMProvider } from '../providers/echo-llm-provider.js';
+import { HttpLLMProvider } from '../providers/http-llm-provider.js';
+import { createLocalLlmProvider, requireLocalLlmConnections } from '../providers/local-llm-provider.js';
+import { RoutingLLMProvider } from '../providers/routing-llm-provider.js';
+import { createToolExecutor } from '../tool/create-tool-executor.js';
+import { MockToolExecutor } from '../tool/mock-tool-executor.js';
+import { DevToolExecutor } from '../tool/dev-tool-executor.js';
+import { AllowAllGovernanceClient, HttpGovernanceClient, } from '../governance/index.js';
+import { InvokeOrchestrator, StreamOrchestrator, SessionService, MessageService, SessionContextService, TaskService, LangGraphAdapter, HitlHandler, TokenBudgetService, InMemoryTokenBudgetRepository, TokenStatsService, TokenBudgetGuard, SessionBudgetChecker, createAgentRegistryClient, GraphLoader, } from '../index.js';
+import { createAgentRuntime } from './agent-runtime.js';
+import { assembleRuntimeStorage } from './storage-profile.js';
+import { resolveSkillHotReload, watchPreinstallSkillRoot, watchSkillRoots } from '../registry/skill-tree.js';
+/**
+ * 装配本地 dev 模式所需的全部 Runtime 依赖
+ *
+ * @returns DevRuntime（含 invokeOrchestrator / streamOrchestrator / 诊断摘要）
+ * @throws EAP_LLM_MODE=local 但解不出任何密钥时抛错，避免静默 Echo
+ */
+export function createDevRuntime() {
+    const foundationUrl = process.env.FOUNDATION_SERVICE_URL ?? 'http://localhost:3100';
+    const foundationConfigured = Boolean(process.env.FOUNDATION_SERVICE_URL && process.env.FOUNDATION_SERVICE_URL.trim().length > 0);
+    const toolExecutionMode = (process.env.EAP_TOOL_EXECUTION_MODE ?? 'mcp').toLowerCase();
+    const deploymentContext = process.env.EAP_DEPLOYMENT_CONTEXT ?? 'server';
+    // ── 存储 profile（默认 dev：File Session/Message/Checkpoint）──
+    // 兼容旧变量：EAP_SESSION_STORE=memory → 强制 test（全内存）
+    const legacySessionStore = process.env.EAP_SESSION_STORE?.toLowerCase();
+    const storage = assembleRuntimeStorage({
+        defaultProfile: legacySessionStore === 'memory' || legacySessionStore === 'in-memory' ? 'test' : 'dev',
+        profile: legacySessionStore === 'memory' || legacySessionStore === 'in-memory'
+            ? 'test'
+            : undefined,
+    });
+    // ── LLM Provider（本地 eap.config runtime.llm 优先，再 Foundation 路由，再环境直连）──
+    let llmProviderKind;
+    let llmProvider;
+    const localLlm = process.env.EAP_LLM_MODE === 'local';
+    if (localLlm || (!foundationConfigured && process.env.OPENAI_API_KEY)) {
+        llmProvider = localLlm
+            ? createLocalLlmProvider(requireLocalLlmConnections())
+            : new HttpLLMProvider({
+                apiKey: process.env.OPENAI_API_KEY ?? '',
+                baseUrl: process.env.OPENAI_BASE_URL,
+                defaultModel: process.env.EAP_DEFAULT_MODEL,
+            });
+        llmProviderKind = 'openai-http';
+    }
+    else if (foundationConfigured) {
+        llmProvider = new RoutingLLMProvider({ foundationUrl });
+        llmProviderKind = 'routing';
+    }
+    else {
+        llmProvider = createDefaultLLMProvider();
+        llmProviderKind = 'echo';
+    }
+    // ── Tool Executor（显式 mock → dev+mcp 直连，缺配置失败 → 通用路由）──
+    const toolExecutor = toolExecutionMode === 'mock'
+        ? new MockToolExecutor({ toolsDir: process.env.EAP_LOCAL_TOOLS_DIR })
+        : toolExecutionMode === 'mcp' && deploymentContext === 'dev'
+            ? new DevToolExecutor()
+            : createToolExecutor({ foundationUrl, deploymentContext });
+    // ── Governance ──
+    const governanceClient = process.env.GOVERNANCE_DISABLED === '1' || !foundationConfigured
+        ? new AllowAllGovernanceClient()
+        : new HttpGovernanceClient({ baseUrl: foundationUrl });
+    const hitlHandler = new HitlHandler(storage.checkpointSaver, {
+        emit: () => { },
+        close: () => { },
+        heartbeat: () => { },
+    });
+    const graphEngine = new LangGraphAdapter(storage.checkpointSaver, llmProvider, toolExecutor, governanceClient, hitlHandler);
+    // ── Session / Messages ──
+    const sessionService = new SessionService(storage.sessionRepository);
+    const messageService = new MessageService(storage.messageRepository);
+    const sessionContextService = new SessionContextService(sessionService, messageService);
+    // ── Task / Token ──
+    const taskService = new TaskService();
+    const budgetService = new TokenBudgetService(new InMemoryTokenBudgetRepository());
+    const tokenStatsService = new TokenStatsService();
+    const tokenBudgetGuard = new TokenBudgetGuard(budgetService);
+    const sessionBudgetChecker = new SessionBudgetChecker(budgetService);
+    // ── Registry / GraphLoader ──
+    const registryClient = foundationConfigured
+        ? createAgentRegistryClient({ baseUrl: foundationUrl })
+        : undefined;
+    const skillHotReload = resolveSkillHotReload(deploymentContext);
+    const preinstallRoot = process.env.EAP_PREINSTALL_ROOT;
+    const localSkillsDir = process.env.EAP_LOCAL_SKILLS_DIR;
+    const graphLoader = new GraphLoader({
+        registryClient,
+        deploymentContext,
+        localToolsDir: process.env.EAP_LOCAL_TOOLS_DIR,
+        localSkillsDir,
+        preinstallRoot,
+        skillHotReload,
+    });
+    const stopSkillWatch = skillHotReload
+        ? (() => {
+            const stopPreinstall = preinstallRoot
+                ? watchPreinstallSkillRoot(preinstallRoot, () => {
+                    graphLoader.invalidateAllDefinitions();
+                })
+                : () => { };
+            const stopAuthor = localSkillsDir
+                ? watchSkillRoots([localSkillsDir], () => {
+                    graphLoader.invalidateAllDefinitions();
+                })
+                : () => { };
+            return () => {
+                stopPreinstall();
+                stopAuthor();
+            };
+        })()
+        : () => { };
+    // ── Orchestrators ──
+    const invokeOrchestrator = new InvokeOrchestrator({
+        sessionContextService,
+        taskService,
+        graphEngine,
+        tokenStatsService,
+        tokenBudgetGuard,
+        sessionBudgetChecker,
+        messageService,
+        graphLoader,
+        checkpointSaver: storage.checkpointSaver,
+    });
+    const streamOrchestrator = new StreamOrchestrator({
+        sessionContextService,
+        taskService,
+        graphEngine,
+        tokenStatsService,
+        tokenBudgetGuard,
+        sessionBudgetChecker,
+        messageService,
+        graphLoader,
+        checkpointSaver: storage.checkpointSaver,
+    });
+    const agentRuntime = createAgentRuntime({
+        invokeOrchestrator,
+        sessionContextService,
+        taskService,
+        graphEngine,
+        checkpointSaver: storage.checkpointSaver,
+        hitlHandler,
+        graphLoader,
+        messageService,
+    });
+    return {
+        invokeOrchestrator,
+        streamOrchestrator,
+        agentRuntime,
+        resumeHitl: (taskId, response) => agentRuntime.resumeHitl(taskId, response),
+        streamResumeHitl: (taskId, response) => agentRuntime.streamResumeHitl(taskId, response),
+        sessionService,
+        messageService,
+        sessionContextService,
+        taskService,
+        tokenStatsService,
+        graphLoader,
+        dispose: stopSkillWatch,
+        diagnostics: {
+            deploymentContext,
+            toolExecutionMode,
+            llmProviderKind,
+            llmDefaultModel: process.env.EAP_DEFAULT_MODEL ?? 'DeepSeek-V4-Pro',
+            governanceKind: governanceClient instanceof AllowAllGovernanceClient ? 'AllowAll' : 'Http',
+            storageProfile: storage.profile,
+            sessionStoreKind: storage.diagnostics.sessionKind === 'file' ? 'file' : 'in-memory',
+            messageStoreKind: storage.diagnostics.messageKind,
+            checkpointKind: storage.diagnostics.checkpointKind,
+            foundationConfigured,
+            skillHotReload,
+        },
+    };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,4 @@
+export { AgentRuntime, createAgentRuntime, type AgentRuntimeDeps, type ForkRelationRecord, type RecordForkRelation, } from './agent-runtime.js';
+export type { ExecuteParams, ExecuteResult, ForkOverrides, ForkResult, HitlResponse, ResumeHitlResult, SSEEvent, } from './types.js';
+export { createDevRuntime, type DevRuntime, } from './dev-runtime.js';
+export { assembleRuntimeStorage, resolveRuntimeStorageProfile, type RuntimeStorageProfile, type AssembleRuntimeStorageOptions, type AssembledRuntimeStorage, } from './storage-profile.js';

package/dist/runtime/index.js

@@ -0,0 +1,3 @@
+export { AgentRuntime, createAgentRuntime, } from './agent-runtime.js';
+export { createDevRuntime, } from './dev-runtime.js';
+export { assembleRuntimeStorage, resolveRuntimeStorageProfile, } from './storage-profile.js';

package/dist/runtime/storage-profile.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Runtime 存储装配（EAP_RUNTIME_STORAGE_PROFILE）
+ *
+ * @see docs/governance/governance-env-config.md §9
+ * @see docs/architecture/storage-decisions.md — messages.session_id → hosting.sessions.id；不单独建 Runtime sessions 表
+ */
+import { Redis } from 'ioredis';
+import type { ICheckpointSaver } from '../checkpoint/contracts/checkpoint-saver.contract.js';
+import { type IPgPool } from '../checkpoint/pg-checkpoint-saver.js';
+import type { ISessionRepository } from '../session/session.service.js';
+import type { IFullMessageRepository } from '../session/message.service.js';
+export type RuntimeStorageProfile = 'test' | 'dev' | 'integration' | 'production';
+export interface AssembleRuntimeStorageOptions {
+    /** 显式 profile；缺省读 EAP_RUNTIME_STORAGE_PROFILE */
+    profile?: RuntimeStorageProfile;
+    /** 未指定 profile 时的默认值（dev-runtime → dev；embedded → integration） */
+    defaultProfile: RuntimeStorageProfile;
+    /** File Checkpoint / Session / Message 根目录 */
+    checkpointDir?: string;
+    sessionDir?: string;
+    messageDir?: string;
+    /** 注入已有连接（Hosting 复用）；未注入时 integration/production 自建 */
+    pgPool?: IPgPool;
+    redis?: Redis;
+    /** Redis key 前缀 */
+    redisKeyPrefix?: string;
+}
+export interface AssembledRuntimeStorage {
+    profile: RuntimeStorageProfile;
+    checkpointSaver: ICheckpointSaver;
+    /** undefined = SessionService 默认 InMemory */
+    sessionRepository?: ISessionRepository;
+    messageRepository: IFullMessageRepository;
+    diagnostics: {
+        profile: RuntimeStorageProfile;
+        checkpointKind: 'memory' | 'file' | 'redis+pg' | 'pg';
+        sessionKind: 'memory' | 'file';
+        messageKind: 'memory' | 'file' | 'postgres';
+    };
+}
+export declare function resolveRuntimeStorageProfile(explicit: RuntimeStorageProfile | undefined, defaultProfile: RuntimeStorageProfile, env?: NodeJS.ProcessEnv): RuntimeStorageProfile;
+/**
+ * 按 profile 装配 Checkpoint / Session / Message 存储
+ *
+ * - test: 全内存
+ * - dev: File Checkpoint + File Session + File Message
+ * - integration/production: Message=PG；Checkpoint=Redis 热 + PG 备；
+ *   Session 仓储不落 PG（sessionId 权威在 Hosting.sessions，Runtime 内存采纳）
+ */
+export declare function assembleRuntimeStorage(options: AssembleRuntimeStorageOptions, env?: NodeJS.ProcessEnv): AssembledRuntimeStorage;

package/dist/runtime/storage-profile.js

@@ -0,0 +1,138 @@
+/**
+ * Runtime 存储装配（EAP_RUNTIME_STORAGE_PROFILE）
+ *
+ * @see docs/governance/governance-env-config.md §9
+ * @see docs/architecture/storage-decisions.md — messages.session_id → hosting.sessions.id；不单独建 Runtime sessions 表
+ */
+// @ts-expect-error pg 无内置类型；Hosting 侧同样按 any 使用
+import pg from 'pg';
+import { Redis } from 'ioredis';
+import { FileCheckpointSaver } from '../checkpoint/file-checkpoint-saver.js';
+import { PostgresCheckpointSaver } from '../checkpoint/pg-checkpoint-saver.js';
+import { RedisCheckpointSaver } from '../checkpoint/redis-checkpoint-saver.js';
+import { CompositeCheckpointSaver } from '../checkpoint/composite-checkpoint-saver.js';
+import { InMemoryCheckpointSaver } from '../checkpoint/in-memory-checkpoint-saver.js';
+import { FileSessionRepository } from '../session/file-session.repository.js';
+import { InMemoryFullMessageRepository } from '../session/message.service.js';
+import { FileMessageRepository } from '../session/file-message.repository.js';
+import { PostgresMessageRepository } from '../session/pg-message.repository.js';
+const { Pool } = pg;
+const VALID_PROFILES = new Set([
+    'test',
+    'dev',
+    'integration',
+    'production',
+]);
+export function resolveRuntimeStorageProfile(explicit, defaultProfile, env = process.env) {
+    const raw = explicit ?? env.EAP_RUNTIME_STORAGE_PROFILE;
+    if (raw && VALID_PROFILES.has(raw)) {
+        return raw;
+    }
+    return defaultProfile;
+}
+function requireDbEnv(env) {
+    const missing = [];
+    if (!env.DB_HOST && !env.DATABASE_URL)
+        missing.push('DB_HOST 或 DATABASE_URL');
+    if (!env.DB_NAME && !env.DATABASE_URL)
+        missing.push('DB_NAME 或 DATABASE_URL');
+    if (!env.DB_USER && !env.DATABASE_URL)
+        missing.push('DB_USER 或 DATABASE_URL');
+    if (missing.length > 0) {
+        throw new Error(`[EAP_RUNTIME_STORAGE_PROFILE] integration/production 缺少数据库配置: ${missing.join(', ')}`);
+    }
+}
+function requireRedisEnv(env) {
+    if (!env.REDIS_HOST && !env.REDIS_URL) {
+        throw new Error('[EAP_RUNTIME_STORAGE_PROFILE] integration/production 缺少 REDIS_HOST 或 REDIS_URL（禁止回退 File Checkpoint）');
+    }
+}
+function createPgPoolFromEnv(env) {
+    if (env.DATABASE_URL) {
+        return new Pool({ connectionString: env.DATABASE_URL });
+    }
+    return new Pool({
+        host: env.DB_HOST ?? 'localhost',
+        port: parseInt(env.DB_PORT ?? '5432', 10),
+        database: env.DB_NAME ?? 'eap_hosting',
+        user: env.DB_USER ?? 'postgres',
+        password: env.DB_PASSWORD ?? '',
+        max: 10,
+    });
+}
+function createRedisFromEnv(env) {
+    if (env.REDIS_URL) {
+        return new Redis(env.REDIS_URL);
+    }
+    const password = env.REDIS_PASSWORD || undefined;
+    return new Redis({
+        host: env.REDIS_HOST ?? 'localhost',
+        port: parseInt(env.REDIS_PORT ?? '6379', 10),
+        password,
+        db: parseInt(env.REDIS_DB ?? '0', 10),
+        maxRetriesPerRequest: 1,
+    });
+}
+/**
+ * 按 profile 装配 Checkpoint / Session / Message 存储
+ *
+ * - test: 全内存
+ * - dev: File Checkpoint + File Session + File Message
+ * - integration/production: Message=PG；Checkpoint=Redis 热 + PG 备；
+ *   Session 仓储不落 PG（sessionId 权威在 Hosting.sessions，Runtime 内存采纳）
+ */
+export function assembleRuntimeStorage(options, env = process.env) {
+    const profile = resolveRuntimeStorageProfile(options.profile, options.defaultProfile, env);
+    const checkpointDir = options.checkpointDir ?? env.EAP_CHECKPOINT_DIR ?? '/tmp/eap-checkpoints';
+    const sessionDir = options.sessionDir ?? env.EAP_SESSION_DIR ?? '/tmp/eap-sessions';
+    const messageDir = options.messageDir ?? env.EAP_MESSAGE_DIR ?? `${sessionDir.replace(/\/$/, '')}/messages`;
+    if (profile === 'test') {
+        return {
+            profile,
+            checkpointSaver: new InMemoryCheckpointSaver(),
+            sessionRepository: undefined,
+            messageRepository: new InMemoryFullMessageRepository(),
+            diagnostics: {
+                profile,
+                checkpointKind: 'memory',
+                sessionKind: 'memory',
+                messageKind: 'memory',
+            },
+        };
+    }
+    if (profile === 'dev') {
+        return {
+            profile,
+            checkpointSaver: new FileCheckpointSaver(checkpointDir),
+            sessionRepository: new FileSessionRepository({ baseDir: sessionDir }),
+            messageRepository: new FileMessageRepository({ baseDir: messageDir }),
+            diagnostics: {
+                profile,
+                checkpointKind: 'file',
+                sessionKind: 'file',
+                messageKind: 'file',
+            },
+        };
+    }
+    requireDbEnv(env);
+    requireRedisEnv(env);
+    const pool = options.pgPool ?? createPgPoolFromEnv(env);
+    const redis = options.redis ?? createRedisFromEnv(env);
+    const pgSaver = new PostgresCheckpointSaver(pool);
+    const redisSaver = new RedisCheckpointSaver(redis, {
+        keyPrefix: options.redisKeyPrefix ?? env.REDIS_KEY_PREFIX ?? 'eap:rt:',
+    });
+    const checkpointSaver = new CompositeCheckpointSaver(pgSaver, redisSaver);
+    return {
+        profile,
+        checkpointSaver,
+        sessionRepository: undefined,
+        messageRepository: new PostgresMessageRepository(pool),
+        diagnostics: {
+            profile,
+            checkpointKind: 'redis+pg',
+            sessionKind: 'memory',
+            messageKind: 'postgres',
+        },
+    };
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,120 @@
+/**
+ * AgentRuntime SDK 类型 — 供 Hosting 内嵌与 eap dev 调用
+ *
+ * HITL：`stream()` 在 `hitl.waited` 后结束；续跑走 `streamResumeHitl()`（新 SSE）。
+ * `resumeHitl()` 消费该流并返回 `ResumeHitlResult`。
+ *
+ * @see 04-runtime-core/design.md §1.5
+ */
+import type { ExecutionContext, InvokeConfig, ResumeHitlResult } from '@gt-fe/eap-contracts';
+import type { InvokeResponseData } from '../api/routes/agent.routes.js';
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+import type { SSEEvent } from '../sse/contracts/sse-emitter.contract.js';
+/** 同步/流式执行参数 */
+export interface ExecuteParams {
+    /**
+     * @deprecated 使用 agentCode；保留仅为迁移双读
+     */
+    agentId?: string;
+    /** 对外主键（优先） */
+    agentCode?: string;
+    input: string;
+    /** 平台执行上下文（Hosting / eap dev 注入，对齐 04 R15） */
+    executionContext?: ExecutionContext;
+    sessionId?: string;
+    /** Hosting 发号的 Task ID；有则 Runtime 复用 */
+    taskId?: string;
+    /** Hosting 路由选定的预装版本目录（AR-3b） */
+    agentVersion?: string;
+    /**
+     * Hosting 已创建的 Trace id（Foundation `POST /traces` / TraceLinker.createTrace 的返回值）。
+     * 写入 GraphState 供 Skill/Tool span。
+     */
+    traceId?: string;
+    config?: InvokeConfig;
+}
+/** 同步执行结果 */
+export type ExecuteResult = InvokeResponseData;
+/** HITL 恢复结果（与 @gt-fe/eap-contracts ResumeHitlResult 对齐） */
+export type { ResumeHitlResult };
+/** HITL 用户响应 */
+export interface HitlResponse {
+    choice: string;
+    userId: string;
+    executionContext?: ExecutionContext;
+    /**
+     * Checkpoint thread_id 提示（冷恢复）。
+     * Hosting 可从 tasks.output.hitlThreadId 注入；优先于 sessionId。
+     */
+    threadId?: string;
+}
+/** Fork 参数覆盖 */
+export interface ForkOverrides {
+    model?: string;
+    toolInputs?: Record<string, unknown>;
+    skipNodes?: string[];
+    state?: Record<string, unknown>;
+    /** 源 Trace ID（未提供时从 checkpoint 元数据读取） */
+    originalTraceId?: string;
+    /**
+     * @deprecated 使用 agentCode
+     */
+    agentId?: string;
+    /** 执行所用 Agent（未提供时从 checkpoint state 读取） */
+    agentCode?: string;
+    /** 预装版本（未提供时从 checkpoint state.agentVersion 读取） */
+    agentVersion?: string;
+    userId?: string;
+    sessionId?: string;
+    /** 续操作时的执行上下文（Hosting 注入） */
+    executionContext?: ExecutionContext;
+}
+/** Fork 执行结果 */
+export interface ForkResult {
+    newTraceId: string;
+    originalTraceId: string;
+    newTaskId: string;
+    checkpointId: string;
+    status: 'completed' | 'failed';
+    output: unknown;
+    tokenUsage: {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+    };
+    compareUrl?: string;
+}
+/**
+ * 会话种子消息入参 —— 首条真实用户输入之前，向 Runtime session 一次性预置
+ * 开发者提供的对话上下文（开场白 / few-shot）。
+ *
+ * 约束（AgentRuntime.seedSessionMessages 强制校验）：
+ * - `role` 白名单为 `user` / `assistant`，`system` 走 graph.json 的
+ *   `config.systemPrompt`（由 SystemPromptBuilder 拼平台规则），`tool` 必须与
+ *   前置 assistant.toolCalls 严格配对，两者禁止作为种子；
+ * - 该 session 已有历史时，视作已种入，跳过写入（exactly-once 幂等）。
+ */
+export interface SeedSessionMessagesParams {
+    /**
+     * @deprecated 使用 agentCode；保留仅为迁移双读
+     */
+    agentId?: string;
+    /** 对外主键（优先） */
+    agentCode?: string;
+    /** 预装版本（写入 session.metadata.agentVersion，续聊回退） */
+    agentVersion?: string;
+    /** 会话 ID；未提供时新建 session */
+    sessionId?: string;
+    /** 平台执行上下文（Hosting / eap dev 注入） */
+    executionContext?: ExecutionContext;
+    /** 种子消息列表（role ∈ user | assistant，content 非空） */
+    messages: GraphMessage[];
+}
+/** 种子消息执行结果 */
+export interface SeedSessionMessagesResult {
+    /** 复用或新建的 session ID */
+    sessionId: string;
+    /** true=本次写入了种子；false=既有历史已存在，跳过写入 */
+    seeded: boolean;
+}
+export type { SSEEvent };

package/dist/runtime/types.js

@@ -0,0 +1,9 @@
+/**
+ * AgentRuntime SDK 类型 — 供 Hosting 内嵌与 eap dev 调用
+ *
+ * HITL：`stream()` 在 `hitl.waited` 后结束；续跑走 `streamResumeHitl()`（新 SSE）。
+ * `resumeHitl()` 消费该流并返回 `ResumeHitlResult`。
+ *
+ * @see 04-runtime-core/design.md §1.5
+ */
+export {};

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @eap/runtime HTTP 服务入口
+ *
+ * Phase 1 独立部署模式：包装 InvokeOrchestrator / StreamOrchestrator 为 REST API。
+ * Phase 2+ 推荐由 hosting-service 内嵌 SDK，本服务可选。
+ *
+ * TODO: Phase 2 将本文件迁移至 dev-tools/cli（作为 `eap dev` 命令实现），
+ *       runtime 包不再包含 HTTP 服务代码，仅作为纯库导出。
+ */
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+declare const server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
+export { server };