@ai-setting/roy-agent-cli 1.3.15 → 1.3.16

package/dist/core/src/env/workflow/nodes/agent-node.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @fileoverview AgentNode - Delegate work to an AI agent
+ *
+ * AgentNode delegates work to an AI agent with task description and context.
+ */
+import { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+import type { SessionComponent } from '../../session/session-component';
+/**
+ * Agent 注册配置
+ */
+export interface AgentRegistrationConfig {
+    /** Agent 类型 */
+    type?: string;
+    /** 系统提示词 */
+    systemPrompt?: string;
+    /** 模型名称 */
+    model?: string;
+    /** 最大迭代次数 */
+    maxIterations?: number;
+    /** 允许的工具列表 */
+    allowedTools?: string[];
+    /** 禁止的工具列表 */
+    deniedTools?: string[];
+}
+/**
+ * AgentRunner 接口
+ *
+ * 用于运行 AI Agent 的接口
+ */
+export interface AgentRunner {
+    /**
+     * 运行 Agent
+     * @param config Agent 配置
+     * @param resumeOptions 可选的恢复选项（用于恢复暂停的 agent）
+     * @returns Agent 执行结果
+     */
+    run(config: AgentConfig, resumeOptions?: {
+        userResponse?: string;
+        agentSessionId?: string;
+    }): Promise<AgentResult>;
+    /**
+     * 恢复暂停的 Agent
+     *
+     * @param agentSessionId Agent session ID
+     * @param userResponse 用户的响应
+     * @param config 原始的 agent 配置
+     * @returns Agent 执行结果
+     */
+    resumeAgent?(agentSessionId: string, userResponse: string, config: AgentConfig): Promise<AgentResult>;
+    /**
+     * 获取当前 agent session ID
+     */
+    getCurrentAgentSessionId?(): string | undefined;
+    /**
+     * 设置 SessionComponent
+     */
+    setSessionComponent?(sessionComponent: SessionComponent): void;
+    /**
+     * 获取待恢复的 session 信息
+     */
+    getPendingSession?(agentSessionId: string): {
+        agentSessionId: string;
+        nodeId: string;
+        runId: string;
+        createdAt: number;
+    } | undefined;
+    /**
+     * 注册 Agent（如果不存在）
+     */
+    registerAgent?(name: string, config: AgentRegistrationConfig): void;
+    /**
+     * 检查 Agent 是否已注册
+     */
+    hasAgent?(name: string): boolean;
+}
+/**
+ * Agent 配置
+ */
+export interface AgentConfig {
+    /** Agent 类型 */
+    type: string;
+    /** Prompt（任务描述） */
+    prompt: string;
+    /** 可选配置 */
+    options?: {
+        /** 超时时间（毫秒） */
+        timeout?: number;
+        /** 模型名称 */
+        model?: string;
+        /** 允许的工具列表（用于限制 agent 可用的工具） */
+        allowedTools?: string[];
+        /** 拒绝的工具列表 */
+        deniedTools?: string[];
+    };
+    /** Workflow 历史消息（来自前置 agent 节点） */
+    workflowHistory?: Array<{
+        role: 'user' | 'assistant' | 'tool';
+        content: string;
+        toolCallId?: string;
+        toolName?: string;
+        nodeId?: string;
+    }>;
+    /** 节点 ID（用于 history 标记） */
+    nodeId?: string;
+    /** Agent sub-session ID（用于 HiL resume） */
+    agentSessionId?: string;
+}
+/**
+ * Agent 执行结果
+ */
+export interface AgentResult {
+    /** Agent 输出 */
+    output: unknown;
+    /** 执行元数据 */
+    metadata?: {
+        /** 消耗的 token 数量 */
+        tokens?: number;
+        /** 执行耗时（毫秒） */
+        duration?: number;
+        /** 其他元数据 */
+        [key: string]: unknown;
+    };
+    /** 生成的消息列表（用于 workflow history 累积） */
+    messages?: Array<{
+        role: 'user' | 'assistant' | 'tool';
+        content: string;
+        toolCallId?: string;
+        toolName?: string;
+        nodeId?: string;
+    }>;
+}
+/**
+ * AgentNode 类
+ *
+ * 委托 AI Agent 执行任务的节点类型
+ */
+export declare class AgentNode implements Node {
+    private definition;
+    private agentRunner;
+    /** 节点类型 */
+    readonly type = "agent";
+    /** 节点 ID */
+    readonly id: string;
+    /**
+     * 创建 AgentNode
+     * @param definition 节点定义
+     * @param agentRunner Agent 运行器
+     */
+    constructor(definition: NodeDefinition, agentRunner: AgentRunner);
+    /**
+     * 执行 AgentNode
+     *
+     * 流程：
+     * 1. 从 definition.config 获取 agent 配置
+     * 2. 解析 prompt 模板（可能引用前置节点输出）
+     * 3. 通过 agentRunner 运行 agent
+     * 4. 返回 agent 结果
+     *
+     * @param context 执行上下文
+     * @returns 执行结果
+     */
+    execute(context: NodeExecutionContext): Promise<NodeExecutionResult>;
+    /**
+     * 创建 agent sub-session
+     *
+     * Sub-session 用于存储 agent 的对话历史，支持 human-in-loop resume
+     */
+    private createAgentSubSession;
+    /**
+     * 解析模板字符串
+     *
+     * 支持以下模板变量：
+     * - {{input.key}} - 从 context.input 获取值
+     * - {{nodes.nodeId}} - 从前置节点输出获取值
+     * - {{nodes.nodeId.output}} - 从前置节点输出获取值
+     * - {{nodes.nodeId.output.path}} - 从前置节点输出的嵌套路径获取值
+     *
+     * @param template 模板字符串
+     * @param context 执行上下文
+     * @returns 解析后的字符串
+     */
+    private resolveTemplate;
+    /**
+     * Convert a value to string for template replacement.
+     * - If value is undefined, return the original template
+     * - If value is a string, return it directly
+     * - If value is null, return 'null'
+     * - If value is an object or array, serialize to JSON
+     *
+     * @param value - The value to stringify
+     * @param originalTemplate - The original template string (returned if value is undefined)
+     * @returns String representation of the value
+     */
+    private stringifyValue;
+    /**
+     * 从包装格式中提取实际输出值
+     *
+     * 处理以下格式：
+     * - AgentNode: { result, metadata } -> 返回 result
+     * - DecoratorNode: { success, output, ... } -> 返回 output
+     * - 其他格式直接返回
+     *
+     * @param value 原始值
+     * @returns 提取后的值
+     */
+    private extractFromWrapper;
+    /**
+     * 获取嵌套对象的值
+     *
+     * @param obj 对象
+     * @param path 属性路径
+     * @returns 值或 undefined
+     */
+    private getNestedValue;
+}
+export { AgentNode as default };
+//# sourceMappingURL=agent-node.d.ts.map

package/dist/core/src/env/workflow/nodes/agent-node.js

@@ -0,0 +1,419 @@
+/**
+ * @fileoverview AgentNode - Delegate work to an AI agent
+ *
+ * AgentNode delegates work to an AI agent with task description and context.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { AskUserError } from "../types/workflow-hil.js";
+import { TracedAs } from "../../log-trace/decorator.js";
+// ============================================================================
+// AgentNode Implementation
+// ============================================================================
+/**
+ * AgentNode 类
+ *
+ * 委托 AI Agent 执行任务的节点类型
+ */
+export class AgentNode {
+    definition;
+    agentRunner;
+    /** 节点类型 */
+    type = 'agent';
+    /** 节点 ID */
+    id;
+    /**
+     * 创建 AgentNode
+     * @param definition 节点定义
+     * @param agentRunner Agent 运行器
+     */
+    constructor(definition, agentRunner) {
+        this.definition = definition;
+        this.agentRunner = agentRunner;
+        this.id = definition.id;
+    }
+    /**
+     * 执行 AgentNode
+     *
+     * 流程：
+     * 1. 从 definition.config 获取 agent 配置
+     * 2. 解析 prompt 模板（可能引用前置节点输出）
+     * 3. 通过 agentRunner 运行 agent
+     * 4. 返回 agent 结果
+     *
+     * @param context 执行上下文
+     * @returns 执行结果
+     */
+    async execute(context) {
+        const startTime = Date.now();
+        try {
+            // 1. 从配置中获取 agent 参数
+            const config = this.definition.config || {};
+            const agentType = config.agent_type || 'general';
+            const promptTemplate = config.prompt || '';
+            const options = config.options || {};
+            // 2. 解析 prompt 模板
+            const resolvedPrompt = this.resolveTemplate(promptTemplate, context);
+            // 3. 自动注册 agent（如果不存在）
+            // 这样 workflow 定义中引用的 agent 类型会被自动注册，无需手动预注册
+            if (this.agentRunner.registerAgent && this.agentRunner.hasAgent) {
+                if (!this.agentRunner.hasAgent(agentType)) {
+                    this.agentRunner.registerAgent(agentType, {
+                        type: agentType,
+                        systemPrompt: config.system_prompt || `You are a ${agentType} agent.`,
+                        model: options.model,
+                    });
+                }
+            }
+            // 4. 检查是否需要恢复执行（从 pause 恢复时传递了 userResponse）
+            // 从 context 中获取恢复选项（由 engine.resumeNode 设置）
+            const userResponse = context.userResponse;
+            let agentSessionId = context.agentSessionId;
+            // 5. 如果不是恢复模式，创建 agent sub-session
+            // Sub-session 用于存储 agent 的对话历史，支持 resume
+            if (!userResponse && context.sessionComponent && !agentSessionId) {
+                agentSessionId = await this.createAgentSubSession(context);
+                // 将 agentSessionId 设置到 context 中，供后续使用（如 AskUserError）
+                // 注意：NodeExecutionContext 是引用类型，直接修改会生效
+                context.agentSessionId = agentSessionId;
+            }
+            // 6. 构建 AgentConfig
+            // 注意：添加 allowedTools: ['ask_user'] 确保 ask_user 工具在 workflow agent 上下文中可用
+            // 这样 ask_user 只在 workflow agent 中可用，不影响 default agent 和 sub agent
+            const agentConfig = {
+                type: agentType,
+                prompt: resolvedPrompt,
+                options: {
+                    timeout: options.timeout,
+                    model: options.model,
+                    // 添加 ask_user 到 allowedTools，确保 workflow agent 可以调用此工具
+                    allowedTools: ['ask_user'],
+                },
+                // 传递 workflow history（来自前置 agent 节点）
+                workflowHistory: context.workflowHistory,
+                // 传递节点信息（用于 history 标记）
+                nodeId: this.definition.id,
+                // 传递 agent sub-session ID
+                agentSessionId,
+            };
+            // 如果有 userResponse，说明是从 pause 恢复的，应该传递给 agentRunner
+            const resumeOptions = userResponse
+                ? { userResponse, agentSessionId }
+                : undefined;
+            // 7. 运行 agent（传递 resumeOptions 如果是从 pause 恢复的）
+            const result = await this.agentRunner.run(agentConfig, resumeOptions);
+            // 8. 计算执行耗时
+            const duration = Date.now() - startTime;
+            // 9. 返回成功结果
+            return {
+                output: {
+                    result: result.output,
+                    metadata: result.metadata,
+                    // 返回 workflow history 供 WorkflowEngine 累积
+                    workflowHistory: result.messages,
+                },
+                error: undefined,
+                duration,
+            };
+        }
+        catch (error) {
+            // 检查是否是 AskUserError - 这是用于工作流暂停的特殊错误，需要向上传播
+            // 以便 Executor 能够正确处理暂停逻辑
+            if (error instanceof AskUserError) {
+                // 确保 AskUserError 携带 agentSessionId（如果有的话）
+                const contextAgentSessionId = context.agentSessionId;
+                if (contextAgentSessionId && !error.agentSessionId) {
+                    // 创建一个新的 AskUserError 携带 agentSessionId
+                    throw new AskUserError(error.runId, error.sessionId, error.nodeId, error.nodeType, error.query, contextAgentSessionId, error.timestamp);
+                }
+                throw error; // 重新抛出，让 Executor 处理
+            }
+            // 其他错误处理
+            const duration = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                output: undefined,
+                error: errorMessage,
+                duration,
+            };
+        }
+    }
+    /**
+     * 创建 agent sub-session
+     *
+     * Sub-session 用于存储 agent 的对话历史，支持 human-in-loop resume
+     */
+    async createAgentSubSession(context) {
+        const sessionComponent = context.sessionComponent;
+        if (!sessionComponent) {
+            return '';
+        }
+        const agentSessionId = `agent_${this.definition.id}_${Date.now()}`;
+        // 1. 创建 agent sub-session
+        await sessionComponent.create({
+            id: agentSessionId,
+            title: `Agent: ${this.definition.id}`,
+            metadata: {
+                type: 'agent',
+                parentSessionId: context.sessionId,
+                nodeId: this.definition.id,
+                workflowName: context.workflowName,
+            },
+        });
+        // 2. 更新 workflow session 的 metadata，添加 agentSessions 引用
+        const workflowSession = await sessionComponent.get(context.sessionId);
+        if (workflowSession) {
+            const metadata = workflowSession.metadata || {};
+            const agentSessions = metadata.agentSessions || [];
+            // 检查是否已经存在
+            const existingIndex = agentSessions.findIndex((s) => s.nodeId === this.definition.id);
+            if (existingIndex >= 0) {
+                agentSessions[existingIndex] = {
+                    nodeId: this.definition.id,
+                    sessionId: agentSessionId,
+                    status: 'active',
+                    createdAt: Date.now(),
+                };
+            }
+            else {
+                agentSessions.push({
+                    nodeId: this.definition.id,
+                    sessionId: agentSessionId,
+                    status: 'active',
+                    createdAt: Date.now(),
+                });
+            }
+            await sessionComponent.update(context.sessionId, {
+                metadata: {
+                    ...metadata,
+                    agentSessions,
+                },
+            });
+        }
+        return agentSessionId;
+    }
+    /**
+     * 解析模板字符串
+     *
+     * 支持以下模板变量：
+     * - {{input.key}} - 从 context.input 获取值
+     * - {{nodes.nodeId}} - 从前置节点输出获取值
+     * - {{nodes.nodeId.output}} - 从前置节点输出获取值
+     * - {{nodes.nodeId.output.path}} - 从前置节点输出的嵌套路径获取值
+     *
+     * @param template 模板字符串
+     * @param context 执行上下文
+     * @returns 解析后的字符串
+     */
+    resolveTemplate(template, context) {
+        if (!template) {
+            return '';
+        }
+        let resolved = template;
+        // 解析 input 变量: {{input.key}} 或 {{input.key.nested}}
+        resolved = resolved.replace(/\{\{input\.([^}]+)\}\}/g, (match, path) => {
+            const value = this.getNestedValue(context.input, path);
+            return this.stringifyValue(value, match);
+        });
+        // 解析 node 输出变量: {{nodes.nodeId}} 或 {{nodes.nodeId.output}} 或 {{nodes.nodeId.output.path}}
+        resolved = resolved.replace(/\{\{nodes\.([^}]+)\}\}/g, (match, path) => {
+            // 路径格式: nodeId 或 nodeId.output 或 nodeId.output.path
+            const segments = path.split('.');
+            const nodeId = segments[0];
+            // 从 previousOutputs 获取原始输出（尝试规范化匹配）
+            let nodeOutput = context.previousOutputs.get(nodeId);
+            if (nodeOutput === undefined) {
+                // 尝试规范化版本（hyphen <-> underscore）
+                const normalizedUnderscore = nodeId.replace(/-/g, '_');
+                const normalizedHyphen = nodeId.replace(/_/g, '-');
+                if (normalizedUnderscore !== nodeId) {
+                    nodeOutput = context.previousOutputs.get(normalizedUnderscore);
+                }
+                if (nodeOutput === undefined && normalizedHyphen !== nodeId) {
+                    nodeOutput = context.previousOutputs.get(normalizedHyphen);
+                }
+            }
+            if (nodeOutput === undefined) {
+                return match;
+            }
+            // 首先从包装格式中提取实际值
+            // 处理 DecoratorNode 格式: { success, output, ... } 和 AgentNode 格式: { result, metadata }
+            nodeOutput = this.extractFromWrapper(nodeOutput);
+            // 然后从提取后的值中获取嵌套路径
+            if (segments.length === 1) {
+                // 只有 nodeId，直接返回提取后的值
+                // 如果是对象，序列化为 JSON；如果是原始值，转为字符串
+                return this.stringifyValue(nodeOutput, match);
+            }
+            // 从嵌套路径获取（从 segments[1] 开始）
+            // 如果 segments[1] 是包装属性（"output"、"result"、"metadata"），跳过它因为 extractFromWrapper 已经提取了
+            let value = nodeOutput;
+            let startIndex = 1;
+            if (segments.length > 1 &&
+                (segments[1] === 'output' || segments[1] === 'result' || segments[1] === 'metadata')) {
+                startIndex = 2;
+            }
+            for (let i = startIndex; i < segments.length; i++) {
+                if (value === null || value === undefined) {
+                    return match;
+                }
+                value = value[segments[i]];
+            }
+            return this.stringifyValue(value, match);
+        });
+        // 解析裸 node 输出变量: {{nodeId}} 或 {{nodeId.output}} (不带 nodes. 前缀)
+        // 这需要放在 {{input.}} 和 {{nodes.}} 之后，以避免与它们冲突
+        resolved = resolved.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+            // 跳过已经是 input 或 nodes 开头的（已由前面的规则处理）
+            if (path.startsWith('input.') || path.startsWith('nodes.')) {
+                return match;
+            }
+            const segments = path.split('.');
+            const nodeId = segments[0];
+            // 从 previousOutputs 获取原始输出（尝试规范化匹配）
+            let nodeOutput = context.previousOutputs.get(nodeId);
+            if (nodeOutput === undefined) {
+                // 尝试规范化版本（hyphen <-> underscore）
+                const normalizedUnderscore = nodeId.replace(/-/g, '_');
+                const normalizedHyphen = nodeId.replace(/_/g, '-');
+                if (normalizedUnderscore !== nodeId) {
+                    nodeOutput = context.previousOutputs.get(normalizedUnderscore);
+                }
+                if (nodeOutput === undefined && normalizedHyphen !== nodeId) {
+                    nodeOutput = context.previousOutputs.get(normalizedHyphen);
+                }
+            }
+            if (nodeOutput === undefined) {
+                return match;
+            }
+            // 首先从包装格式中提取实际值
+            nodeOutput = this.extractFromWrapper(nodeOutput);
+            // 然后从提取后的值中获取嵌套路径
+            if (segments.length === 1) {
+                // 只有 nodeId，直接返回提取后的值
+                // 如果是对象，序列化为 JSON；如果是原始值，转为字符串
+                return this.stringifyValue(nodeOutput, match);
+            }
+            // 从嵌套路径获取（从 segments[1] 开始）
+            // 如果 segments[1] 是包装属性（"output"、"result"、"metadata"），跳过它因为 extractFromWrapper 已经提取了
+            let value = nodeOutput;
+            let startIndex = 1;
+            if (segments.length > 1 &&
+                (segments[1] === 'output' || segments[1] === 'result' || segments[1] === 'metadata')) {
+                startIndex = 2;
+            }
+            for (let i = startIndex; i < segments.length; i++) {
+                if (value === null || value === undefined) {
+                    return match;
+                }
+                value = value[segments[i]];
+            }
+            return this.stringifyValue(value, match);
+        });
+        return resolved;
+    }
+    /**
+     * Convert a value to string for template replacement.
+     * - If value is undefined, return the original template
+     * - If value is a string, return it directly
+     * - If value is null, return 'null'
+     * - If value is an object or array, serialize to JSON
+     *
+     * @param value - The value to stringify
+     * @param originalTemplate - The original template string (returned if value is undefined)
+     * @returns String representation of the value
+     */
+    stringifyValue(value, originalTemplate) {
+        if (value === undefined) {
+            return originalTemplate;
+        }
+        if (value === null) {
+            return 'null';
+        }
+        if (typeof value === 'string') {
+            return value;
+        }
+        // For objects and arrays, serialize to JSON
+        return JSON.stringify(value);
+    }
+    /**
+     * 从包装格式中提取实际输出值
+     *
+     * 处理以下格式：
+     * - AgentNode: { result, metadata } -> 返回 result
+     * - DecoratorNode: { success, output, ... } -> 返回 output
+     * - 其他格式直接返回
+     *
+     * @param value 原始值
+     * @returns 提取后的值
+     */
+    extractFromWrapper(value) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+        if (typeof value !== 'object') {
+            return value;
+        }
+        // 检查 AgentNode 包装格式: { result, metadata }
+        // 这是 AgentNode 输出的特征签名
+        if ('result' in value && 'metadata' in value) {
+            return value.result;
+        }
+        // 检查 DecoratorNode 包装格式: { success, output, ... }
+        // 有 'output' 但没有 'result'（AgentNode 的特征）
+        if ('output' in value) {
+            return value.output;
+        }
+        return value;
+    }
+    /**
+     * 获取嵌套对象的值
+     *
+     * @param obj 对象
+     * @param path 属性路径
+     * @returns 值或 undefined
+     */
+    getNestedValue(obj, path) {
+        if (!obj) {
+            return undefined;
+        }
+        // Special case: If obj has an 'input' key, we might be accessing a key inside it
+        // This happens when createExecutionContext wraps globalInput as {input: globalInput}
+        if ('input' in obj && path in obj['input']) {
+            // Path exists inside 'input', so look there
+            return obj['input'][path];
+        }
+        // Normal case: path.split('.').reduce(...) with obj as initial value
+        // This allows {{input.city}} to work when path = "city" and obj = {input: {city: "..."}}
+        return path.split('.').reduce((current, key) => {
+            if (current && typeof current === 'object') {
+                return current[key];
+            }
+            return undefined;
+        }, obj);
+    }
+}
+__decorate([
+    TracedAs("agent.node.execute", { recordParams: true, recordResult: true, log: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AgentNode.prototype, "execute", null);
+__decorate([
+    TracedAs("agent.node.createAgentSubSession", { recordParams: true, recordResult: true, log: true }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], AgentNode.prototype, "createAgentSubSession", null);
+// ============================================================================
+// Exports
+// ============================================================================
+export { AgentNode as default };
+//# sourceMappingURL=agent-node.js.map

package/dist/core/src/env/workflow/nodes/agent-node.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview AgentNode TDD Tests
+ *
+ * 测试 AgentNode 类的功能：
+ * - 运行 agent 成功
+ * - Agent runner 错误处理
+ * - Prompt 模板解析
+ * - 传递前置节点上下文
+ * - 处理 agent 超时
+ * - 记录执行元数据
+ */
+export {};
+//# sourceMappingURL=agent-node.test.d.ts.map