@ai-setting/roy-agent-core 1.7.51 → 1.7.53

package/dist/env/tool/tool-component.d.ts

@@ -0,0 +1,242 @@
+import { BaseComponent, type ComponentConfig } from "../component";
+import type { Tool, ToolContext, ToolResult, ToolResultMetadata, ToolExecuteRequest, ToolListFilter, ToolRegistration } from "./types";
+import type { ConfigComponent } from "../../config/config-component";
+/**
+ * 设置 ConfigComponent 实例
+ */
+export declare function setToolConfigComponent(component: any): void;
+/**
+ * 获取工具输出最大长度配置（支持热更新）
+ *
+ * 配置路径: tool.execution.maxOutputSize
+ * 默认值: 5120 (5KB) — 与 LLM Token 窗口匹配，避免工具输出过大占用上下文
+ *
+ * @returns 最大输出大小（字节），0 表示不限制
+ */
+export declare function getMaxOutputSize(): number;
+/**
+ * 截断工具输出
+ *
+ * v5.0: 移除了 v4.6.0 的 ITERATION_TASK_TRIGGER_BEGIN/END marker 识别逻辑。
+ *       AutoTaskPlugin v5.0 不再向 tool result 注入 metadata，
+ *       而是推送 user 消息，因此 truncateOutput 不需要识别任何 plugin-specific marker。
+ *       按原行为截断：保留前 maxSize 字符 + 添加截断通知。
+ *
+ * @param output 原始输出
+ * @param maxSize 最大输出大小
+ * @returns 截断后的输出和元数据更新
+ */
+export declare function truncateOutput(output: string, maxSize: number): {
+    output: string;
+    metadata: Partial<ToolResultMetadata>;
+};
+/**
+ * Per-tool default overrides for maxOutputSize.
+ *
+ * Most tools share the global `tool.execution.maxOutputSize` limit (5KB by
+ * default) — but a handful of tools routinely produce much larger outputs and
+ * benefit from a larger ceiling. The map below gives those tools a sensible
+ * per-tool cap while keeping the default conservative for everything else.
+ *
+ * The map is intentionally small. New entries should be added only with a
+ * clear reason (e.g. "always reads full files of any size").
+ */
+export declare const TOOL_MAX_OUTPUT_SIZE_OVERRIDES: Record<string, number>;
+/**
+ * Look up the effective maxOutputSize for a given tool. Resolution order:
+ *   1. explicit `overrideMaxSize` (used by tests & Power Users)
+ *   2. `TOOL_MAX_OUTPUT_SIZE_OVERRIDES[toolName]`
+ *   3. global `tool.execution.maxOutputSize` via config component
+ *   4. fallback default 5120
+ */
+export declare function getMaxOutputSizeForTool(toolName?: string, overrideMaxSize?: number): number;
+/**
+ * Inline truncation helper for execution paths that bypass `ToolComponent.execute()`.
+ *
+ * Two production code paths currently call `tool.execute()` directly instead of
+ * routing through `ToolComponent`:
+ *   (A) `AgentComponent.executeTool` `isExtraTool` branch
+ *   (B) `AgentComponent.executeTool` fallback branch (no ToolComponent)
+ *
+ * Each of those paths previously skipped truncation entirely. This helper replicates
+ * the truncation step that `ToolComponent.execute()` performs, so the two bypass
+ * paths re-enter the same safety net without restructuring the call sites.
+ *
+ * Resolution precedence for the cap:
+ *   1. `maxSize` argument (explicit call-site override, wins)
+ *   2. `TOOL_MAX_OUTPUT_SIZE_OVERRIDES[toolName]` if `toolName` is supplied
+ *   3. global `tool.execution.maxOutputSize` via config component
+ *   4. fallback default 5120
+ *
+ * Tool authors can also opt out of truncation entirely by setting
+ * `metadata.skipTruncation === true` on their Tool. When the optional
+ * `tool` argument is supplied and carries that flag, the helper returns
+ * a shallow clone of the source result without touching `output` or
+ * `error` — mirroring the central `ToolComponent.execute()` short-circuit.
+ * WorkflowToolNode no longer calls this helper (it deliberately preserves
+ * raw payloads for the workflow data layer); only the two AgentComponent
+ * bypass paths above use it now.
+ *
+ * `truncateOutputInline` returns a new ToolResult (the input is shallow-cloned)
+ * to avoid surprising downstream mutators that reuse the original object.
+ */
+export declare function truncateOutputInline(result: ToolResult, maxSize?: number, overrideMaxSize?: number, toolName?: string, tool?: Tool): ToolResult;
+/**
+ * ToolComponent 配置选项（通过 options 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface ToolComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "TOOL"） */
+    envPrefix?: string;
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<ToolComponentConfig>;
+}
+/**
+ * Tool Hook 上下文
+ */
+export interface ToolHookContext {
+    tool?: Tool;
+    args?: Record<string, unknown>;
+    context?: ToolContext;
+    result?: ToolResult;
+}
+/**
+ * ToolComponent 配置
+ */
+export interface ToolComponentConfig {
+    /** 工具目录 */
+    toolsDir?: string;
+    /** 内置工具 */
+    builtInTools?: {
+        enabled: boolean;
+        loadAll?: boolean;
+        names?: string[];
+    };
+    /** 沙箱配置 */
+    sandbox?: {
+        enabled: boolean;
+        type: "native" | "docker";
+        defaultConfig?: Record<string, unknown>;
+    };
+    /** 执行配置 */
+    execution?: {
+        timeout?: number;
+        maxConcurrency?: number;
+    };
+}
+/**
+ * ToolComponent
+ * 工具管理核心组件
+ */
+export declare class ToolComponent extends BaseComponent {
+    readonly name = "tool";
+    readonly version = "1.0.0";
+    private registry;
+    private validator;
+    private config?;
+    /** ConfigComponent 用于配置管理 */
+    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 - 直接配置对象（最高）
+     *
+     * 实现步骤：
+     * 1. 使用 registerComponent(TOOL_CONFIG_REGISTRATION) 注册配置
+     * 2. 使用 load("tool") 加载已注册的配置
+     * 3. 设置 TOOL_DEFAULTS 默认值
+     * 4. 处理环境变量后备方案
+     * 5. 处理 config 对象（最高优先级）
+     */
+    private registerConfig;
+    /**
+     * 将配置对象展平为点号路径
+     */
+    private flattenConfig;
+    /**
+     * 注册配置热更新监听
+     */
+    private registerConfigWatcher;
+    /**
+     * 处理配置变更
+     */
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    /**
+     * 停止组件
+     */
+    onStop(): Promise<void>;
+    /**
+     * 注册工具
+     */
+    register(tool: Tool, source?: ToolRegistration["source"]): void;
+    /**
+     * 批量注册工具
+     */
+    registerMany(tools: Tool[], source?: ToolRegistration["source"]): void;
+    /**
+     * 注销工具
+     */
+    unregister(name: string): boolean;
+    /**
+     * 获取工具
+     */
+    getTool(name: string): Tool | undefined;
+    /**
+     * 列出工具
+     */
+    listTools(filter?: ToolListFilter): Tool[];
+    /**
+     * 获取工具数量
+     */
+    getToolCount(): number;
+    /**
+     * 检查工具是否存在
+     */
+    hasTool(name: string): boolean;
+    /**
+     * 按分类获取工具
+     */
+    getToolsByCategory(category: string): Tool[];
+    /**
+     * 执行工具
+     *
+     * errorIf：与 AgentComponent.executeTool 对齐 —— 只有「工具不存在 / 被禁用」
+     * 才标 ERROR（配置错误），工具自身的运行时失败保持 OK 以免噪音淹没真问题。
+     */
+    execute(request: ToolExecuteRequest): Promise<ToolResult>;
+    /**
+     * 加载内置工具
+     */
+    loadBuiltInTools(): Promise<void>;
+    /**
+     * 获取 Tool Hook 点列表
+     */
+    getHookPoints(): string[];
+}

package/dist/env/tool/tool-config-registration.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Tool Component 配置注册
+ *
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+import type { ComponentRegistration } from "../../config/config-component";
+/**
+ * Tool Component 默认配置值
+ *
+ * 注意：键使用完整格式（带 "tool." 前缀），在 registerConfig 中手动设置
+ */
+export declare const TOOL_DEFAULTS: Record<string, unknown>;
+/**
+ * Tool Component 配置注册常量
+ *
+ * 定义了所有 Tool 相关的配置项和来源
+ */
+export declare const TOOL_CONFIG_REGISTRATION: ComponentRegistration;

package/dist/env/tool/types.d.ts

@@ -0,0 +1,274 @@
+import { z, ZodType, ZodError } from "zod";
+/**
+ * 沙箱配置
+ */
+export 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>;
+    };
+}
+/**
+ * 工具执行上下文
+ */
+export 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;
+}
+/**
+ * 工具结果元数据
+ */
+export interface ToolResultMetadata {
+    /** 执行时间（毫秒） */
+    execution_time_ms: number;
+    /** 输出大小（字节） */
+    output_size?: number;
+    /** 标准输出 */
+    stdout?: string;
+    /** 标准错误 */
+    stderr?: string;
+    /** 退出码 */
+    exit_code?: number;
+    /** Token 使用量 */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens?: number;
+    };
+    /** 输出是否被截断 */
+    output_truncated?: boolean;
+    /** 原始输出大小（截断前，单位：字符） */
+    original_output_size?: number;
+    /** 截断后输出大小（单位：字符） */
+    truncated_output_size?: number;
+    /** 额外元数据 */
+    [key: string]: unknown;
+}
+/**
+ * 工具执行结果
+ */
+export interface ToolResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 输出内容 */
+    output: string | Record<string, unknown>;
+    /** 错误信息 */
+    error?: string;
+    /** 结果元数据 */
+    metadata?: ToolResultMetadata;
+}
+/**
+ * 工具元数据
+ */
+export interface ToolMetadata {
+    /** 分类 */
+    category?: string;
+    /** 标签 */
+    tags?: string[];
+    /** 版本 */
+    version?: string;
+    /** 作者 */
+    author?: string;
+    /** 是否实验性 */
+    experimental?: boolean;
+    /** MCP 工具信息（MCP adapter 使用） */
+    mcpTool?: {
+        originalName: string;
+        originalDescription: string;
+        inputSchema?: unknown;
+    };
+    /**
+     * 允许使用该工具的 agent 名称白名单（2026-07 新增）。
+     *
+     * 设计目标：让某些"工具仅对特定 agent 可见"，例如：
+     * - `query_background_process`：只给 default 接待员 agent 使用（因为只有它会委托任务）
+     * - 其他 agent（roy / strict-task-agent / explore 等）看不到这个工具，行为不变
+     *
+     * 匹配规则（listTools filter `allowedAgent` 时）：
+     * - `undefined` 或空数组：所有 agent 可见（向后兼容）
+     * - 非空数组：当 `allowedAgent` 命中数组中任一元素时可见
+     * - 字符串精确匹配，大小写敏感
+     *
+     * 注意：这是**工具自身的可见性声明**，与 agent 配置中的 `allowedTools`（白名单）、
+     * `deniedTools`（黑名单）是**正交**的。两者共同决定最终可见工具集：
+     *   1. 工具声明自己允许的 agent（这里）
+     *   2. agent 自己声明 allowedTools / deniedTools
+     *   3. ToolComponent.listTools({ allowedAgent }) 一次过滤；agent-component 再做 allowedTools/deniedTools 二次过滤
+     */
+    allowedAgentTypes?: string[];
+    /**
+     * Whether this tool explicitly opts out of string output truncation.
+     *
+     * `true` preserves the complete string output, including the temp-file
+     * fallback path in `ToolComponent.execute()`. Use this for tools whose
+     * output IS the deliverable (e.g. metadata readers like `workflow_get`):
+     * silently truncating their payload defeats the user's intent.
+     *
+     * `false` or `undefined` preserves the default 5KB cap and truncation
+     * notice for backward compatibility.
+     */
+    skipTruncation?: boolean;
+}
+/**
+ * 工具沙箱配置
+ */
+export interface ToolSandboxConfig {
+    /** 是否启用沙箱 */
+    enabled: boolean;
+    /** 沙箱配置 */
+    config?: Partial<SandboxConfig>;
+}
+/**
+ * 工具权限配置
+ */
+export interface ToolPermissionConfig {
+    /** 是否需要用户确认 */
+    requireConfirmation?: boolean;
+    /** 权限级别 */
+    level?: "safe" | "dangerous" | "critical";
+}
+/**
+ * 工具信息
+ */
+export 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<ToolResult>;
+    /** 参数验证错误格式化（可选） */
+    formatValidationError?: (error: ZodError) => string;
+    /** 沙箱配置 */
+    sandbox?: ToolSandboxConfig;
+    /** 权限配置 */
+    permission?: ToolPermissionConfig;
+    /** 工具元数据 */
+    metadata?: ToolMetadata;
+}
+/**
+ * 工具类型别名
+ */
+export type Tool = ToolInfo;
+/**
+ * 工具注册来源
+ */
+export type ToolSource = "built-in" | "plugin" | "dynamic";
+/**
+ * 工具注册信息
+ */
+export interface ToolRegistration {
+    /** 工具实例 */
+    tool: Tool;
+    /** 注册时间 */
+    registeredAt: number;
+    /** 注册来源 */
+    source: ToolSource;
+    /** 是否启用 */
+    enabled: boolean;
+}
+/**
+ * 工具执行请求
+ */
+export interface ToolExecuteRequest {
+    /** 工具名称 */
+    name: string;
+    /** 参数 */
+    args: Record<string, unknown>;
+    /** 上下文 */
+    context: ToolContext;
+    /** 是否跳过 Hook */
+    skipHooks?: boolean;
+}
+/**
+ * 工具列表过滤器
+ */
+export interface ToolListFilter {
+    /** 按名称过滤（支持 glob） */
+    name?: string | string[];
+    /** 按分类过滤 */
+    category?: string;
+    /** 按标签过滤 */
+    tags?: string[];
+    /** 按来源过滤 */
+    source?: ToolSource;
+    /** 只返回启用的工具 */
+    enabledOnly?: boolean;
+    /** 排除的工具 */
+    exclude?: string[];
+    /**
+     * 按 agent 名称过滤（2026-07 新增，工具级 agent-可见性过滤）
+     *
+     * 工作原理：
+     * - 若 tool.metadata.allowedAgentTypes 为 undefined 或 [] → 该工具对所有 agent 可见
+     * - 若 tool.metadata.allowedAgentTypes 非空 → 仅当 allowedAgent 命中数组中任一字符串时返回
+     * - 字符串精确匹配，大小写敏感
+     *
+     * 调用方传入 agent.name（如 "default"、"roy"、"strict-task-agent"），
+     * 通常由 AgentComponent.getAvailableTools(agent) 内部传入。
+     */
+    allowedAgent?: string;
+}
+/**
+ * 参数验证结果
+ */
+export interface ValidationResult {
+    /** 是否成功 */
+    success: boolean;
+    /** 验证后的数据 */
+    data?: Record<string, unknown>;
+    /** 错误信息 */
+    error?: string;
+}

package/dist/env/tool/validator.d.ts

@@ -0,0 +1,14 @@
+import type { Tool, ValidationResult } from "./types";
+/**
+ * 工具参数验证器
+ */
+export declare class ToolValidator {
+    /**
+     * 验证参数
+     */
+    validate(tool: Tool, args: Record<string, unknown>): Promise<ValidationResult>;
+    /**
+     * 格式化 Zod 错误
+     */
+    private formatError;
+}