@ai-setting/roy-agent-core 1.7.52 → 1.7.55

package/dist/env/workflow/nodes/agent-component-adapter.d.ts

@@ -0,0 +1,175 @@
+/**
+ * @fileoverview AgentComponentAdapter - Bridge between Workflow AgentNode and AgentComponent
+ *
+ * This adapter implements the AgentRunner interface required by AgentNode,
+ * delegating actual execution to the AgentComponent.
+ *
+ * Usage:
+ * ```typescript
+ * const agentComponent = env.getComponent<AgentComponent>('agent');
+ * const adapter = new AgentComponentAdapter(agentComponent);
+ *
+ * // Register agents that can be used in workflows
+ * adapter.registerAgent('researcher', {
+ *   systemPrompt: 'You are a research assistant...',
+ *   type: 'general',
+ *   model: 'gpt-4'
+ * });
+ *
+ * // Now AgentNode can use 'researcher' agent type
+ * const workflow = {
+ *   nodes: [{
+ *     type: 'agent',
+ *     config: { agent_type: 'researcher', prompt: '...' }
+ *   }]
+ * };
+ * ```
+ */
+import type { AgentComponent } from '../../agent/agent-component';
+import type { AgentRunner, AgentConfig, AgentResult } from './agent-node';
+import type { SessionComponent } from '../../session/session-component';
+/**
+ * Pending Agent Session - Stores info needed to resume an agent after user input
+ */
+export interface PendingAgentSession {
+    agentSessionId: string;
+    nodeId: string;
+    runId: string;
+    createdAt: number;
+}
+/**
+ * AgentComponentAdapter
+ *
+ * Adapts AgentComponent to the AgentRunner interface expected by Workflow's AgentNode.
+ * Provides session isolation for agent execution within workflow context.
+ *
+ * Features:
+ * - Creates dedicated agent sessions for each workflow agent node execution
+ * - Tracks pending sessions for resume after user input
+ * - Supports mapping agent sessions to workflow run session messages
+ */
+export declare class AgentComponentAdapter implements AgentRunner {
+    private agentComponent;
+    private options;
+    private _sessionComponent?;
+    /** Session prefix for agent sessions */
+    private agentSessionPrefix;
+    /** Current agent session ID */
+    private _currentAgentSessionId?;
+    /** Pending agent sessions (waiting for user input) */
+    private pendingSessions;
+    /** Map from workflow run session to agent sessions */
+    private runSessionToAgentSessions;
+    /** Ensure workflow JSON output plugin is registered once */
+    private jsonOutputPluginRegistered;
+    constructor(agentComponent: AgentComponent, options?: AgentComponentAdapterOptions, _sessionComponent?: SessionComponent | undefined);
+    private ensureJsonOutputPluginRegistered;
+    /**
+     * Set the SessionComponent for agent session management
+     */
+    setSessionComponent(sessionComponent: SessionComponent): void;
+    /**
+     * Get the current agent session ID
+     */
+    getCurrentAgentSessionId(): string | undefined;
+    /**
+     * Register an agent that can be used in workflows
+     *
+     * @param name - Agent name (used as agent_type in workflow definition)
+     * @param config - Agent configuration
+     */
+    registerAgent(name: string, config: AgentRegistrationConfig): void;
+    /**
+     * Run an agent
+     *
+     * Implements AgentRunner interface.
+     * Creates a dedicated agent session for each execution within workflow context.
+     *
+     * @param config - Agent configuration
+     * @param resumeOptions - Optional options for resuming a paused agent
+     * @returns Agent execution result
+     */
+    run(config: AgentConfig, resumeOptions?: {
+        userQuery?: string;
+        agentSessionId?: string;
+    }, signal?: AbortSignal): Promise<AgentResult>;
+    /**
+     * Resume a paused agent with user response
+     *
+     * This method is called when workflow resumes after user input.
+     * It retrieves the pending agent session and continues execution.
+     *
+     * @param agentSessionId - The agent session ID to resume
+     * @param userQuery - User's response to the ask_user query
+     * @param config - Original agent config
+     * @returns Agent execution result
+     */
+    resumeAgent(agentSessionId: string, userQuery: string, config: AgentConfig): Promise<AgentResult>;
+    /**
+     * Get pending agent session by agent session ID
+     */
+    getPendingSession(agentSessionId: string): PendingAgentSession | undefined;
+    /**
+     * Get pending agent sessions for a workflow run
+     */
+    getPendingSessionsForRun(runId: string): PendingAgentSession[];
+    /**
+     * Get all agent session IDs associated with a workflow session
+     */
+    getAgentSessionsForWorkflowSession(workflowSessionId: string): string[];
+    /**
+     * Check if an agent is registered
+     */
+    hasAgent(name: string): boolean;
+    /**
+     * Get registered agent configuration
+     *
+     * Returns the config of a registered agent, useful for workflow
+     * agent_name lookups to inherit model, allowedTools, etc.
+     *
+     * @param name - Agent name
+     * @returns Agent registration config or undefined if not found
+     */
+    getAgentConfig(name: string): AgentRegistrationConfig | undefined;
+    /**
+     * List all registered agents
+     */
+    listAgents(): string[];
+    /**
+     * Get the underlying AgentComponent
+     */
+    getAgentComponent(): AgentComponent;
+    private agentSessionPrefixes;
+}
+/**
+ * Options for AgentComponentAdapter
+ */
+export interface AgentComponentAdapterOptions {
+    /** Default timeout for agent execution (ms) */
+    defaultTimeout?: number;
+    /** Default session ID prefix */
+    defaultSessionPrefix?: string;
+}
+/**
+ * Configuration for registering an agent
+ */
+export interface AgentRegistrationConfig {
+    /** Agent type */
+    type?: 'general' | 'research' | 'coder' | 'critic';
+    /** Model to use */
+    model?: string;
+    /** System prompt */
+    systemPrompt?: string;
+    /** Max iterations */
+    maxIterations?: number;
+    /** Allowed tools */
+    allowedTools?: string[];
+    /** Denied tools */
+    deniedTools?: string[];
+    /** Timeout (ms) */
+    timeout?: number;
+    /** Max error retries */
+    maxErrorRetries?: number;
+    /** Session ID prefix for workflow isolation */
+    sessionIdPrefix?: string;
+}

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

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview AgentNode - Delegate work to an AI agent
+ *
+ * AgentNode delegates work to an AI agent with task description and context.
+ */
+import type { 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）
+     * @param signal AbortSignal — Task #1976: 当 workflow 节点超时或被 stop 时
+     *   通过此 signal 通知 runner 取消。Runner 应当监听 signal.aborted 并
+     *   尽快 resolve/reject（不要 hang）。Optional — 老 runner 不实现也 OK。
+     * @returns Agent 执行结果
+     */
+    run(config: AgentConfig, resumeOptions?: {
+        userQuery?: string;
+        agentSessionId?: string;
+    }, signal?: AbortSignal): Promise<AgentResult>;
+    /**
+     * 恢复暂停的 Agent
+     *
+     * @param agentSessionId Agent session ID
+     * @param userQuery 用户的响应
+     * @param config 原始的 agent 配置
+     * @returns Agent 执行结果
+     */
+    resumeAgent?(agentSessionId: string, userQuery: 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 的配置
+     * @param name Agent 名称
+     * @returns Agent 注册配置，如果不存在则返回 undefined
+     */
+    getAgentConfig?(name: string): AgentRegistrationConfig | undefined;
+}
+/**
+ * Agent 配置
+ */
+export interface AgentConfig {
+    /** Agent 类型 */
+    type: string;
+    /** Prompt（任务描述） */
+    prompt: string;
+    /** 可选配置 */
+    options?: {
+        /** 超时时间（毫秒） */
+        timeout?: number;
+        /** 模型名称 */
+        model?: string;
+        /** 允许的工具列表（用于限制 agent 可用的工具） */
+        allowedTools?: string[];
+        /** 拒绝的工具列表 */
+        deniedTools?: string[];
+        /** JSON output schema (when output.mode=json) */
+        outputSchema?: Record<string, unknown>;
+    };
+    /** 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;
+    /** Structured JSON output (when output.mode=json) */
+    structuredOutput?: Record<string, 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>;
+    /**
+     * Apply caller-provided prompt injection to a resolved base prompt.
+     *
+     * Task #2135 — Workflow input may carry an optional `prompt_injection`
+     * string (via `workflow run --input '{"prompt_injection": "..."}'`). When
+     * present and non-empty, we append it to the resolved base prompt with a
+     * unified separator so the caller can supply runtime hints / context /
+     * constraints without re-running template resolution.
+     *
+     * Behavior:
+     * - `promptInjection` undefined / null / empty string → return basePrompt unchanged
+     * - otherwise → append with `\n\n---\n[Caller Injection]\n<injection>`
+     *
+     * Trace: span name `workflow.agent.applyPromptInjection`,
+     * `recordParams: true` (record `basePrompt` and `promptInjection` for
+     * debugging "injection didn't take effect" bugs), `recordResult: false`
+     * (basePrompt may contain sensitive info → never leak it back).
+     */
+    private applyPromptInjection;
+    /**
+     * Resolve agent sub-session ID from workflow session metadata.agentSessions
+     */
+    private resolveAgentSessionIdFromWorkflow;
+    /**
+     * 创建 agent sub-session
+     *
+     * Sub-session 用于存储 agent 的对话历史，支持 human-in-loop resume
+     */
+    private createAgentSubSession;
+}
+export { AgentNode as default };

package/dist/env/workflow/nodes/ask-user-node.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @fileoverview AskUserNode - Node for requesting user input
+ *
+ * This node is used for simple pause/resume scenarios where a workflow
+ * needs user input without going through an Agent.
+ */
+import type { Node, NodeExecutionResult } from '../types';
+import type { NodeDefinition } from '../types';
+import type { NodeInterruptEvent } from '../types/workflow-hil';
+/**
+ * AskUserNode Configuration
+ */
+export interface AskUserNodeConfig {
+    /** Question to ask the user */
+    query?: string;
+    /** Optional choices for the user */
+    options?: string[];
+    /** If true, user must explicitly confirm */
+    required_confirm?: boolean;
+}
+/**
+ * AskUserNode - Standalone node for user input requests
+ *
+ * This node pauses the workflow and waits for user response.
+ * Used for simple human-in-loop scenarios without an Agent.
+ *
+ * @example
+ * ```yaml
+ * nodes:
+ *   - id: confirm_step
+ *     type: ask_user
+ *     config:
+ *       query: "Do you want to proceed?"
+ *       options:
+ *         - "Yes"
+ *         - "No"
+ *         - "Cancel"
+ * ```
+ */
+export declare class AskUserNode implements Node {
+    private definition;
+    readonly type = "ask_user";
+    readonly id: string;
+    constructor(definition: NodeDefinition);
+    /**
+     * Execute the AskUserNode
+     *
+     * Publishes a node.interrupt event and throws AskUserError to pause workflow.
+     *
+     * @param context - Node execution context with optional resolvedConfig
+     * @throws AskUserError - Always throws to pause workflow
+     */
+    execute(context: {
+        runId: string;
+        sessionId: string;
+        eventBus: {
+            publish(event: NodeInterruptEvent): Promise<void>;
+        };
+        nodeOutputs: Map<string, unknown>;
+        resolvedConfig?: Record<string, unknown>;
+    }): Promise<NodeExecutionResult>;
+    /**
+     * Validate node configuration
+     */
+    validateConfig(_config: Record<string, unknown>): boolean;
+}

package/dist/env/workflow/nodes/condition-node.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview ConditionNode - Workflow condition node
+ *
+ * Evaluates a condition and decides whether to proceed or skip.
+ *
+ * Input can contain template strings like {{nodeId.output.path}} that will be
+ * resolved from previousOutputs via TemplateResolver.
+ */
+import type { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+/**
+ * ConditionNode evaluates a condition and returns the result.
+ *
+ * The condition can be:
+ * - A boolean value
+ * - A template expression that evaluates to a boolean
+ * - A template reference to a previous node's output
+ *
+ * Usage in workflow:
+ * ```yaml
+ * nodes:
+ *   - id: check-tests-pass
+ *     type: condition
+ *     config:
+ *       condition: "{{run-unit-tests.success}}"
+ *     depends_on:
+ *       - run-unit-tests
+ * ```
+ */
+export declare class ConditionNode implements Node {
+    private definition;
+    readonly type = "condition";
+    readonly id: string;
+    constructor(definition: NodeDefinition);
+    execute(context: NodeExecutionContext): Promise<NodeExecutionResult>;
+    /**
+     * Evaluate a resolved condition value.
+     */
+    private evaluateCondition;
+}

package/dist/env/workflow/nodes/index.d.ts

@@ -0,0 +1,8 @@
+export { ToolNode } from './tool-node';
+export type { ToolRegistry, Tool } from './tool-node';
+export { SkillNode } from './skill-node';
+export type { SkillRegistry, Skill } from './skill-node';
+export { WorkflowNode } from './workflow-node';
+export type { WorkflowRunner, WorkflowRunResult } from './workflow-node';
+export { PythonCallNode } from './python-call-node';
+export type { PythonCallAllowList, PythonCallNodeOptions, PythonCallNodeConfig, } from './python-call-node';

package/dist/env/workflow/nodes/index.js

@@ -7,7 +7,7 @@ import {
   init_skill_node,
   init_tool_node,
   init_workflow_node
-} from "../../../shared/@ai-setting/roy-agent-core-x8n1r7h4.js";
+} from "../../../shared/@ai-setting/roy-agent-core-2bscfrr1.js";
 import"../../../shared/@ai-setting/roy-agent-core-dsevjbck.js";
 import"../../../shared/@ai-setting/roy-agent-core-8seq65bp.js";
 import"../../../shared/@ai-setting/roy-agent-core-jnszp0jq.js";

package/dist/env/workflow/nodes/merge-node.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview MergeNode - Workflow merge/join node
+ *
+ * A merge node waits for all dependencies to complete and collects their outputs.
+ *
+ * Input can contain template strings like {{nodeId.output.path}} that will be
+ * resolved from previousOutputs.
+ */
+import type { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+/**
+ * MergeNode collects outputs from all dependent nodes and optionally merges them.
+ *
+ * The merge strategy can be:
+ * - "collect": Collect all outputs into an array
+ * - "first": Return the first completed output
+ * - "last": Return the last completed output
+ * - "merge": Deep merge all outputs into a single object
+ *
+ * Usage in workflow:
+ * ```yaml
+ * nodes:
+ *   - id: final
+ *     type: merge
+ *     config:
+ *       strategy: collect
+ *     depends_on:
+ *       - log-workflow-complete
+ * ```
+ */
+export declare class MergeNode implements Node {
+    private definition;
+    readonly type = "merge";
+    readonly id: string;
+    constructor(definition: NodeDefinition);
+    execute(context: NodeExecutionContext): Promise<NodeExecutionResult>;
+    /**
+     * Deep merge multiple objects into a single object.
+     */
+    private deepMerge;
+}

package/dist/env/workflow/nodes/python-call-node.d.ts

@@ -0,0 +1,95 @@
+/**
+ * PythonCallNode - workflow node type that invokes a Python function via subprocess.
+ *
+ * Task #1998: 投资选股 workflow 解耦 CLI/bash 依赖
+ *
+ * Decouples workflows from hardcoded paths like:
+ *   `/home/dzk/work/.../.venv/bin/python scripts/foo.py --arg1`
+ *
+ * Instead, a workflow declares:
+ *   ```yaml
+ *   - id: market-timing
+ *     type: python_call
+ *     config:
+ *       module: investment_strategy.scripts.market_timing
+ *       function: run
+ *       args:
+ *         base_top_n: "{{input.base_top_n}}"
+ *       cwd: /path/to/repo          # optional
+ *       python: /usr/bin/python3   # optional, default: python3
+ *       timeout: 60000              # optional, ms, default: 60000
+ *   ```
+ *
+ * Execution model:
+ *   - Spawn: `<python> -c "<source>"`
+ *     where `<source>` imports the module, calls the function with the args,
+ *     and prints the return value as JSON to stdout.
+ *   - stdout is parsed as JSON if possible; otherwise returned as a string.
+ *   - Non-zero exit → result.error is populated.
+ *   - Timeout → kills subprocess and returns timeout error.
+ *
+ * Security (MVP):
+ *   - Module must match the allow-list (default: `investment_strategy.*`).
+ *   - Function name must be a bare identifier (regex /^[A-Za-z_]\w*$/).
+ *   - This is a guard rail against arbitrary code execution — not a full sandbox.
+ *     Workflow authors are trusted operators; the allow-list prevents accidental
+ *     `module: os` / `module: subprocess` misuse.
+ */
+import { spawn } from 'node:child_process';
+import type { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+/**
+ * Allow-list configuration for Python module names.
+ *
+ * - `prefix`: each entry matches modules that start with `<entry>.` or equal `<entry>`.
+ * - Default: `{ prefix: ['investment_strategy'] }`.
+ *
+ * Pass an empty `{ prefix: [] }` to disable (NOT recommended in production).
+ */
+export interface PythonCallAllowList {
+    prefix: string[];
+}
+/**
+ * Per-node constructor options.
+ */
+export interface PythonCallNodeOptions {
+    allowList?: PythonCallAllowList;
+    /**
+     * Override spawn factory (for tests / Effect-based executors).
+     * Signature mirrors `child_process.spawn`.
+     */
+    spawnFn?: typeof spawn;
+}
+/**
+ * Static type for the `config` field of a python_call node.
+ */
+export interface PythonCallNodeConfig {
+    module: string;
+    function: string;
+    args?: Record<string, unknown>;
+    cwd?: string;
+    python?: string;
+    timeout?: number;
+}
+/**
+ * PythonCallNode — see file header for design.
+ */
+export declare class PythonCallNode implements Node {
+    private definition;
+    readonly type = "python_call";
+    readonly id: string;
+    private readonly allowList;
+    private readonly spawnFn;
+    constructor(definition: NodeDefinition, options?: PythonCallNodeOptions);
+    /**
+     * Validate that `module` is in the allow-list.
+     * Returns null when OK, or an error message string.
+     */
+    private checkAllowList;
+    /**
+     * Parse JSON emitted by the Python wrapper, including JSON-encoded strings.
+     * If stdout is not valid JSON, preserve the raw output while removing only
+     * trailing newlines.
+     */
+    private parseOutput;
+    execute(context: NodeExecutionContext): Promise<NodeExecutionResult>;
+}

package/dist/env/workflow/nodes/skill-node.d.ts

@@ -0,0 +1,29 @@
+import type { Node, NodeDefinition, NodeExecutionContext, NodeExecutionResult } from '../types';
+/**
+ * Skill Registry interface for looking up skills
+ */
+export interface SkillRegistry {
+    getSkill(name: string): Skill | undefined;
+    hasSkill(name: string): boolean;
+}
+/**
+ * Skill interface for invocation
+ */
+export interface Skill {
+    name: string;
+    invoke(input: any, context: any): Promise<any>;
+}
+/**
+ * SkillNode invokes a registered Skill with the provided input.
+ *
+ * Input can contain template strings like {{nodeId.output.path}} that will be
+ * resolved via context.templateResolver.
+ */
+export declare class SkillNode implements Node {
+    private definition;
+    private skillRegistry;
+    readonly type = "skill";
+    readonly id: string;
+    constructor(definition: NodeDefinition, skillRegistry: SkillRegistry);
+    execute(context: NodeExecutionContext): Promise<NodeExecutionResult>;
+}