@ai-setting/roy-agent-core 1.5.5 → 1.5.7

package/dist/env/agent/index.d.ts

@@ -0,0 +1,2279 @@
+/**
+* @fileoverview Hook 系统统一类型定义
+* 
+* 提供所有 Component 使用的统一 Hook 接口
+*/
+/**
+* Hook 执行阶段
+*/
+type HookPhase = "before" | "after" | "error";
+/**
+* Hook 元信息
+*/
+interface HookMeta {
+	/** Hook 唯一名称 */
+	name: string;
+	/** 执行优先级，默认 0，数值越小越先执行 */
+	priority?: number;
+	/** 描述 */
+	description?: string;
+}
+/**
+* 统一 Hook 上下文
+* 
+* 泛型参数 T 表示该 Component 的上下文数据类型
+*/
+interface HookContext<T = unknown> {
+	/** 当前组件信息 */
+	component: {
+		/** 组件名称 */
+		name: string;
+		/** 组件版本 */
+		version: string;
+	};
+	/** 上下文数据（Component 特定） */
+	data: T;
+	/** 元数据（可用于传递额外信息） */
+	metadata: Record<string, unknown>;
+	/** 执行阶段 */
+	phase: HookPhase;
+	/** 关联的 hook 点名称 */
+	hookPoint: string;
+}
+/**
+* 统一 Hook 接口
+* 
+* 所有 Component 的 Hook 都应实现此接口
+*/
+interface Hook<T = unknown> extends HookMeta {
+	/** 执行 Hook
+	* @param ctx 上下文
+	*/
+	execute(ctx: HookContext<T>): void | Promise<void>;
+}
+/**
+* Hook 函数类型（便捷别名）
+*/
+type HookFn<T = unknown> = (ctx: HookContext<T>) => void | Promise<void>;
+/**
+* Hook 干预动作类型
+*/
+type HookActionType = "stop" | "retry" | "compress" | "extract_memory" | "inject_message" | "skip_tool" | "custom";
+/**
+* Hook 干预动作
+*/
+interface HookAction {
+	/** 动作类型 */
+	type: HookActionType;
+	/** 动作参数 */
+	params?: Record<string, unknown>;
+	/** 动作描述 */
+	description?: string;
+}
+/**
+* Hook 执行结果
+*/
+interface HookResult {
+	/** 是否被停止 */
+	stopped?: boolean;
+	/** 干预动作（如果有） */
+	action?: HookAction;
+	/** 执行结果数据 */
+	results?: unknown[];
+}
+/**
+* HookManager 配置
+*/
+interface HookManagerOptions {
+	/** 组件名称（用于上下文） */
+	componentName?: string;
+	/** 组件版本（用于上下文） */
+	componentVersion?: string;
+	/** 默认优先级 */
+	defaultPriority?: number;
+}
+/**
+* HookManager
+* 
+* 统一管理 Component 的 Hook
+* 
+* @example
+* ```typescript
+* const manager = new HookManager<MyContext>();
+* 
+* // 注册 Hook
+* manager.register("before-action", {
+*   name: "my-hook",
+*   priority: 10,
+*   execute: async (ctx) => { /* ... *\/ }
+* });
+* 
+* // 执行 Hooks
+* await manager.execute("before-action", data);
+* ```
+*/
+declare class HookManager<T = unknown> {
+	private _hooks;
+	private componentName;
+	private componentVersion;
+	private defaultPriority;
+	constructor(options?: HookManagerOptions);
+	/**
+	* 注册 Hook 到指定 hook 点
+	*/
+	register(hookPoint: string, hook: Hook<T>): void;
+	/**
+	* 注册多个 Hook
+	*/
+	registerMany(hookPoint: string, hooks: Hook<T>[]): void;
+	/**
+	* 按名称取消注册 Hook
+	* @returns 是否成功取消注册
+	*/
+	unregister(hookPoint: string, name: string): boolean;
+	/**
+	* 取消注册所有指定 hook 点的 Hook
+	*/
+	unregisterAll(hookPoint: string): void;
+	/**
+	* 执行指定 hook 点的所有 Hook
+	*/
+	execute(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<void>;
+	/**
+	* 执行指定 hook 点的所有 Hook 并收集返回值
+	*/
+	executeAndCollect<R>(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<R[]>;
+	/**
+	* 获取指定 hook 点的 Hook 数量
+	*/
+	count(hookPoint: string): number;
+	/**
+	* 清空所有 Hook
+	*/
+	clear(): void;
+	/**
+	* 获取所有已注册的 hook 点
+	*/
+	getHookPoints(): string[];
+	/**
+	* 检查 hook 点是否有任何 Hook
+	*/
+	hasHooks(hookPoint: string): boolean;
+	/**
+	* 设置组件信息
+	*/
+	setComponentInfo(name: string, version: string): void;
+	/**
+	* 获取所有注册的 hooks（只读副本）
+	*/
+	get hooks(): ReadonlyMap<string, Hook<T>[]>;
+	/**
+	* 执行 Hook 并支持干预机制
+	* 
+	* 如果任何一个 Hook 返回 { stop: true }，执行会停止
+	* Hook 可以通过返回 HookResult 来执行干预动作
+	* 
+	* @param hookPoint Hook 点
+	* @param data 数据
+	* @param metadata 元数据
+	* @returns 执行结果
+	*/
+	executeWithIntervention(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<HookResult>;
+	/**
+	* 获取或创建 hook 列表
+	*/
+	private getOrCreateHooks;
+	/**
+	* 按优先级排序 Hook
+	* 
+	* 优先级相同时保持原顺序（稳定排序）
+	*/
+	private sortHooks;
+	/**
+	* 创建 Hook 上下文
+	*/
+	private createContext;
+	/**
+	* 安全执行 Hook（错误隔离）
+	*/
+	private safeExecute;
+	/**
+	* 安全执行 Hook 并返回结果
+	*/
+	private safeExecuteAndReturn;
+}
+import { ZodType as ZodType3, ZodTypeDef as ZodTypeDef2 } from "zod";
+/**
+* @fileoverview Environment types and interfaces
+* 
+* 定义 Environment 的核心类型，包括：
+* - Environment 配置
+* - EnvEvent 事件类型
+*/
+/**
+* Environment Config
+*/
+interface EnvironmentConfig {
+	/** 环境名称 */
+	name: string;
+	/** 环境版本 */
+	version: string;
+	/** 是否启用 */
+	enabled: boolean;
+}
+/**
+* EnvEvent 元信息
+*/
+interface EnvEventMetadata {
+	/** 触发事件的 session ID */
+	trigger_session_id?: string;
+	/** 触发事件的 agent ID */
+	trigger_agent_id?: string;
+	/** Agent 名称 */
+	trigger_agent_name?: string;
+	/** 环境名称 */
+	env_name?: string;
+	/** 事件来源 */
+	source?: string;
+	/** 其他元数据 */
+	[key: string]: unknown;
+}
+/**
+* EnvEvent
+* 
+* 统一的事件机制，用于：
+* - Stream 事件（stream.start, stream.text, stream.completed 等）
+* - 工具调用事件（tool.call, tool.result 等）
+* - 会话事件（session.created, session.updated 等）
+* - Agent 事件（agent.thinking, agent.acting 等）
+*/
+interface EnvEvent<T = unknown> {
+	/** 事件 ID */
+	id: string;
+	/** 事件类型 */
+	type: string;
+	/** 时间戳 */
+	timestamp: number;
+	/** 元信息 */
+	metadata: EnvEventMetadata;
+	/** 事件负载 */
+	payload: T;
+}
+/**
+* EnvEvent Handler
+*/
+type EnvEventHandler = (event: EnvEvent) => void | Promise<void>;
+/**
+* EnvEvent 创建参数（部分属性，可选）
+* 
+* 用于 pushEnvEvent 方法，允许传入部分属性，自动补全必填字段
+*/
+interface EnvEventInput {
+	/** 事件类型（必填） */
+	type: string;
+	/** 事件 ID（可选，自动生成） */
+	id?: string;
+	/** 时间戳（可选，自动生成） */
+	timestamp?: number;
+	/** 元信息（可选，自动创建） */
+	metadata?: EnvEventMetadata;
+	/** 事件负载（可选） */
+	payload?: unknown;
+}
+/**
+* Action 类型
+*/
+interface Action {
+	/** Action 类型 */
+	type: string;
+	/** Action 参数 */
+	params?: Record<string, unknown>;
+}
+/**
+* Tool Result
+*/
+interface ToolResult {
+	/** 是否成功 */
+	success: boolean;
+	/** 输出内容 */
+	output: string | Record<string, unknown>;
+	/** 错误信息 */
+	error?: string;
+}
+/**
+* Context
+*/
+interface Context {
+	/** 会话 ID */
+	sessionId?: string;
+	/** 用户 ID */
+	userId?: string;
+	/** 工作目录 */
+	workdir?: string;
+	/** 中断信号 */
+	abort?: AbortSignal;
+	/** 元数据 */
+	metadata?: Record<string, unknown>;
+}
+import { ModelMessage } from "ai";
+import { z, ZodType, ZodError } from "zod";
+/**
+* 沙箱配置
+*/
+interface SandboxConfig {
+	/** 是否启用沙箱 */
+	enabled: boolean;
+	/** 沙箱类型 */
+	type: "native" | "docker";
+	/** 动作过滤 */
+	actionFilter?: {
+		/** 包含的动作 */
+		include?: string[];
+		/** 排除的动作 */
+		exclude?: string[];
+	};
+	/** 文件系统限制 */
+	filesystem?: {
+		/** 允许读取 */
+		allowRead?: string[];
+		/** 禁止读取 */
+		denyRead?: string[];
+		/** 允许写入 */
+		allowWrite?: string[];
+		/** 禁止写入 */
+		denyWrite?: string[];
+	};
+	/** 网络限制 */
+	network?: {
+		/** 允许的域名 */
+		allowedDomains?: string[];
+		/** 禁止的域名 */
+		deniedDomains?: string[];
+	};
+	/** Docker 配置 */
+	docker?: {
+		/** 镜像 */
+		image?: string;
+		/** 网络模式 */
+		networkMode?: "bridge" | "host" | "none";
+		/** 卷挂载 */
+		volumes?: Record<string, string>;
+	};
+}
+/**
+* 工具执行上下文
+*/
+interface ToolContext {
+	/** 工作目录 */
+	workdir?: string;
+	/** 用户 ID */
+	user_id?: string;
+	/** 会话 ID */
+	session_id?: string;
+	/** 消息 ID */
+	message_id?: string;
+	/** 中断信号 */
+	abort?: AbortSignal;
+	/** 额外元数据 */
+	metadata?: Record<string, unknown>;
+	/** 沙箱配置 */
+	sandbox?: SandboxConfig;
+	/** 沙箱 Provider */
+	sandboxProvider?: unknown | null;
+}
+/**
+* 工具结果元数据
+*/
+interface ToolResultMetadata {
+	/** 执行时间（毫秒） */
+	execution_time_ms: number;
+	/** 输出大小（字节） */
+	output_size?: number;
+	/** 标准输出 */
+	stdout?: string;
+	/** 标准错误 */
+	stderr?: string;
+	/** 退出码 */
+	exit_code?: number;
+	/** Token 使用量 */
+	usage?: {
+		inputTokens: number;
+		outputTokens: number;
+		totalTokens?: number;
+	};
+	/** 额外元数据 */
+	[key: string]: unknown;
+}
+/**
+* 工具执行结果
+*/
+interface ToolResult2 {
+	/** 是否成功 */
+	success: boolean;
+	/** 输出内容 */
+	output: string | Record<string, unknown>;
+	/** 错误信息 */
+	error?: string;
+	/** 结果元数据 */
+	metadata?: ToolResultMetadata;
+}
+/**
+* 工具元数据
+*/
+interface ToolMetadata {
+	/** 分类 */
+	category?: string;
+	/** 标签 */
+	tags?: string[];
+	/** 版本 */
+	version?: string;
+	/** 作者 */
+	author?: string;
+	/** 是否实验性 */
+	experimental?: boolean;
+	/** MCP 工具信息（MCP adapter 使用） */
+	mcpTool?: {
+		originalName: string;
+		originalDescription: string;
+		inputSchema?: unknown;
+	};
+}
+/**
+* 工具沙箱配置
+*/
+interface ToolSandboxConfig {
+	/** 是否启用沙箱 */
+	enabled: boolean;
+	/** 沙箱配置 */
+	config?: Partial<SandboxConfig>;
+}
+/**
+* 工具权限配置
+*/
+interface ToolPermissionConfig {
+	/** 是否需要用户确认 */
+	requireConfirmation?: boolean;
+	/** 权限级别 */
+	level?: "safe" | "dangerous" | "critical";
+}
+/**
+* 工具信息
+*/
+interface ToolInfo<Parameters extends ZodType = ZodType> {
+	/** 工具名称 */
+	name: string;
+	/** 工具描述 */
+	description: string;
+	/** 参数 Schema */
+	parameters: Parameters;
+	/** 初始化函数（可选） */
+	init?: (ctx?: ToolContext) => Promise<void>;
+	/** 执行函数 */
+	execute: (args: z.infer<Parameters>, ctx: ToolContext) => Promise<ToolResult2>;
+	/** 参数验证错误格式化（可选） */
+	formatValidationError?: (error: ZodError) => string;
+	/** 沙箱配置 */
+	sandbox?: ToolSandboxConfig;
+	/** 权限配置 */
+	permission?: ToolPermissionConfig;
+	/** 工具元数据 */
+	metadata?: ToolMetadata;
+}
+/**
+* 工具类型别名
+*/
+type Tool = ToolInfo;
+/**
+* LLM Message
+*/
+interface LLMMessage {
+	/** 消息角色 */
+	role: "system" | "user" | "assistant" | "tool";
+	/** 消息内容 */
+	content: string;
+	/** 工具调用（仅 assistant 角色） */
+	toolCalls?: ToolCall[];
+	/** 工具调用 ID（仅 tool 角色） */
+	toolCallId?: string;
+	/** 名称（用于 function 调用） */
+	name?: string;
+}
+/**
+* Tool Call (OpenAI format)
+*/
+interface ToolCall {
+	/** 工具调用 ID */
+	id: string;
+	/** 工具名称 */
+	name: string;
+	/** 工具参数（JSON 字符串） */
+	arguments: string;
+	/** OpenAI 格式的 function 对象 */
+	function?: {
+		/** 函数名称 */
+		name: string;
+		/** 函数参数（JSON 字符串） */
+		arguments: string;
+	};
+}
+/**
+* Usage Information
+*/
+interface UsageInfo {
+	/** Prompt Token 数 */
+	promptTokens: number;
+	/** Completion Token 数 */
+	completionTokens: number;
+	/** 总 Token 数 */
+	totalTokens: number;
+}
+/**
+* LLM Output
+*/
+interface LLMOutput {
+	/** 生成的内容 */
+	content: string;
+	/** 推理/思考内容（支持 reasoning 模型的输出） */
+	reasoning?: string;
+	/** 完成原因 */
+	finishReason: "stop" | "length" | "content-filter" | "tool-calls" | "function-call";
+	/** 工具调用 */
+	toolCalls?: ToolCall[];
+	/** Usage 信息 */
+	usage?: UsageInfo;
+	/** 生成模型 */
+	model?: string;
+}
+/**
+* 模型限制配置
+*/
+interface ModelLimits {
+	/** 上下文窗口大小（Token 数） */
+	contextWindow: number;
+	/** 压缩阈值（0-1），超过此比例触发上下文压缩 */
+	compactionThreshold?: number;
+	/** 最大输出 Token 数 */
+	maxOutputTokens?: number;
+}
+/**
+* LLM Invoke 请求
+*/
+interface LLMInvokeRequest {
+	/** 消息列表 */
+	messages: LLMMessage[];
+	/** Provider ID（可选，默认使用配置的默认 Provider） */
+	providerId?: string;
+	/** 模型（可选，默认使用配置的默认模型） */
+	model?: string;
+	/** 工具列表 */
+	tools?: ToolInfo2[];
+	/** 温度参数 */
+	temperature?: number;
+	/** 最大 Token 数 */
+	maxTokens?: number;
+	/** Top P */
+	topP?: number;
+	/** 工具选择策略 */
+	toolChoice?: "auto" | "none" | {
+		type: "function";
+		function: {
+			name: string;
+		};
+	};
+	/** 停止序列 */
+	stopSequences?: string[];
+	/** Abort Signal */
+	abortSignal?: AbortSignal;
+	/** 调用上下文（用于事件元数据） */
+	context?: LLMInvokeContext;
+	/** 跳过上下文阈值检查（用于 SummaryAgent 等内部调用，避免循环触发压缩） */
+	skipThresholdCheck?: boolean;
+}
+/**
+* LLM Invoke 结果
+*/
+interface LLMInvokeResult {
+	/** LLM 输出 */
+	output: LLMOutput;
+	/** 使用的 Provider ID */
+	providerId: string;
+	/** 使用的模型 */
+	model: string;
+	/** 调用延迟（毫秒） */
+	latencyMs: number;
+}
+/**
+* Tool Info（用于 LLM 工具调用）
+*/
+interface ToolInfo2 {
+	/** 工具名称 */
+	name: string;
+	/** 工具描述 */
+	description?: string;
+	/** 工具参数 Schema */
+	parameters: Record<string, unknown>;
+}
+/**
+* LLM 调用上下文（用于事件元数据）
+*/
+interface LLMInvokeContext {
+	/** Session ID */
+	sessionId?: string;
+	/** Message ID */
+	messageId?: string;
+}
+type AbortSignalType = AbortSignal;
+interface ProjectSummary {
+	projectPath: string;
+	projectName: string;
+	lastUpdated: number;
+	summary: string;
+	shortSummary: string;
+	draftCount: number;
+	memoryMdPath: string;
+	draftsDir: string;
+	detailsDir: string;
+}
+/**
+* Agent 执行上下文
+*/
+interface AgentContext {
+	/** 会话 ID */
+	sessionId?: string;
+	/** 消息 ID */
+	messageId?: string;
+	/** 中断信号 */
+	abort?: AbortSignalType;
+	/** 额外的上下文信息（会添加到 system prompt） */
+	additionInfo?: string;
+	/** 元数据 */
+	metadata?: Record<string, unknown>;
+	/** Agent 类型（用于选择 Behavior Spec） */
+	agentType?: string;
+	/** 使用的模型 */
+	model?: string;
+	/** 允许的工具列表（上下文级别，会覆盖 agent 配置） */
+	allowedTools?: string[];
+	/** 拒绝的工具列表（上下文级别，会覆盖 agent 配置） */
+	deniedTools?: string[];
+	/** 是否过滤 history 中的 tool 消息（上下文级别，会覆盖 agent 配置） */
+	filterHistory?: boolean;
+}
+/**
+* 工具调用（内部使用）
+*/
+interface ToolCall2 {
+	/** 调用 ID */
+	id: string;
+	/** 工具名称 */
+	name: string;
+	/** 调用参数 */
+	arguments: Record<string, unknown>;
+}
+/**
+* 工具调用结果
+*/
+interface ToolCallResult {
+	/** 调用 ID */
+	id: string;
+	/** 工具名称 */
+	name: string;
+	/** 调用结果 */
+	result: ToolResult2;
+	/** 是否成功 */
+	success: boolean;
+}
+/**
+* Hook 点枚举（带 component 前缀）
+*/
+type HookPoint = "agent:before.start" | "agent:before.llm" | "agent:after.llm" | "agent:before.tool" | "agent:after.tool" | "agent:on.iteration" | "agent:on.threshold" | "agent:after.complete" | "agent:on.error" | "agent:after.react" | "on.error";
+/**
+* Context data for agent:after.react hook
+*/
+interface AgentReactContext {
+	/** Current messages for memory extraction */
+	messages: ModelMessage[];
+	/** Current session ID */
+	sessionId?: string;
+	/** Execution summary */
+	summary?: string;
+}
+/**
+* Hook 上下文（Agent 特有版本）
+* 
+* 注意：这是 AgentComponent 使用的 HookContext 扩展版本
+* 包含 iteration, maxIterations, messages 等 Agent 特有字段
+*/
+interface HookContext2 {
+	/** 当前 LLM 输出（after.llm hook 可用） */
+	llmOutput?: AgentLLMOutput;
+	/** 当前工具调用（before.tool/after.tool hook 可用） */
+	currentToolCall?: ToolCall2;
+	/** 工具执行结果（after.tool hook 可用） */
+	toolResult?: ToolCallResult;
+	/** 阈值信息（on.threshold hook 可用） */
+	threshold?: {
+		type: "tokens" | "turns" | "iterations" | "custom";
+		value: number;
+		limit?: number;
+	};
+	/** 当前错误（on.error hook 可用） */
+	error?: Error;
+	/** 当前 Agent 实例 */
+	agent: AgentInstance;
+	/** 当前迭代次数（可修改） */
+	iteration: number;
+	/** 最大迭代次数限制（before.llm hook 可用） */
+	maxIterations: number;
+	/** 消息列表（可直接修改） */
+	messages: ModelMessage[];
+	/** 可用工具列表（可直接修改） */
+	tools: Tool[];
+	/** 当前 system prompt（可直接修改） */
+	systemPrompt: string;
+	/** 额外的上下文信息（可直接修改） */
+	additionInfo?: string;
+	/** 执行上下文（可直接修改属性） */
+	context: AgentContext;
+	/** 是否已停止 */
+	_stopped?: boolean;
+	/** 停止原因 */
+	_stopReason?: string;
+	/** 待执行的干预动作 */
+	_pendingAction?: {
+		type: HookActionType2;
+		payload?: unknown;
+	};
+	/** 错误列表 */
+	_errors?: Array<{
+		plugin: string;
+		error: string;
+	}>;
+	/** Project Memory Agent 生成的摘要列表（由 Project Agent 写入，Global Agent 读取） */
+	projectSummaries?: ProjectSummary[];
+}
+/**
+* Hook 干预动作
+*/
+type HookActionType2 = "stop" | "retry" | "compress" | "extract_memory" | "inject_message" | "skip_tool";
+/**
+* Hook 返回结果
+*/
+interface HookResult2 {
+	/** 是否继续执行（false = 停止 Agent） */
+	continue: boolean;
+	/** 干预动作（可选） */
+	action?: {
+		type: HookActionType2;
+		payload?: unknown;
+	};
+}
+/**
+* Plugin 定义
+*/
+interface Plugin {
+	/** Plugin 唯一名称 */
+	name: string;
+	/** Plugin 版本 */
+	version: string;
+	/** Plugin 描述 */
+	description?: string;
+	/** 订阅的 Hook 点及优先级 */
+	hooks: Array<{
+		point: HookPoint;
+		/** 优先级，默认 0，数字越大越先执行 */
+		priority?: number;
+	}>;
+	/** 执行函数 */
+	execute: (ctx: HookContext2) => HookResult2 | Promise<HookResult2>;
+}
+/**
+* Agent 类型
+*/
+type AgentType = "primary" | "sub" | "summary";
+/**
+* Agent 状态
+*/
+type AgentStatus = "idle" | "running" | "paused" | "stopped" | "error";
+/**
+* Agent 实例配置
+*/
+interface AgentInstanceConfig {
+	/** Agent 类型 */
+	type: AgentType;
+	/** Agent 名称 */
+	name?: string;
+	/** System Prompt */
+	systemPrompt?: string;
+	/** Behavior Spec ID */
+	behaviorSpecId?: string;
+	/** 使用的模型 */
+	model?: string;
+	/** 最大迭代次数 */
+	maxIterations?: number;
+	/** 最大错误重试次数 */
+	maxErrorRetries?: number;
+	/** 死循环检测阈值 */
+	doomLoopThreshold?: number;
+	/** 允许的工具列表 */
+	allowedTools?: string[];
+	/** 拒绝的工具列表 */
+	deniedTools?: string[];
+	/** 工具超时（毫秒） */
+	toolTimeout?: number;
+	/** 工具重试次数 */
+	toolRetries?: number;
+	/** 是否过滤 history 中的 tool 消息（默认过滤，避免上下文过长） */
+	filterHistory?: boolean;
+}
+/**
+* Agent 实例
+*/
+interface AgentInstance {
+	/** Agent 名称 */
+	name: string;
+	/** Agent 配置 */
+	config: Required<AgentInstanceConfig>;
+	/** 当前状态 */
+	status: AgentStatus;
+	/** 注册的 Plugins */
+	plugins: Map<string, Plugin>;
+}
+/**
+* Agent 执行结果
+*/
+interface AgentRunResult {
+	/** 最终文本响应 */
+	finalText?: string;
+	/** 是否被 hook 停止 */
+	stopped?: boolean;
+	/** 停止原因 */
+	stopReason?: string;
+	/** 执行的迭代次数 */
+	iterations: number;
+	/** 工具调用列表 */
+	toolCalls: ToolCall2[];
+	/** 错误信息（如有） */
+	error?: string;
+}
+/**
+* LLM 调用结果
+* 
+* 复用 LLMComponent 的 LLMOutput，并扩展 Agent 特有字段
+*/
+interface LLMCallResult {
+	/** 成功 */
+	success: boolean;
+	/** 输出 */
+	output?: LLMOutput;
+	/** 错误信息 */
+	error?: string;
+	/** Usage 信息 */
+	usage?: {
+		promptTokens: number;
+		completionTokens: number;
+		totalTokens: number;
+	};
+}
+/**
+* Agent 内部使用的 LLM 输出
+* 独立定义以避免与 LLMOutput 的类型冲突
+*/
+interface AgentLLMOutput {
+	/** 生成的内容 */
+	content: string;
+	/** 完成原因 */
+	finishReason: "stop" | "length" | "content-filter" | "tool-calls" | "function-call";
+	/** 工具调用（兼容格式） */
+	toolCalls?: Array<{
+		id: string;
+		function?: {
+			name: string;
+			arguments: string;
+		};
+		name?: string;
+		arguments?: string;
+	}>;
+	/** Usage 信息 */
+	usage?: {
+		promptTokens: number;
+		completionTokens: number;
+		totalTokens: number;
+	};
+	/** 生成模型 */
+	model?: string;
+	/** 推理内容（思考过程） */
+	reasoning?: string;
+}
+/**
+* Summary Agent 配置
+* 
+* 专门用于生成 session checkpoint 的 Agent
+*/
+interface SummaryAgentConfig extends AgentInstanceConfig {
+	/** Agent 类型 */
+	type: "summary";
+	/** 使用的 prompt */
+	promptName: "session/compact";
+	/** 默认模型 */
+	model?: string;
+	/** 最大迭代次数（summary 任务只需 1 次） */
+	maxIterations: 1;
+}
+/**
+* Summary Agent 运行选项
+*/
+interface SummaryAgentRunOptions {
+	/** 消息列表 */
+	messages: Array<{
+		role: string;
+		content: string;
+	}>;
+	/** 用户提供的上下文/提示 */
+	userContext?: string;
+	/** 期望的输出格式 */
+	outputFormat: "json";
+	/** 
+	* 场景化提示 (Scenario Hint)
+	* 
+	* 用于指导 checkpoint 生成的重点方向。
+	* 当提供此参数时，会在系统提示中添加场景上下文，
+	* 帮助 LLM 生成更符合当前场景的 checkpoint。
+	*/
+	scenarioHint?: string;
+}
+/**
+* Summary Agent 运行结果
+*/
+interface SummaryAgentResult {
+	/** Checkpoint 标题 */
+	title: string;
+	/** 过程要点 */
+	processKeyPoints: string[];
+	/** 当前状态 */
+	currentState: string;
+	/** 后续待跟进 */
+	nextSteps: string[];
+	/** 用户意图列表 - 从对话中提取的用户相关意图 */
+	userIntents: string[];
+	/** 原始 LLM 响应 */
+	rawResponse?: string;
+}
+/**
+* Compact Hint 生成选项
+* 
+* 用于两阶段自动压缩流程中的第一阶段：
+* 根据会话历史生成场景化的压缩提示
+*/
+interface CompactHintGenerationOptions {
+	/** 消息列表 */
+	messages: Array<{
+		role: string;
+		content: string;
+	}>;
+	/** 
+	* 会话上下文信息（可选）
+	* 
+	* 包含会话相关的额外信息，如：
+	* - 当前活跃任务信息
+	* - 工作目录
+	* - 最近的操作记录等
+	*/
+	sessionContext?: {
+		activeTaskId?: string;
+		activeTaskTitle?: string;
+		workingDirectory?: string;
+		recentActions?: string[];
+	};
+}
+/**
+* Compact Hint 生成结果
+*/
+interface CompactHintGenerationResult {
+	/** 
+	* 场景化压缩指导提示（自然语言）
+	* 
+	* 这是一段"压缩指导 Prompt"，用于告诉 Compact 阶段：
+	* "在当前这个场景/目标/任务下，生成 checkpoint 时应该重点关注什么"
+	* 
+	* 示例：
+	* "Feature development. User is implementing JWT authentication for auth-service.
+	*  Focus on: auth flow decisions, token refresh progress, middleware implementation."
+	*/
+	hint: string;
+	/** 原始 LLM 响应 */
+	rawResponse?: string;
+}
+import { ZodType as ZodType2, ZodTypeDef } from "zod";
+/**
+* ConfigSource 类型
+*/
+type ConfigSourceType = "memory" | "file" | "env" | "remote";
+/**
+* SourceRegistration - Source 注册配置
+*/
+interface SourceRegistration {
+	/** Source 类型 */
+	type: ConfigSourceType;
+	/** 相对路径（file 类型使用，基于 XDG_DATA_HOME） */
+	relativePath?: string;
+	/** 环境变量前缀（env 类型使用） */
+	envPrefix?: string;
+	/** 优先级，默认值：memory=0, file=10, env=20 */
+	priority?: number;
+	/** 是否可选（file 类型使用，文件不存在时不报错） */
+	optional?: boolean;
+	/** 是否启用文件监听（file 类型使用，默认 true） */
+	watch?: boolean;
+}
+/**
+* KeyRegistration - 配置 Key 注册
+*/
+interface KeyRegistration {
+	/** 配置 Key（支持点号嵌套，如 "llm.provider"） */
+	key: string;
+	/** 优先使用的 Source 列表（按优先级从低到高） */
+	sources: ConfigSourceType[];
+	/** 自定义优先级（覆盖默认优先级） */
+	priority?: number;
+	/** 默认值 */
+	default?: unknown;
+}
+/**
+* ComponentRegistration - Component 注册配置
+*/
+interface ComponentRegistration {
+	/** Component 名称 */
+	name: string;
+	/** 声明需要的 Source */
+	sources: SourceRegistration[];
+	/** 声明需要的配置 Key */
+	keys: KeyRegistration[];
+	/** 配置 Schema（用于验证，可选） */
+	schema?: ZodType2<unknown, ZodTypeDef, unknown>;
+	/** 默认值 */
+	defaults?: Record<string, unknown>;
+}
+/**
+* ConfigSource 接口
+*/
+interface ConfigSource {
+	readonly name: ConfigSourceType;
+	readonly priority: number;
+	read(key: string): unknown | undefined;
+	write?(key: string, value: unknown): boolean;
+	delete?(key: string): boolean;
+	list(): Array<{
+		key: string;
+		value: unknown;
+	}>;
+	watch?(callback: (event: ConfigChangeEvent) => void): () => void;
+}
+/**
+* Config 变更事件
+*/
+interface ConfigChangeEvent {
+	type: "change" | "add" | "delete";
+	key: string;
+	oldValue: unknown;
+	newValue: unknown;
+	source: ConfigSourceType;
+	timestamp: number;
+}
+/**
+* ConfigComponent 配置
+*/
+interface ConfigComponentOptions {
+	/** 持久化文件路径 */
+	persistFile?: string;
+	/** 防抖延迟（ms） */
+	debounceMs?: number;
+	/** 最大批量大小 */
+	maxBatchSize?: number;
+}
+/**
+* ConfigComponent
+*/
+declare class ConfigComponent extends BaseComponent {
+	readonly name = "config";
+	readonly version = "1.0.0";
+	private memorySource;
+	private sources;
+	private componentSchemas;
+	private componentPaths;
+	private watchers;
+	/** Source watch unsubscribe 函数 */
+	private sourceUnwatchFns;
+	private persistQueue;
+	private persistFile?;
+	/** Key 注册表：key -> KeyRegistration */
+	private keyRegistry;
+	/** Component 注册表：name -> ComponentRegistration */
+	private componentRegistrations;
+	/** 协议解析器 */
+	private protocolResolver?;
+	/** XDG_DATA_HOME 缓存（用于测试注入） */
+	private __xdgDataHome?;
+	/** Source 注册配置（延迟创建） */
+	private pendingSources;
+	/** Source 唯一标识缓存：type:relativePath -> true */
+	private sourceKeys;
+	/**
+	* 获取 XDG_DATA_HOME（动态获取，支持运行时覆盖）
+	*/
+	getXdgDataHome(): string;
+	/**
+	* 设置 XDG_DATA_HOME（用于测试）
+	*/
+	setXdgDataHome(path: string): void;
+	constructor(options?: ConfigComponentOptions);
+	/**
+	* 注册 Component Schema
+	*/
+	register(schema: ComponentSchema): void;
+	/**
+	* 注销 Component
+	*/
+	unregister(name: string): boolean;
+	/**
+	* 检查是否已注册
+	*/
+	isRegistered(name: string): boolean;
+	/**
+	* 列出所有注册的 Component
+	*/
+	listComponents(): string[];
+	/**
+	* 获取配置值（支持 xxx.yyy.zzz 嵌套访问）
+	* 支持两种模式：
+	* 1. 完整 key：直接查找，如 "component.key" -> 读取 "component.key"
+	* 2. 嵌套对象：查找 component 对象后从中获取属性，如 "component.nested.deep" 
+	*    -> 先找 "component.nested"，再获取其 "deep" 属性
+	*/
+	get(key: string): unknown;
+	/**
+	* 批量获取
+	*/
+	getMany(keys: string[]): Record<string, unknown>;
+	/**
+	* 设置配置值（内存级别 + 异步持久化）
+	*/
+	set(key: string, value: unknown): Promise<void>;
+	/**
+	* 批量设置
+	*/
+	setMany(config: Record<string, unknown>): Promise<void>;
+	/**
+	* 获取 Component 的路径
+	*/
+	getPath(component: string, subPath?: string): string;
+	/**
+	* 手动持久化
+	*/
+	save(key?: string): Promise<void>;
+	/**
+	* 重置到默认值
+	*/
+	reset(key: string): Promise<void>;
+	/**
+	* 监听配置变更
+	*/
+	watch(pattern: string, callback: ComponentWatchCallback): () => void;
+	/**
+	* 添加配置源
+	*/
+	addSource(source: ConfigSource): void;
+	/**
+	* 获取 Source 唯一标识
+	*/
+	private getSourceKey;
+	/**
+	* 移除配置源
+	*/
+	removeSource(name: ConfigSourceType): boolean;
+	/**
+	* 关闭所有配置源的 watcher（用于优雅退出）
+	*/
+	unwatchAll(): void;
+	/**
+	* 获取配置源列表
+	*/
+	getSources(): ConfigSource[];
+	private getNestedValue;
+	private notifyWatchers;
+	private persistToFile;
+	/**
+	* 注册配置 Source
+	* 
+	* Source 会在首次 load() 时被创建
+	* 
+	* @example
+	* config.registerSource({ type: "file", relativePath: "llm-config.jsonc" });
+	* config.registerSource({ type: "env", envPrefix: "LLM" });
+	*/
+	registerSource(registration: SourceRegistration): void;
+	/**
+	* 创建 Source 实例
+	*/
+	private createSource;
+	/**
+	* 确保所有待创建的 Source 已被创建
+	*/
+	private ensureSourcesCreated;
+	/**
+	* 注册配置 Key
+	* 
+	* @example
+	* config.registerKeys([
+	*   { key: "llm.provider", sources: ["file", "memory"], default: "openai" },
+	*   { key: "llm.model", sources: ["file"] },
+	* ]);
+	*/
+	registerKeys(keys: KeyRegistration[]): void;
+	/**
+	* 注册 Component（一次性注册 Source 和 Keys）
+	* 
+	* @example
+	* config.registerComponent({
+	*   name: "llm",
+	*   sources: [
+	*     { type: "file", relativePath: "llm-config.jsonc" },
+	*     { type: "env", envPrefix: "LLM" },
+	*   ],
+	*   keys: [
+	*     { key: "llm.provider", sources: ["file", "env", "memory"] },
+	*   ],
+	* });
+	*/
+	registerComponent(registration: ComponentRegistration): void;
+	/**
+	* 按需加载配置
+	* 
+	* 从注册的 Source 加载已注册 Keys 的配置值到内存中
+	* 
+	* @param componentName - 可选，指定要加载的 Component 名称
+	* 
+	* @example
+	* // 加载所有已注册的 Keys
+	* await config.load();
+	* 
+	* // 只加载指定 Component 的 Keys
+	* await config.load("llm");
+	*/
+	load(componentName?: string): Promise<void>;
+	/**
+	* 获取已注册的 Source 列表
+	*/
+	getRegisteredSources(): ConfigSource[];
+}
+/**
+* 服务配置接口
+*/
+interface ServiceConfig {
+	/** 环境配置 */
+	environment?: {
+		name?: string;
+		version?: string;
+	};
+	/** 组件配置映射 */
+	components?: Record<string, ComponentConfigEntry>;
+}
+/**
+* 组件配置项
+*/
+interface ComponentConfigEntry {
+	/** 配置文件路径（可选） */
+	configPath?: string;
+	/** 环境变量前缀（可选） */
+	envPrefix?: string;
+	/** 直接配置对象（可选） */
+	config?: Record<string, unknown>;
+	/** 是否启用（可选，默认 true） */
+	enabled?: boolean;
+}
+/**
+* 组件初始化选项（由 generateComponentOptions 生成）
+*/
+interface GeneratedComponentOptions {
+	/** ConfigComponent 实例 */
+	configComponent: ConfigComponent;
+	/** 配置文件路径 */
+	configPath?: string;
+	/** 环境变量前缀 */
+	envPrefix?: string;
+	/** 直接配置对象 */
+	config?: Record<string, unknown>;
+	/** 允许的其他属性 */
+	[key: string]: unknown;
+}
+/**
+* Environment 接口
+* 
+* 定义 Agent 运行时的核心能力接口。
+*/
+interface Environment {
+	/** 环境名称 */
+	readonly name: string;
+	/** 环境版本 */
+	readonly version: string;
+	/** 获取环境配置 */
+	getConfig(): EnvironmentConfig;
+	/**
+	* 注册组件
+	*/
+	registerComponent(component: Component): void;
+	/**
+	* 注销组件
+	*/
+	unregisterComponent(name: string): void;
+	/**
+	* 获取组件
+	*/
+	getComponent<T extends Component>(name: string): T | undefined;
+	/**
+	* 列出所有组件
+	*/
+	listComponents(): Component[];
+	/**
+	* 处理自然语言查询（核心入口）
+	* 
+	* @param query 用户查询文本
+	* @param context 执行上下文（可选）
+	* @returns 完整的文本响应
+	*/
+	handle_query(query: string, context?: AgentContext): Promise<string>;
+	/**
+	* 处理动作
+	*/
+	handle_action(action: Action, context: Context): Promise<ToolResult>;
+	/**
+	* 订阅 EnvEvent（返回取消订阅函数）
+	*/
+	subscribe(handler: EnvEventHandler): () => void;
+	/**
+	* 订阅指定类型事件
+	*/
+	subscribeTo(eventType: string | string[], handler: EnvEventHandler): () => void;
+	/**
+	* 订阅所有事件（通配符）
+	*/
+	subscribeAll(handler: EnvEventHandler): () => void;
+	/**
+	* 推送事件
+	* 
+	* @param event EnvEvent 或 EnvEventInput（部分属性）
+	*/
+	pushEnvEvent(event: EnvEvent | EnvEventInput): void;
+	/**
+	* 从配置文件加载服务配置
+	* 
+	* @param configPath 配置文件路径（基于 XDG_DATA_HOME）
+	* @returns 解析后的服务配置对象
+	*/
+	loadServiceConfig(configPath: string): Promise<ServiceConfig>;
+	/**
+	* 生成组件初始化选项
+	* 
+	* 根据组件配置项生成可用于初始化的选项对象。
+	* 
+	* @param componentName 组件名称
+	* @param configEntry 组件配置项
+	* @returns 生成的组件初始化选项
+	*/
+	generateComponentOptions(componentName: string, configEntry: ComponentConfigEntry): GeneratedComponentOptions;
+	/**
+	* 注册组件并用配置初始化
+	* 
+	* 便捷方法：注册组件并通过 ConfigComponent 初始化。
+	* 
+	* @param component 要注册的组件实例
+	* @param configEntry 组件配置项
+	*/
+	registerComponentWithConfig(component: Component, configEntry: ComponentConfigEntry): Promise<void>;
+	/**
+	* 从配置文件初始化整个环境
+	* 
+	* 加载服务配置，注册并初始化所有配置的组件。
+	* 
+	* @param configPath 配置文件路径（基于 XDG_DATA_HOME）
+	*/
+	initFromConfig(configPath: string): Promise<void>;
+}
+/**
+* Component 状态
+*/
+type ComponentStatus = "created" | "initializing" | "running" | "stopping" | "stopped" | "error";
+/**
+* Component 配置
+*/
+interface ComponentConfig {
+	name: string;
+	version: string;
+	enabled: boolean;
+	options?: Record<string, unknown>;
+	/**
+	* Environment 实例（可选）
+	* 
+	* 推荐在 init 时接收 env 实例，以便：
+	* - 通过 env.getComponent() 获取其他组件
+	* - 通过 env.pushEnvEvent() 发布事件
+	* - 通过 env.handle_query() 处理查询
+	* 
+	* 如果未提供，部分 Component 仍可正常工作（如测试场景）
+	* 
+	* @example
+	* ```typescript
+	* async onInit(): Promise<void> {
+	*   if (this.env) {
+	*     const configComp = this.env.getComponent("config");
+	*   }
+	* }
+	* ```
+	*/
+	env?: Environment;
+}
+/**
+* Component 路径声明
+*/
+interface ComponentPaths {
+	base: "config" | "state" | "data" | "cache";
+	subPath: string;
+	isDirectory: boolean;
+}
+/**
+* Component Schema（注册配置）
+*/
+interface ComponentSchema {
+	/** Component 名称 */
+	name: string;
+	/** 配置 Schema（Zod） */
+	schema: ZodType3<unknown, ZodTypeDef2, unknown>;
+	/** 默认值（从 Schema 提取） */
+	defaults: Record<string, unknown>;
+	/** 路径声明 */
+	paths?: Record<string, ComponentPaths>;
+	/** 元信息 */
+	metadata?: {
+		description?: string;
+		version?: string;
+		author?: string;
+	};
+}
+/**
+* Component 配置变更事件
+*/
+interface ComponentConfigChangeEvent {
+	/** Component 名称 */
+	component: string;
+	/** 变更的配置键 */
+	key: string;
+	/** 旧值 */
+	oldValue: unknown;
+	/** 新值 */
+	newValue: unknown;
+	/** 是否持久化 */
+	persisted: boolean;
+	/** 时间戳 */
+	timestamp: number;
+}
+/**
+* Component 配置监听回调
+*/
+type ComponentWatchCallback = (event: ComponentConfigChangeEvent) => void | Promise<void>;
+/**
+* Component 基类接口
+*/
+interface Component {
+	/** Component 名称 */
+	readonly name: string;
+	/** Component 版本 */
+	readonly version: string;
+	/** 获取状态 */
+	getStatus(): ComponentStatus;
+	/** 获取配置 */
+	getConfig(): ComponentConfig;
+	/** 初始化 */
+	init(config: ComponentConfig): Promise<void>;
+	/** 启动 */
+	start(): Promise<void>;
+	/** 停止 */
+	stop(): Promise<void>;
+}
+/**
+* Component 基类实现
+*/
+declare abstract class BaseComponent implements Component {
+	abstract readonly name: string;
+	abstract readonly version: string;
+	protected _status: ComponentStatus;
+	protected _enabled: boolean;
+	protected env: Environment;
+	/** Hook 管理器 - 子类初始化时由构造函数设置 */
+	readonly hookManager: HookManager;
+	constructor();
+	getStatus(): ComponentStatus;
+	getConfig(): ComponentConfig;
+	/**
+	* 检查 Environment 是否已初始化
+	*/
+	protected isEnvInitialized(): boolean;
+	protected setStatus(status: ComponentStatus): void;
+	/**
+	* 获取 Environment 实例
+	*/
+	protected getEnv(): Environment;
+	init(config?: ComponentConfig): Promise<void>;
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	/**
+	* 子类可覆盖的钩子方法
+	*/
+	protected onInit(): Promise<void>;
+	protected onStart(): Promise<void>;
+	protected onStop(): Promise<void>;
+	/**
+	* 注册 Hook
+	* 
+	* @param hookPoint Hook 点名称
+	* @param hook Hook 实例
+	*/
+	protected registerHook<T = unknown>(hookPoint: string, hook: Hook<T>): void;
+	/**
+	* 便捷方法：快速注册 Hook
+	*/
+	protected addHook<T = unknown>(hookPoint: string, name: string, fn: HookFn<T>, priority?: number): void;
+	/**
+	* 便捷方法：按名称取消注册 Hook
+	*/
+	protected removeHook(hookPoint: string, name: string): boolean;
+	/**
+	* 执行 Hook
+	*/
+	protected executeHooks<T = unknown>(hookPoint: string, data: T, metadata?: Record<string, unknown>): Promise<void>;
+	/**
+	* 获取 ConfigComponent 实例
+	* 
+	* 子类可使用此方法获取配置组件，支持热更新
+	*/
+	protected getConfigComponent(): {
+		get(key: string): unknown;
+	} | undefined;
+	/**
+	* 动态获取运行时配置值
+	* 
+	* 优先从 ConfigComponent 获取（支持热更新），否则返回默认值
+	* 适用于运行时可能变化的配置（如 API Keys、模型参数）
+	* 
+	* @param key 配置键（支持点号分隔的路径，如 "llm.temperature"）
+	* @param defaultValue 默认值
+	* @returns 配置值或默认值
+	* 
+	* @example
+	* ```typescript
+	* // 获取 LLM 温度配置（可能支持热更新）
+	* const temperature = this.getRuntimeConfig("llm.temperature", 0.7);
+	* 
+	* // 获取 API Key
+	* const apiKey = this.getRuntimeConfig<string>("llm.providers.openai.apiKey");
+	* ```
+	*/
+	protected getRuntimeConfig<T>(key: string, defaultValue: T): T;
+}
+import { ModelMessage as ModelMessage2 } from "ai";
+import { z as z2 } from "zod";
+/**
+* AgentComponent 配置 Schema
+*/
+declare const AgentComponentConfigSchema: unknown;
+type AgentComponentConfig = z2.infer<typeof AgentComponentConfigSchema>;
+/**
+* AgentComponent
+* 
+* 提供 Agent 执行能力和 Hook 扩展机制
+*/
+declare class AgentComponent extends BaseComponent {
+	readonly name = "agent";
+	readonly version = "1.0.0";
+	private agents;
+	private config;
+	private llmComponent;
+	private toolComponent;
+	private aborted;
+	private abortControllers;
+	private defaultTools;
+	private doomLoopCaches;
+	/** ConfigComponent 用于配置管理 */
+	private configComponent?;
+	/** 配置变更 watcher 清理函数 */
+	private configWatcher?;
+	/** Session 消息转换器 */
+	private messageConverter;
+	/** 构造函数传入的配置（最高优先级） */
+	private _constructorConfig?;
+	/** Run ID 计数器（用于生成唯一的 runId） */
+	private runCounter;
+	constructor(options?: {
+		config?: Partial<AgentComponentConfig>;
+	});
+	/**
+	* 初始化组件
+	* 
+	* 配置加载优先级（从高到低）：
+	* 1. Object - 直接传入的 config 对象
+	* 2. Env - 环境变量（通过 envPrefix 配置前缀）
+	* 3. File - 配置文件（通过 configPath 指定）
+	*/
+	init(config: ComponentConfig): Promise<void>;
+	/**
+	* 注册配置到 ConfigComponent
+	* 
+	* 配置加载顺序（优先级从低到高）：
+	* 1. Defaults - 默认值（最低）
+	* 2. FileSource - 从配置文件加载
+	* 3. EnvSource - 从环境变量加载
+	* 4. config 对象 - 直接传入的配置（最高）
+	*/
+	private registerConfig;
+	/**
+	* 将配置对象展平为点号路径
+	*/
+	private flattenConfig;
+	/**
+	* 注册配置热更新监听
+	*/
+	private registerConfigWatcher;
+	/**
+	* 处理配置变更
+	*/
+	protected onConfigChange(event: {
+		key: string;
+		oldValue?: unknown;
+		newValue?: unknown;
+	}): void;
+	/**
+	* 组件停止时的清理逻辑
+	* 
+	* 清理内容：
+	* 1. 终止所有正在运行的 Agent（调用 abort() 以中断 LLM 调用）
+	* 2. 清空 AbortController 注册表
+	* 3. 清空 Doom Loop 缓存
+	* 4. 取消配置变更监听
+	* 5. 清空 Agent 注册表
+	*/
+	protected onStop(): Promise<void>;
+	/**
+	* 刷新依赖组件引用
+	* 
+	* 当组件被添加到 Environment 后调用，以确保获取到最新的组件引用
+	*/
+	refreshDependencies(): void;
+	/**
+	* 获取 Agent 实例
+	*/
+	getAgent(agentName: string): AgentInstance | undefined;
+	/**
+	* 获取所有 Agent 实例
+	*/
+	listAgents(): AgentInstance[];
+	/**
+	* Add placeholder tool results for remaining unprocessed tool calls
+	* 
+	* This ensures that the message history maintains a 1:1 correspondence
+	* between tool-calls and tool-results, which is required by AI SDK v6.
+	* 
+	* @param ctx - Hook context containing messages
+	* @param allToolCalls - All tool calls from the LLM response
+	* @param processedCount - Number of tool calls that have been processed
+	* @param reason - Reason for the abort/interruption
+	*/
+	private addRemainingToolResults;
+	/**
+	* 注册 Agent
+	* 
+	* 配置优先级（从高到低）：
+	* 1. registerAgent 传入的 config（来自 PromptComponent）
+	* 2. defaultAgent 配置（来自 ConfigComponent，作为 fallback）
+	*/
+	registerAgent(name: string, config: Partial<AgentInstanceConfig>): AgentInstance;
+	/**
+	* 注销 Agent
+	*/
+	unregisterAgent(name: string): boolean;
+	/**
+	* 注册 Plugin 到指定 Agent
+	*/
+	registerPlugin(agentName: string, plugin: Plugin): void;
+	/**
+	* 注销 Plugin
+	*/
+	unregisterPlugin(agentName: string, pluginName: string): boolean;
+	/**
+	* 设置默认工具列表
+	*/
+	setDefaultTools(tools: Tool[]): void;
+	/**
+	* 获取可用工具
+	*/
+	getAvailableTools(agent: AgentInstance, context?: AgentContext): Tool[];
+	/**
+	* 执行 Agent
+	* 
+	* @param agentName Agent 名称
+	* @param query 用户查询
+	* @param context 执行上下文
+	* @returns Agent 执行结果
+	*/
+	run(agentName: string, query: string, context?: AgentContext): Promise<AgentRunResult>;
+	private pushMessage;
+	/**
+	* 执行 Agent（核心方法，内部实现）
+	*/
+	private _run;
+	/**
+	* 中止 Agent
+	* 
+	* 调用此方法会：
+	* 1. 设置 aborted 标志（用于 ReAct 循环检查）
+	* 2. 触发 AbortController.abort()（用于中断正在进行的 LLM 调用）
+	* 
+	* 注意：不直接修改 agent.status，由 _run() 的 finally 统一处理
+	*/
+	abort(agentName: string): void;
+	/**
+	* 构建消息列表
+	* 
+	* 注意：ctx.messages 已经包含了历史消息（包括 system prompt 和 user query）
+	* 这里只需要构建当前请求的消息，不重复添加
+	*/
+	private buildMessages;
+	/**
+	* 调用 LLM
+	* 
+	* 流式事件由 LLMComponent 通过 env.pushEnvEvent() 发布
+	*/
+	private invokeLLM;
+	/**
+	* 执行工具
+	*/
+	private executeTool;
+	/**
+	* 执行 Plugin Hooks (Agent 特有的 Hook 执行机制)
+	*/
+	private executePluginHooks;
+	/**
+	* 处理 Hook 动作
+	*/
+	private handleHookAction;
+	/**
+	* 通知消息添加（扩展点）
+	*/
+	protected notifyMessageAdded(message: ModelMessage2): void;
+	/**
+	* 结束结果
+	*/
+	private finalizeResult;
+	/**
+	* Record messages to session
+	* 
+	* 存储策略：
+	* 1. 存储 allMessages 中的所有 user、assistant、tool 消息
+	* 2. 跳过 system 消息
+	* 3. 跳过空内容的 assistant/tool 消息
+	*/
+	private recordSessionMessages;
+	/**
+	* 检查消息内容是否为空
+	* 
+	* 空内容定义：
+	* - 空字符串 ""
+	* - 空数组 []
+	* - null
+	* - undefined
+	* 
+	* @param content - 消息内容
+	* @returns 是否为空
+	*/
+	private isEmptyMessage;
+	/**
+	* 通过 Environment 发送事件
+	*/
+	private pushEnvEvent;
+	/**
+	* 获取会话对话历史
+	* 
+	* 核心逻辑：
+	* 1. 使用 sessionComponent.getContext() 获取消息（自动从 checkpoint 开始）
+	* 2. 根据 messageLimit 限制消息数量（向后兼容 minUserMessages）
+	* 3. 过滤掉 tool_call/tool_result 消息（如果 filterHistory=true）
+	* 
+	* 关键改进：利用 checkpoint 概念，避免重复获取已压缩的历史消息，
+	* 从而减少重复触发压缩的问题。
+	* 
+	* @param sessionComponent - SessionComponent 实例
+	* @param sessionId - 会话 ID
+	* @param options - 配置选项
+	* @param options.minUserMessages - 最少包含的 user 消息数量（默认 100）
+	* @param options.filterHistory - 是否过滤 tool 消息（默认 true）
+	* @returns 过滤后的会话消息列表
+	*/
+	private getConversationHistory;
+}
+/**
+* Prompt 来源类型
+*/
+type PromptSource = "built-in" | "file" | "directory" | "inline";
+/**
+* Prompt 条目
+*/
+interface PromptEntry {
+	/** 唯一名称 */
+	name: string;
+	/** Prompt 内容 */
+	content: string;
+	/** 来源 */
+	source: PromptSource;
+	/** 原始文件路径 */
+	filePath?: string;
+	/** 是否可覆盖（内置 prompt 不可覆盖） */
+	overridable: boolean;
+	/** 加载时间 */
+	loadedAt: number;
+}
+/**
+* Prompt Hook 上下文（用于统一 Hook 系统）
+*/
+interface PromptHookContext {
+	/** Prompt 名称 */
+	name: string;
+	/** 原始内容 */
+	originalContent: string;
+	/** 渲染后的内容（after hook 可修改） */
+	renderedContent: string;
+	/** 渲染变量 */
+	variables: Record<string, string>;
+}
+/**
+* PromptComponent
+* 
+* 管理提示词存储、加载和渲染
+* 配置通过 ConfigComponent 实时获取，支持配置热更新
+*/
+declare class PromptComponent extends BaseComponent {
+	readonly name = "prompt";
+	readonly version = "1.0.0";
+	private prompts;
+	private config?;
+	private configComponent?;
+	private renderer;
+	/** 配置变更 watcher 清理函数 */
+	private configWatcher?;
+	constructor();
+	/**
+	* 初始化组件
+	* 
+	* 配置加载优先级（从高到低）：
+	* 1. Object - 直接传入的 config 对象
+	* 2. Env - 环境变量（通过 envPrefix 配置前缀）
+	* 3. File - 配置文件（通过 configPath 指定）
+	*/
+	init(config: ComponentConfig): Promise<void>;
+	/**
+	* 注册配置到 ConfigComponent
+	* 
+	* 配置加载顺序（优先级从低到高）：
+	* 1. Env - 环境变量（通过 load 加载 + 直接读取）
+	* 2. Defaults - 默认值（在环境变量检查之后设置）
+	* 3. Config Object - 直接配置对象（最高优先级）
+	*/
+	private registerConfig;
+	/**
+	* 将配置对象展平为点号路径
+	*/
+	private flattenConfig;
+	/**
+	* 注册配置热更新监听
+	*/
+	private registerConfigWatcher;
+	/**
+	* 处理配置变更
+	*/
+	private onConfigChange;
+	private initRenderer;
+	onStart(): Promise<void>;
+	onStop(): Promise<void>;
+	private getPromptConfig;
+	/**
+	* 添加 prompt
+	*/
+	add(name: string, content: string, source?: PromptEntry["source"]): void;
+	/**
+	* 获取 prompt 原始内容
+	*/
+	get(name: string): string | undefined;
+	/**
+	* 获取 prompt 条目
+	*/
+	getEntry(name: string): PromptEntry | undefined;
+	/**
+	* 检查 prompt 是否存在
+	*/
+	has(name: string): boolean;
+	/**
+	* 删除 prompt
+	*/
+	delete(name: string): boolean;
+	/**
+	* 列出所有 prompt 名称
+	*/
+	list(): string[];
+	/**
+	* 获取数量
+	*/
+	size(): number;
+	/**
+	* 获取并渲染 prompt
+	*/
+	getPrompt(name: string, variables?: Record<string, string>): Promise<string>;
+	/**
+	* 渲染内容（异步方法）
+	*/
+	render(content: string, variables?: Record<string, string>, context?: Partial<PromptHookContext>): Promise<string>;
+	/**
+	* 提取内容中的变量
+	*/
+	extractVariables(content: string): string[];
+	/**
+	* 加载所有 prompts（内置 + 外部）
+	*/
+	private loadPrompts;
+	/**
+	* 加载内置 prompts
+	* 
+	* 使用嵌入的 prompts（在构建时打包到 bundle 中）
+	*/
+	private loadBuiltInPrompts;
+	/**
+	* 加载外部 prompts
+	*/
+	private loadExternalPrompts;
+	/**
+	* 从文件加载单个 prompt
+	*/
+	loadFromFile(filePath: string, name?: string): Promise<boolean>;
+	/**
+	* 从目录加载多个 prompt
+	*/
+	loadFromDirectory(directory: string, extension?: string, recursive?: boolean): Promise<number>;
+	private findFiles;
+	/**
+	* 注册 Prompt Hook（公开便捷方法，供外部调用）
+	* 
+	* 现在使用全局 hookManager，允许外部通过 globalHookManager 注册
+	*/
+	registerPromptHook(hookPoint: string, name: string, fn: (ctx: {
+		data: PromptHookContext;
+		phase: "before" | "after";
+	}) => void | Promise<void>, priority?: number): void;
+	/**
+	* 取消注册 Prompt Hook
+	*/
+	unregisterPromptHook(hookPoint: string, name: string): boolean;
+	/**
+	* 获取 Prompt Hook 点列表
+	*/
+	getHookPoints(): string[];
+}
+/**
+* @fileoverview 统一错误类型体系
+* 
+* 提供 AgentError, ToolError, LLMError, ComponentError, ContextError 等错误类型
+* 每个错误包含 code（错误码）和 details（额外信息）
+*/
+/**
+* 错误码枚举
+*/
+declare const ErrorCodes: {
+	readonly AGENT_NOT_FOUND: "AGENT_001";
+	readonly AGENT_RUN_FAILED: "AGENT_002";
+	readonly AGENT_TIMEOUT: "AGENT_003";
+	readonly AGENT_CONFIG_INVALID: "AGENT_004";
+	readonly TOOL_NOT_FOUND: "TOOL_001";
+	readonly TOOL_DISABLED: "TOOL_002";
+	readonly TOOL_EXECUTION_FAILED: "TOOL_003";
+	readonly TOOL_VALIDATION_FAILED: "TOOL_004";
+	readonly LLM_PROVIDER_NOT_FOUND: "LLM_001";
+	readonly LLM_INVOCATION_FAILED: "LLM_002";
+	readonly LLM_TIMEOUT: "LLM_003";
+	readonly LLM_CONFIG_INVALID: "LLM_004";
+	readonly COMPONENT_NOT_FOUND: "COMP_001";
+	readonly COMPONENT_INIT_FAILED: "COMP_002";
+	readonly COMPONENT_NOT_RUNNING: "COMP_003";
+	readonly CONFIG_NOT_FOUND: "CONFIG_001";
+	readonly CONFIG_INVALID: "CONFIG_002";
+	readonly CONFIG_SOURCE_ERROR: "CONFIG_003";
+	readonly CONTEXT_THRESHOLD_EXCEEDED: "CTX_001";
+	readonly CONTEXT_COMPACTION_FAILED: "CTX_002";
+	readonly MCP_INIT_FAILED: "MCP_001";
+	readonly MCP_SERVER_ERROR: "MCP_002";
+	readonly MCP_TOOL_ERROR: "MCP_003";
+};
+type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+/**
+* RoyError 基类
+*/
+declare class RoyError extends Error {
+	readonly code: ErrorCode;
+	readonly details?: unknown;
+	constructor(message: string, code: ErrorCode, details?: unknown);
+}
+/**
+* LLM Output 结构（用于 ContextError 携带 assistant message）
+* 
+* 这是简化版本，仅包含保存到 session 所需的最少字段。
+* 与 llm/types.ts 中的 LLMOutput 不同，那个版本包含完整的 LLM 调用结果。
+*/
+interface LLMOutput2 {
+	content?: string;
+	reasoning?: string;
+	toolCalls?: Array<{
+		id: string;
+		function?: {
+			name: string;
+			arguments: string;
+		};
+		name?: string;
+		arguments?: unknown;
+	}>;
+	usage?: {
+		promptTokens: number;
+		completionTokens: number;
+		totalTokens: number;
+	};
+}
+/**
+* Context 相关错误
+*/
+declare class ContextError extends RoyError {
+	readonly sessionId?: string | undefined;
+	readonly usage?: {
+		promptTokens: number;
+		completionTokens: number;
+		totalTokens: number;
+	} | undefined;
+	readonly contextWindow?: number | undefined;
+	readonly llmOutput?: LLMOutput2;
+	constructor(message: string, code?: ErrorCode, sessionId?: string | undefined, usage?: {
+		promptTokens: number;
+		completionTokens: number;
+		totalTokens: number;
+	} | undefined, contextWindow?: number | undefined, llmOutput?: LLMOutput2, details?: unknown);
+}
+/**
+* LLMComponent
+* 管理 LLM 调用，使用 AI SDK 进行实际调用
+* 
+* 配置通过 ConfigComponent 实时获取，支持配置热更新
+* 
+* @example
+* // 通过 ConfigComponent 加载配置
+* const configComponent = new ConfigComponent();
+* configComponent.setXdgDataHome(__dirname);
+* 
+* const llmComponent = new LLMComponent();
+* await llmComponent.init({
+*   env,  // Environment 实例（必填）
+*   options: {
+*     configComponent,  // ConfigComponent 实例
+*     configPath: "config.jsonc"  // 配置文件路径
+*   }
+* });
+* 
+* // 配置更新后，下次调用会自动获取最新配置
+* configComponent.set("llm.temperature", 0.5);
+*/
+declare class LLMComponent extends BaseComponent {
+	readonly name = "llm";
+	readonly version = "2.0.0";
+	private configComponent?;
+	/** 配置变更 watcher 清理函数 */
+	private configWatcher?;
+	constructor();
+	/**
+	* 初始化组件
+	* 
+	* 配置加载优先级（从高到低）：
+	* 1. Object - 直接传入的 config 对象
+	* 2. Env - 环境变量（通过 envPrefix 配置前缀）
+	* 3. File - 配置文件（通过 configPath 指定）
+	*/
+	init(config: ComponentConfig): Promise<void>;
+	/**
+	* 注册配置到 ConfigComponent
+	* 
+	* 配置加载顺序（优先级从低到高）：
+	* 1. FileSource - 从配置文件加载（最低）
+	* 2. EnvSource - 从环境变量加载（中等）
+	* 3. MemorySource - 直接配置对象（最高）
+	*/
+	private registerConfig;
+	/**
+	* 将配置对象展平为点号路径
+	* 
+	* @example
+	* flattenConfig({ providers: { openai: { apiKey: "xxx" } } })
+	* -> { "llm.providers.openai.apiKey": "xxx" }
+	*/
+	private flattenConfig;
+	/**
+	* 注册配置热更新监听
+	*/
+	private registerConfigWatcher;
+	/**
+	* 处理配置变更（支持热更新）
+	*/
+	protected onConfigChange(event: {
+		key: string;
+		oldValue?: unknown;
+		newValue?: unknown;
+	}): void;
+	/**
+	* 启动组件
+	*/
+	onStart(): Promise<void>;
+	/**
+	* 停止组件
+	*/
+	onStop(): Promise<void>;
+	/**
+	* 从配置源获取配置值
+	* 优先从 ConfigComponent 获取（支持热更新），否则返回默认值
+	*/
+	private getLLMConfig;
+	/**
+	* 解析请求，构建调用上下文（invoke 和 invokeStream 共享）
+	*/
+	private resolveRequest;
+	/**
+	* 调用 LLM
+	* 
+	* 流式事件通过 env.pushEnvEvent() 发布
+	*/
+	invoke(request: LLMInvokeRequest): Promise<LLMInvokeResult>;
+	/**
+	* 获取 Provider API Key
+	*/
+	private getApiKey;
+	/**
+	* 获取 Provider
+	*/
+	getProvider(id: string);
+	/**
+	* 列出所有 Provider
+	*/
+	listProviders();
+	/**
+	* 获取模型的限制配置
+	* 
+	* @param providerId - Provider ID
+	* @param modelId - 模型 ID（可选，默认使用 provider 的 defaultModel）
+	* @returns 模型限制配置，如果没有配置则返回 undefined
+	*/
+	getModelLimits(providerId: string, modelId?: string): ModelLimits | undefined;
+	/**
+	* 获取上下文窗口阈值配置
+	* 
+	* @param providerId - Provider ID
+	* @param modelId - 模型 ID
+	* @returns 包含 contextWindow 和 thresholdRatio 的对象
+	*/
+	getContextThresholdConfig(providerId: string, modelId?: string): {
+		contextWindow: number;
+		thresholdRatio: number;
+	};
+	/**
+	* 检测上下文阈值是否超过
+	* 
+	* @param usage - LLM 使用量信息
+	* @param providerId - Provider ID
+	* @param modelId - 模型 ID
+	* @param sessionId - Session ID（用于错误信息）
+	* @returns 如果超过阈值，返回 ContextError；否则返回 undefined
+	*/
+	checkContextThreshold(usage: {
+		totalTokens: number;
+		promptTokens?: number;
+		completionTokens?: number;
+	} | undefined, providerId: string, modelId: string | undefined, sessionId?: string): ContextError | undefined;
+}
+/**
+* Summary Agent
+* 
+* 专门用于生成 session checkpoint 的 Agent
+*/
+declare class SummaryAgent {
+	private promptComponent;
+	private llmComponent;
+	private config;
+	constructor(promptComponent: PromptComponent, llmComponent: LLMComponent, config?: Partial<SummaryAgentConfig>);
+	/**
+	* 生成场景化压缩提示 (Compact Hint)
+	* 
+	* 根据会话历史分析，生成一个场景化的压缩提示，用于指导后续的 checkpoint 生成。
+	* 这个方法用于自动触发压缩的两阶段流程中的第一阶段。
+	* 
+	* @param options 生成选项
+	* @returns 场景化的压缩提示
+	*/
+	generateCompactHint(options: CompactHintGenerationOptions): Promise<CompactHintGenerationResult>;
+	/**
+	* 运行 Summary Agent
+	* 
+	* @param options 运行选项
+	* @returns Summary Agent 结果
+	*/
+	run(options: SummaryAgentRunOptions): Promise<SummaryAgentResult>;
+	/**
+	* 获取系统提示
+	* 
+	* @param scenarioHint 场景化提示（可选）
+	*/
+	private getSystemPrompt;
+	/**
+	* 获取提示生成的系统提示
+	* 
+	* 这个方法生成的 hint 是一个 "压缩指导 Prompt"，用于告诉 Compact 阶段：
+	* "在当前这个场景/目标/任务下，生成 checkpoint 时应该重点关注什么"
+	* 
+	* 注意：这里生成的是"指导 Prompt"，不是"压缩要点本身"
+	* 
+	* 指导 Prompt 应包含：
+	* 1. 当前正在进行什么工作
+	* 2. 进展是什么
+	* 3. 压缩时需要专注什么信息的提取
+	* 4. 这些信息对后续任务推进很重要，不能丢失
+	*/
+	private getHintGenerationSystemPrompt;
+	/**
+	* 构建提示生成的用户提示
+	*/
+	private buildHintGenerationUserPrompt;
+	/**
+	* 构建用户提示
+	*/
+	private buildUserPrompt;
+	/**
+	* 格式化消息用于 prompt
+	*/
+	private formatMessages;
+	/**
+	* 解析 JSON 响应
+	*/
+	private parseJsonResponse;
+	/**
+	* 解析提示响应
+	* 
+	* 直接返回清理后的自然语言提示
+	*/
+	private parseHintResponse;
+}
+export { ToolResult2 as ToolResult, ToolCallResult, ToolCall2 as ToolCall, Tool, SummaryAgentRunOptions, SummaryAgentResult, SummaryAgentConfig, SummaryAgent, ProjectSummary, Plugin, LLMOutput, LLMCallResult, HookResult2 as HookResult, HookPoint, HookContext2 as HookContext, HookActionType2 as HookActionType, CompactHintGenerationResult, CompactHintGenerationOptions, AgentType, AgentStatus, AgentRunResult, AgentReactContext, AgentLLMOutput, AgentInstanceConfig, AgentInstance, AgentContext, AgentComponentConfigSchema, AgentComponentConfig, AgentComponent };