@ai-setting/roy-agent-core 1.0.0

package/src/env/tool/validator.ts

@@ -0,0 +1,44 @@
+import { ZodError } from "zod";
+import type { Tool, ValidationResult } from "./types";
+
+/**
+ * 工具参数验证器
+ */
+export class ToolValidator {
+  /**
+   * 验证参数
+   */
+  async validate(tool: Tool, args: Record<string, unknown>): Promise<ValidationResult> {
+    try {
+      // 使用 Zod 验证参数
+      const parsed = await tool.parameters.parseAsync(args);
+      return {
+        success: true,
+        data: parsed as Record<string, unknown>,
+      };
+    } catch (error) {
+      if (error instanceof ZodError) {
+        const errorMessage = tool.formatValidationError
+          ? tool.formatValidationError(error)
+          : this.formatError(error);
+        return {
+          success: false,
+          error: `Invalid arguments for tool '${tool.name}': ${errorMessage}`,
+        };
+      }
+      return {
+        success: false,
+        error: `Validation error: ${error}`,
+      };
+    }
+  }
+
+  /**
+   * 格式化 Zod 错误
+   */
+  private formatError(error: ZodError): string {
+    return error.errors
+      .map((e) => `${e.path.join(".")}: ${e.message}`)
+      .join("; ");
+  }
+}

package/src/env/types.ts

@@ -0,0 +1,180 @@
+/**
+ * @fileoverview Environment types and interfaces
+ * 
+ * 定义 Environment 的核心类型，包括：
+ * - Environment 配置
+ * - EnvEvent 事件类型
+ */
+
+// ============================================================================
+// Environment Types
+// ============================================================================
+
+/**
+ * Environment Config
+ */
+export interface EnvironmentConfig {
+  /** 环境名称 */
+  name: string;
+  /** 环境版本 */
+  version: string;
+  /** 是否启用 */
+  enabled: boolean;
+}
+
+/**
+ * BaseEnvironment 配置
+ */
+export interface BaseEnvironmentConfig {
+  /** 环境名称 */
+  name?: string;
+  /** 环境版本 */
+  version?: string;
+  /** 是否启用 */
+  enabled?: boolean;
+}
+
+// ============================================================================
+// EnvEvent Types
+// ============================================================================
+
+/**
+ * EnvEvent 元信息
+ */
+export interface EnvEventMetadata {
+  /** 触发事件的 session ID */
+  trigger_session_id?: string;
+  /** 触发事件的 agent ID */
+  trigger_agent_id?: string;
+  /** Agent 名称 */
+  trigger_agent_name?: string;
+  /** 环境名称 */
+  env_name?: string;
+  /** 事件来源 */
+  source?: string;
+  /** 其他元数据 */
+  [key: string]: unknown;
+}
+
+/**
+ * EnvEvent
+ * 
+ * 统一的事件机制，用于：
+ * - Stream 事件（stream.start, stream.text, stream.completed 等）
+ * - 工具调用事件（tool.call, tool.result 等）
+ * - 会话事件（session.created, session.updated 等）
+ * - Agent 事件（agent.thinking, agent.acting 等）
+ */
+export interface EnvEvent<T = unknown> {
+  /** 事件 ID */
+  id: string;
+  /** 事件类型 */
+  type: string;
+  /** 时间戳 */
+  timestamp: number;
+  /** 元信息 */
+  metadata: EnvEventMetadata;
+  /** 事件负载 */
+  payload: T;
+}
+
+/**
+ * EnvEvent Handler
+ */
+export type EnvEventHandler = (event: EnvEvent) => void | Promise<void>;
+
+/**
+ * EnvEvent 创建参数（部分属性，可选）
+ * 
+ * 用于 pushEnvEvent 方法，允许传入部分属性，自动补全必填字段
+ */
+export interface EnvEventInput {
+  /** 事件类型（必填） */
+  type: string;
+  /** 事件 ID（可选，自动生成） */
+  id?: string;
+  /** 时间戳（可选，自动生成） */
+  timestamp?: number;
+  /** 元信息（可选，自动创建） */
+  metadata?: EnvEventMetadata;
+  /** 事件负载（可选） */
+  payload?: unknown;
+}
+
+// ============================================================================
+// Context Types
+// ============================================================================
+
+/**
+ * Action 类型
+ */
+export interface Action {
+  /** Action 类型 */
+  type: string;
+  /** Action 参数 */
+  params?: Record<string, unknown>;
+}
+
+/**
+ * Tool Result
+ */
+export interface ToolResult {
+  /** 是否成功 */
+  success: boolean;
+  /** 输出内容 */
+  output: string | Record<string, unknown>;
+  /** 错误信息 */
+  error?: string;
+}
+
+/**
+ * Context
+ */
+export interface Context {
+  /** 会话 ID */
+  sessionId?: string;
+  /** 用户 ID */
+  userId?: string;
+  /** 工作目录 */
+  workdir?: string;
+  /** 中断信号 */
+  abort?: AbortSignal;
+  /** 元数据 */
+  metadata?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Hook Context Types
+// ============================================================================
+
+/**
+ * Session Hook 上下文
+ */
+export interface SessionHookContext {
+  /** Session 对象 */
+  session?: {
+    id: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+  };
+  /** 操作选项 */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * Log Context（日志上下文）
+ */
+export interface LogContext {
+  /** 日志级别 */
+  level: string;
+  /** 日志类别 */
+  category: string;
+  /** 日志消息 */
+  message: string;
+  /** 时间戳 */
+  timestamp: number;
+  /** 调用位置 */
+  callerLocation?: string;
+  /** 其他元数据 */
+  [key: string]: unknown;
+}

package/src/env/workflow/ask-user-tool-registration.test.ts

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview AskUserTool Registration Tests
+ * 
+ * Tests to verify that ask_user tool is only registered in Workflow AgentNode context,
+ * NOT in default agent or sub agent (delegate task) contexts.
+ * 
+ * Design:
+ * - ask_user tool should NOT be available to default agent
+ * - ask_user tool should NOT be available to sub agent (delegate task)
+ * - ask_user tool should ONLY be available in Workflow AgentNode when workflow is running
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { z } from 'zod';
+
+// Mock the ask_user tool
+const mockAskUserTool = {
+  name: 'ask_user',
+  description: 'Ask user for input',
+  parameters: z.object({
+    query: z.string().describe('The question to ask'),
+    options: z.array(z.string()).optional(),
+  }),
+  execute: vi.fn().mockImplementation(() => {
+    throw new Error('AskUserError - should not be called in this test');
+  }),
+  metadata: { category: 'workflow', tags: ['human-in-loop'] },
+};
+
+describe('AskUserTool Registration', () => {
+  describe('ToolComponent registration behavior', () => {
+    it('should NOT register ask_user tool by default', () => {
+      // The ask_user tool should NOT be pre-registered to ToolComponent
+      // This test documents the expected behavior
+      
+      // Setup: Create a mock ToolComponent
+      const registeredTools = new Map<string, any>();
+      const mockToolComponent = {
+        register: vi.fn((tool: any) => {
+          registeredTools.set(tool.name, tool);
+        }),
+        registerMany: vi.fn((tools: any[]) => {
+          tools.forEach((tool: any) => {
+            registeredTools.set(tool.name, tool);
+          });
+        }),
+        getTool: vi.fn((name: string) => registeredTools.get(name)),
+        listTools: vi.fn(() => Array.from(registeredTools.keys())),
+      };
+
+      // Verify: ask_user is NOT registered by default
+      expect(mockToolComponent.getTool('ask_user')).toBeUndefined();
+    });
+
+    it('should document that ask_user is workflow-only', () => {
+      // This test documents the design:
+      // - ask_user tool is only available in Workflow AgentNode context
+      // - It should NOT be available to default agent
+      // - It should NOT be available to sub agent (delegate task)
+      
+      const toolScope = {
+        availableIn: {
+          defaultAgent: false,
+          subAgent: false,
+          workflowAgentNode: true,  // Only when workflow is running
+        },
+        registrationPoint: 'AgentNode options (not init time)',
+      };
+
+      expect(toolScope.availableIn.defaultAgent).toBe(false);
+      expect(toolScope.availableIn.subAgent).toBe(false);
+      expect(toolScope.availableIn.workflowAgentNode).toBe(true);
+    });
+  });
+
+  describe('AgentNode with ask_user in allowedTools', () => {
+    it('should include ask_user in allowedTools when running workflow agent', () => {
+      // Test that when Workflow AgentNode runs, it should have ask_user in allowedTools
+      // This is set in the AgentNode.execute() method when building AgentConfig
+      
+      const agentConfig = {
+        type: 'general',
+        prompt: 'Test prompt',
+        // ask_user should be explicitly allowed for workflow agents
+        options: {
+          allowedTools: ['ask_user'],
+        },
+      };
+
+      expect(agentConfig.options.allowedTools).toContain('ask_user');
+    });
+
+    it('should NOT include ask_user for non-workflow agents', () => {
+      // Test that regular agents (default agent, sub agent) should NOT have ask_user
+      
+      // Default agent - no allowedTools in options
+      const defaultAgentConfig = {
+        type: 'general',
+        prompt: 'Test prompt',
+        // No options.allowedTools - uses default tool list
+      };
+
+      // Sub agent (delegate task) - should not have ask_user
+      const subAgentConfig = {
+        type: 'delegate',
+        prompt: 'Delegate task',
+        // No options.allowedTools
+      };
+
+      // These configs should NOT have ask_user in their allowed tools
+      expect(defaultAgentConfig.options?.allowedTools).toBeUndefined();
+      expect(subAgentConfig.options?.allowedTools).toBeUndefined();
+    });
+  });
+
+  describe('WorkflowComponent initialization', () => {
+    it('should NOT register ask_user tool during init', () => {
+      // WorkflowComponent.init() should NOT call registerAskUserTool()
+      // This documents the expected behavior after refactoring
+      
+      // The registerAskUserTool method exists but should NOT be called during init
+      // It has been removed from the init() and initSqliteService() methods
+      const shouldNotRegisterDuringInit = true;  // This is the expected behavior
+
+      expect(shouldNotRegisterDuringInit).toBe(true);
+    });
+
+    it('should register ask_user only via AgentNode options', () => {
+      // The new design:
+      // - ask_user is not registered globally
+      // - AgentNode adds allowedTools: ['ask_user'] to its options when building AgentConfig
+      // - AgentComponentAdapter passes this to AgentContext
+      // - AgentComponent uses AgentContext.allowedTools to filter tools
+      
+      const registrationPoints = {
+        duringInit: false,
+        viaAgentNodeOptions: true,
+      };
+
+      expect(registrationPoints.duringInit).toBe(false);
+      expect(registrationPoints.viaAgentNodeOptions).toBe(true);
+    });
+  });
+
+  describe('AgentContext.allowedTools propagation', () => {
+    it('should pass allowedTools from AgentNode to AgentContext', () => {
+      // Test the data flow:
+      // AgentNode (options.allowedTools: ['ask_user']) 
+      //   -> AgentComponentAdapter passes to context.allowedTools
+      //   -> AgentContext (allowedTools: ['ask_user'])
+      //   -> AgentComponent.run()
+
+      const agentNodeOptions = {
+        timeout: 60000,
+        model: 'gpt-4',
+        allowedTools: ['ask_user'],
+      };
+
+      // AgentComponentAdapter builds AgentContext
+      const agentContext = {
+        sessionId: 'test-session',
+        allowedTools: agentNodeOptions.allowedTools,  // Pass through from options
+        deniedTools: agentNodeOptions.deniedTools,
+      };
+
+      expect(agentContext.allowedTools).toEqual(['ask_user']);
+      expect(agentContext.allowedTools).toBe(agentNodeOptions.allowedTools);
+    });
+
+    it('should NOT pass allowedTools for non-workflow agents', () => {
+      // Default agent and sub agent should NOT have allowedTools set in context
+      
+      const defaultAgentContext = {
+        sessionId: 'default-session',
+        // No allowedTools - uses default tool list
+      };
+
+      const subAgentContext = {
+        sessionId: 'sub-agent-session',
+        // No allowedTools - uses default tool list
+      };
+
+      expect(defaultAgentContext.allowedTools).toBeUndefined();
+      expect(subAgentContext.allowedTools).toBeUndefined();
+    });
+  });
+});
+
+describe('AskUserTool Scope Enforcement', () => {
+  it('should enforce ask_user scope: workflow-only', () => {
+    // Document the scope rules:
+    // 1. Default Agent - NO access to ask_user
+    // 2. Sub Agent (delegate task) - NO access to ask_user
+    // 3. Workflow AgentNode - ONLY access when workflow is running
+
+    const toolScopeMatrix = {
+      defaultAgent: {
+        canAccess: false,
+        reason: 'ask_user is workflow-specific functionality',
+      },
+      subAgent: {
+        canAccess: false,
+        reason: 'delegate task is for autonomous execution, no human interruption',
+      },
+      workflowAgentNode: {
+        canAccess: true,
+        condition: 'only when workflow is running',
+        reason: 'enables human-in-loop for workflow pause/resume',
+      },
+    };
+
+    expect(toolScopeMatrix.defaultAgent.canAccess).toBe(false);
+    expect(toolScopeMatrix.subAgent.canAccess).toBe(false);
+    expect(toolScopeMatrix.workflowAgentNode.canAccess).toBe(true);
+  });
+});