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

package/dist/env/task/hooks/index.d.ts

@@ -0,0 +1,607 @@
+import { z as z2, 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: z2.infer<Parameters>, ctx: ToolContext) => Promise<ToolResult2>;
+	/** 参数验证错误格式化（可选） */
+	formatValidationError?: (error: ZodError) => string;
+	/** 沙箱配置 */
+	sandbox?: ToolSandboxConfig;
+	/** 权限配置 */
+	permission?: ToolPermissionConfig;
+	/** 工具元数据 */
+	metadata?: ToolMetadata;
+}
+/**
+* 工具类型别名
+*/
+type Tool = ToolInfo;
+import { z as z7 } from "zod";
+/**
+* Task status enum
+*/
+declare const TaskStatusEnum: unknown;
+type TaskStatus = z7.infer<typeof TaskStatusEnum>;
+/**
+* Task priority enum
+*/
+declare const TaskPriorityEnum: unknown;
+type TaskPriority = z7.infer<typeof TaskPriorityEnum>;
+/**
+* Action type for task operations
+*/
+declare const ActionTypeEnum: unknown;
+type ActionType = z7.infer<typeof ActionTypeEnum>;
+/**
+* Task entity
+*/
+interface Task {
+	id: number;
+	title: string;
+	description: string;
+	status: TaskStatus;
+	priority: TaskPriority;
+	progress: number;
+	current_status: string;
+	goals_and_expected_deliverables: string;
+	parent_task_id?: number;
+	createdAt: string;
+	updatedAt: string;
+	due_date?: string;
+	tags?: string[];
+}
+/**
+* TaskOperation entity
+* 
+* 记录任务的操作历史，每个操作关联到一个 sessionId
+*/
+interface TaskOperation {
+	id: number;
+	taskId: number;
+	sessionId: string;
+	actionType: ActionType;
+	actionTitle: string;
+	actionDescription: string;
+	timestamp: string;
+	mdPath?: string;
+}
+/**
+* TaskTag entity
+* 
+* Tag 池中的单个 Tag
+*/
+interface TaskTag {
+	id: number;
+	name: string;
+	createdAt: string;
+	taskCount: number;
+}
+interface CreateTaskOptions {
+	title: string;
+	description?: string;
+	priority?: TaskPriority;
+	parent_task_id?: number;
+	goals_and_expected_deliverables?: string;
+	due_date?: string;
+	tags?: string[];
+	sessionId: string;
+}
+interface UpdateTaskOptions {
+	title?: string;
+	description?: string;
+	status?: TaskStatus;
+	priority?: TaskPriority;
+	progress?: number;
+	current_status?: string;
+	goals_and_expected_deliverables?: string;
+	due_date?: string;
+	tags?: string[];
+}
+interface CreateOperationOptions {
+	taskId: number;
+	sessionId: string;
+	actionType: ActionType;
+	actionTitle: string;
+	actionDescription?: string;
+	mdPath?: string;
+}
+/**
+* @fileoverview Task Hook Points - Hook 点常量定义
+* 
+* 定义 Task Component 生命周期中的所有 Hook 点
+*/
+declare const TaskHookPoints: {
+	/** 创建 Task 前 - 可干预 options */
+	readonly BEFORE_CREATE: "task:before.create";
+	/** 创建 Task 后 - 观察或触发副作用 */
+	readonly AFTER_CREATE: "task:after.create";
+	/** 更新 Task 前 - 可干预 options */
+	readonly BEFORE_UPDATE: "task:before.update";
+	/** 更新 Task 后 - 观察变更 */
+	readonly AFTER_UPDATE: "task:after.update";
+	/** 删除 Task 前 - 观察 */
+	readonly BEFORE_DELETE: "task:before.delete";
+	/** 删除 Task 后 - 清理关联资源 */
+	readonly AFTER_DELETE: "task:after.delete";
+	/** 委派任务前 - 可干预 prompt、参数 */
+	readonly DELEGATE_BEFORE: "task:delegate:before";
+	/** 委派任务后 - 观察结果 */
+	readonly DELEGATE_AFTER: "task:delegate:after";
+	/** 创建操作记录前 - 可干预 options */
+	readonly OPERATION_BEFORE_CREATE: "task:operation:before.create";
+	/** 创建操作记录后 - 观察或触发副作用 */
+	readonly OPERATION_AFTER_CREATE: "task:operation:after.create";
+};
+/**
+* Task Hook 点类型
+*/
+type TaskHookPoint = typeof TaskHookPoints[keyof typeof TaskHookPoints];
+interface ListTagsOptions {
+	limit?: number;
+	offset?: number;
+	orderBy?: "count" | "name" | "created_at";
+}
+interface SearchTagsOptions {
+	query: string;
+	limit?: number;
+}
+interface TagService {
+	/**
+	* 创建 Tag（如果已存在则返回现有 Tag）
+	*/
+	createTag(name: string): Promise<TaskTag>;
+	/**
+	* 获取 Tag by ID
+	*/
+	getTag(id: number): Promise<TaskTag | undefined>;
+	/**
+	* 获取 Tag by Name
+	*/
+	getTagByName(name: string): Promise<TaskTag | undefined>;
+	/**
+	* 列出所有 Tag
+	*/
+	listTags(options?: ListTagsOptions): Promise<TaskTag[]>;
+	/**
+	* 搜索 Tag（模糊匹配）
+	*/
+	searchTags(options: SearchTagsOptions): Promise<TaskTag[]>;
+	/**
+	* 删除 Tag（同时删除所有关联）
+	*/
+	deleteTag(id: number): Promise<boolean>;
+	/**
+	* 给 Task 添加 Tags
+	*/
+	addTagsToTask(taskId: number, tagIds: number[]): Promise<void>;
+	/**
+	* 从 Task 移除 Tags
+	*/
+	removeTagsFromTask(taskId: number, tagIds: number[]): Promise<void>;
+	/**
+	* 获取 Task 的所有 Tags
+	*/
+	getTagsForTask(taskId: number): Promise<TaskTag[]>;
+	/**
+	* 根据 Tag 名称获取关联的 Task IDs
+	*/
+	getTaskIdsByTags(tagNames: string[]): Promise<number[]>;
+	/**
+	* 根据关键词列表搜索 Task（检索 tags、description、goals、operations）
+	* 这是新的核心检索方法
+	*/
+	searchTasksByKeywords(keywords: string[], options?: {
+		limit?: number;
+		excludeTaskId?: number;
+	}): Promise<Task[]>;
+	/**
+	* 根据关键词查找类似 Task（排除自身，按相关性排序）
+	* 这是新的核心检索方法
+	*/
+	findSimilarTasksByKeywords(keywords: string[], options?: {
+		limit?: number;
+		excludeTaskId?: number;
+	}): Promise<Task[]>;
+	/**
+	* 同步 Tags 到 Task（根据 tag 名称列表）
+	* - 查找或创建 Tag
+	* - 更新关联关系
+	* - 更新 task.tags JSON 字段
+	*/
+	syncTagsToTask(taskId: number, tagNames: string[]): Promise<void>;
+	/**
+	* 查找类似 Task（基于 Tag 匹配度）- 原始实现，保留兼容
+	* @deprecated 使用 findSimilarTasksByKeywords 代替
+	*/
+	findSimilarTasks(taskId: number, limit?: number): Promise<Task[]>;
+	/**
+	* 根据关键词搜索 Task（标题 + 描述）- 原始实现，保留兼容
+	* @deprecated 使用 searchTasksByKeywords 代替
+	*/
+	searchTasks(query: string, limit?: number): Promise<Task[]>;
+}
+interface DelegateToolResult {
+	tool: Tool;
+	backgroundTaskManager: BackgroundTaskManager;
+}
+interface BackgroundTask {
+	id: string;
+	subSessionId: string;
+	parentSessionId: string;
+	description: string;
+	subagentType: string;
+	status: "pending" | "running" | "completed" | "failed" | "timeout" | "stopped";
+	createdAt: number;
+	startedAt?: number;
+	completedAt?: number;
+	result?: string;
+	error?: string;
+	progress?: number;
+	progressMessage?: string;
+	abortController?: AbortController;
+	taskId?: number;
+}
+interface CreateBackgroundTaskOptions {
+	parentSessionId: string;
+	description: string;
+	prompt: string;
+	subagentType: string;
+	timeout?: number;
+	cleanup?: "delete" | "keep";
+	taskId?: number;
+}
+/**
+* Background Task Manager (简化版)
+* 
+* 管理后台任务的创建、执行、状态跟踪
+* 支持 EnvEvent 发布
+*/
+declare class BackgroundTaskManager {
+	private env;
+	private tasks;
+	private progressTimers;
+	private abortControllers;
+	constructor(env: any);
+	/**
+	* Get SessionComponent from env
+	*/
+	private getSessionComponent;
+	createTask(options: CreateBackgroundTaskOptions): Promise<{
+		taskId: string;
+		subSessionId: string;
+	}>;
+	private executeTask;
+	private executeWithAbort;
+	/**
+	* Start progress reporter for a task
+	*/
+	private startProgressReporter;
+	/**
+	* Stop progress reporter for a task
+	*/
+	private stopProgressReporter;
+	/**
+	* Publish an event to the environment
+	*/
+	private publishEvent;
+	stopTask(taskId: string): {
+		success: boolean;
+		task?: BackgroundTask;
+		message: string;
+	};
+	getTask(taskId: string): BackgroundTask | undefined;
+	listTasks(): BackgroundTask[];
+	/**
+	* Dispose and cleanup all resources
+	* Call this when shutting down to prevent process from hanging
+	*/
+	dispose(): void;
+}
+/**
+* Task Create Hook Context
+* 
+* 触发时机：createTask() 方法调用后，实际创建前
+* 
+* Plugin 可直接修改 options 来干预创建行为
+*/
+interface TaskCreateContext {
+	/** 创建选项（Plugin 可直接修改） */
+	options: CreateTaskOptions;
+	/** Session ID */
+	sessionId: string;
+	/** Tag 服务引用 */
+	tagService: TagService;
+}
+/**
+* Task Create Result Hook Context
+* 
+* 触发时机：Task 创建成功后
+* 
+* Plugin 可在此 Hook 中：
+* - 同步 Tag 到数据库
+* - 创建关联资源
+* - 发送通知
+*/
+interface TaskCreateResultContext {
+	/** 创建后的 Task（已包含生成 ID） */
+	task: Task;
+	/** Session ID */
+	sessionId: string;
+	/** Tag 服务引用 */
+	tagService: TagService;
+}
+/**
+* Task Update Hook Context
+* 
+* 触发时机：updateTask() 方法调用后，实际更新前
+* 
+* Plugin 可直接修改 options 来干预更新行为
+*/
+interface TaskUpdateContext {
+	/** Task ID */
+	id: number;
+	/** 更新选项（Plugin 可直接修改） */
+	options: UpdateTaskOptions;
+	/** Tag 服务引用 */
+	tagService: TagService;
+}
+/**
+* Task Update Result Hook Context
+* 
+* 触发时机：Task 更新成功后
+*/
+interface TaskUpdateResultContext {
+	/** 更新后的 Task */
+	task: Task;
+	/** 变更的字段 */
+	changes: Partial<UpdateTaskOptions>;
+	/** Tag 服务引用 */
+	tagService: TagService;
+}
+/**
+* Task Delete Hook Context
+* 
+* 触发时机：deleteTask() 方法调用后，实际删除前
+*/
+interface TaskDeleteContext {
+	/** Task ID */
+	id: number;
+}
+/**
+* Task Delete Result Hook Context
+* 
+* 触发时机：Task 删除成功后
+* 
+* 注意：删除成功后无法获取 Task 的详细信息
+*/
+interface TaskDeleteResultContext {
+	/** 被删除的 Task ID */
+	id: number;
+	/** 是否成功删除 */
+	deleted: boolean;
+}
+/**
+* Delegate Before Hook Context
+* 
+* 触发时机：delegate_task 工具执行前
+* 
+* Plugin 可直接修改 prompt 来注入上下文
+*/
+interface TaskDelegateContext {
+	/** 关联的 Task ID */
+	taskId?: number;
+	/** 执行提示词（Plugin 可直接修改以注入上下文） */
+	prompt: string;
+	/** SubAgent 类型 */
+	subagentType: string;
+	/** 是否后台执行 */
+	background: boolean;
+	/** 超时时间 */
+	timeout?: number;
+	/** 清理策略 */
+	cleanup?: "delete" | "keep";
+	/** 执行原因 */
+	reason?: string;
+	/** Tag 服务引用 */
+	tagService: TagService;
+}
+/**
+* Delegate After Hook Context
+* 
+* 触发时机：delegate_task 工具执行后
+*/
+interface TaskDelegateResultContext {
+	/** 关联的 Task ID */
+	taskId?: number;
+	/** 执行结果 */
+	result: DelegateToolResult;
+	/** Tag 服务引用 */
+	tagService: TagService;
+}
+/**
+* Operation Create Hook Context
+* 
+* 触发时机：createOperation() 方法调用后，实际创建前
+* 
+* Plugin 可直接修改 options 来干预操作记录创建
+*/
+interface TaskOperationCreateContext {
+	/** 创建选项（Plugin 可直接修改） */
+	options: CreateOperationOptions;
+}
+/**
+* Operation Create Result Hook Context
+* 
+* 触发时机：操作记录创建成功后
+*/
+interface TaskOperationCreateResultContext {
+	/** 创建后的操作记录 */
+	operation: TaskOperation;
+}
+/**
+* TaskHookContextMap - Hook 点与 Context 类型的映射
+* 
+* 用于 Hook 执行时类型安全的 Context 获取
+*/
+interface TaskHookContextMap {
+	"task:before.create": TaskCreateContext;
+	"task:after.create": TaskCreateResultContext;
+	"task:before.update": TaskUpdateContext;
+	"task:after.update": TaskUpdateResultContext;
+	"task:before.delete": TaskDeleteContext;
+	"task:after.delete": TaskDeleteResultContext;
+	"task:delegate:before": TaskDelegateContext;
+	"task:delegate:after": TaskDelegateResultContext;
+	"task:operation:before.create": TaskOperationCreateContext;
+	"task:operation:after.create": TaskOperationCreateResultContext;
+}
+export { TaskUpdateResultContext, TaskUpdateContext, TaskOperationCreateResultContext, TaskOperationCreateContext, TaskHookPoints, TaskHookPoint, TaskHookContextMap, TaskDeleteResultContext, TaskDeleteContext, TaskDelegateResultContext, TaskDelegateContext, TaskCreateResultContext, TaskCreateContext };