@ai-setting/roy-agent-cli 1.3.19 → 1.3.22

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

@@ -1,217 +0,0 @@
-/**
- * @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

@@ -1,419 +0,0 @@
-/**
- * @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

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