@elevasis/core 0.1.0

package/src/execution/engine/tools/platform/resource-invocation/__tests__/tool.test.ts

@@ -0,0 +1,555 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { z } from 'zod'
+import { createResourceInvocationTool } from '../tool'
+import { createDynamicResourceInvocationTool } from '../dynamic-tool'
+import { getToolServices } from '../../../registry'
+import type { ResourceInvocationService } from '../resource-invocation-service'
+import type { WorkflowDefinition } from '../../../../workflow/types'
+import type { AgentDefinition } from '../../../../agent/core/types'
+import type { ResourceInvocationResult } from '../types'
+import { createMockExecutionContext } from '../../../../test-utils/mocks'
+
+vi.mock('../../../registry', () => ({
+  getToolServices: vi.fn()
+}))
+
+describe('createResourceInvocationTool', () => {
+  const mockContext = createMockExecutionContext({
+    organizationId: 'org-123',
+    organizationName: 'test-org',
+    executionId: 'exec-parent',
+    resourceId: 'parent-agent'
+  })
+
+  const mockWorkflowDefinition: WorkflowDefinition = {
+    config: {
+      resourceId: 'validation-workflow',
+      name: 'Validation Workflow',
+      description: 'Validates lead data',
+      version: '1.0.0',
+      type: 'workflow',
+      status: 'dev'
+    },
+    contract: {
+      inputSchema: z.object({
+        email: z.string().email(),
+        company: z.string()
+      }),
+      outputSchema: z.object({
+        valid: z.boolean(),
+        errors: z.array(z.string())
+      })
+    },
+    entryPoint: 'validate',
+    steps: {}
+  }
+
+  const mockAgentDefinition: AgentDefinition = {
+    config: {
+      resourceId: 'research-agent',
+      name: 'Research Agent',
+      description: 'Researches companies',
+      version: '1.0.0',
+      type: 'agent',
+      status: 'dev'
+    },
+    contract: {
+      inputSchema: z.object({
+        query: z.string()
+      }),
+      outputSchema: z.object({
+        findings: z.string()
+      })
+    },
+    modelConfig: {
+      provider: 'openai',
+      model: 'gpt-4o',
+      temperature: 0.7
+    },
+    systemPrompt: 'You are a research agent',
+    tools: []
+  }
+
+  let mockService: ResourceInvocationService
+
+  beforeEach(() => {
+    mockService = {
+      executeSync: vi.fn()
+    } as unknown as ResourceInvocationService
+
+    vi.mocked(getToolServices).mockReturnValue({
+      commandQueueService: null,
+      taskSchedulerService: null,
+      notificationsService: null,
+      credentialsService: null,
+      integrationService: null,
+      resourceInvocationService: mockService
+    })
+  })
+
+  describe('tool creation', () => {
+    it('derives schemas from resource contract', () => {
+      const tool = createResourceInvocationTool({
+        name: 'invoke_lead_validation',
+        description: 'Validate lead data',
+        resource: mockWorkflowDefinition
+      })
+
+      expect(tool.name).toBe('invoke_lead_validation')
+      expect(tool.description).toBe('Validate lead data')
+      expect(tool.inputSchema).toBe(mockWorkflowDefinition.contract.inputSchema)
+      expect(tool.outputSchema).toBe(mockWorkflowDefinition.contract.outputSchema)
+    })
+
+    it('uses z.null() for outputSchema when resource has no outputSchema', () => {
+      const workflowWithoutOutput: WorkflowDefinition = {
+        ...mockWorkflowDefinition,
+        contract: {
+          inputSchema: z.object({ data: z.string() }),
+          outputSchema: null
+        }
+      }
+
+      const tool = createResourceInvocationTool({
+        name: 'fire_and_forget',
+        description: 'Fire and forget workflow',
+        resource: workflowWithoutOutput
+      })
+
+      expect(tool.outputSchema).toBeInstanceOf(z.ZodNull)
+    })
+
+    it('creates tool for agent resource', () => {
+      const tool = createResourceInvocationTool({
+        name: 'invoke_research',
+        description: 'Research company',
+        resource: mockAgentDefinition
+      })
+
+      expect(tool.name).toBe('invoke_research')
+      expect(tool.inputSchema).toBe(mockAgentDefinition.contract.inputSchema)
+      expect(tool.outputSchema).toBe(mockAgentDefinition.contract.outputSchema)
+    })
+  })
+
+  describe('tool execution', () => {
+    it('executes workflow and returns output', async () => {
+      const tool = createResourceInvocationTool({
+        name: 'invoke_lead_validation',
+        description: 'Validate lead data',
+        resource: mockWorkflowDefinition
+      })
+
+      const mockResult: ResourceInvocationResult = {
+        success: true,
+        output: { valid: true, errors: [] },
+        executionId: 'exec-child',
+        resourceType: 'workflow'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      const result = await tool.execute({
+        input: { email: 'test@test.com', company: 'ACME Corp' },
+        executionContext: mockContext
+      })
+
+      expect(result).toEqual({ valid: true, errors: [] })
+      expect(mockService.executeSync).toHaveBeenCalledWith(
+        'validation-workflow',
+        { email: 'test@test.com', company: 'ACME Corp' },
+        'test-org',
+        mockContext
+      )
+    })
+
+    it('executes agent and returns output', async () => {
+      const tool = createResourceInvocationTool({
+        name: 'invoke_research',
+        description: 'Research company',
+        resource: mockAgentDefinition
+      })
+
+      const mockResult: ResourceInvocationResult = {
+        success: true,
+        output: { findings: 'Research results...' },
+        executionId: 'exec-research',
+        resourceType: 'agent'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      const result = await tool.execute({
+        input: { query: 'ACME Corp' },
+        executionContext: mockContext
+      })
+
+      expect(result).toEqual({ findings: 'Research results...' })
+    })
+
+    it('returns null for fire-and-forget resources', async () => {
+      const fireAndForgetWorkflow: WorkflowDefinition = {
+        ...mockWorkflowDefinition,
+        contract: {
+          inputSchema: z.object({ data: z.string() }),
+          outputSchema: null
+        }
+      }
+
+      const tool = createResourceInvocationTool({
+        name: 'fire_and_forget',
+        description: 'Fire and forget',
+        resource: fireAndForgetWorkflow
+      })
+
+      const mockResult: ResourceInvocationResult = {
+        success: true,
+        output: null,
+        executionId: 'exec-fire',
+        resourceType: 'workflow'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      const result = await tool.execute({
+        input: { data: 'test' },
+        executionContext: mockContext
+      })
+
+      expect(result).toBeNull()
+    })
+
+    it('throws error when execution fails', async () => {
+      const tool = createResourceInvocationTool({
+        name: 'invoke_lead_validation',
+        description: 'Validate lead data',
+        resource: mockWorkflowDefinition
+      })
+
+      const mockResult: ResourceInvocationResult = {
+        success: false,
+        output: null,
+        executionId: '',
+        resourceType: 'workflow',
+        error: 'Validation failed: missing required fields'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      await expect(
+        tool.execute({
+          input: { email: 'test@test.com', company: 'ACME' },
+          executionContext: mockContext
+        })
+      ).rejects.toThrow('Validation failed: missing required fields')
+    })
+
+    it('throws error with resourceType when no error message provided', async () => {
+      const tool = createResourceInvocationTool({
+        name: 'invoke_research',
+        description: 'Research company',
+        resource: mockAgentDefinition
+      })
+
+      const mockResult: ResourceInvocationResult = {
+        success: false,
+        output: null,
+        executionId: '',
+        resourceType: 'agent'
+        // No error message
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      await expect(
+        tool.execute({
+          input: { query: 'test' },
+          executionContext: mockContext
+        })
+      ).rejects.toThrow('agent execution failed')
+    })
+  })
+
+  describe('service availability', () => {
+    it('throws if service not initialized', async () => {
+      vi.mocked(getToolServices).mockReturnValue({
+        commandQueueService: null,
+        taskSchedulerService: null,
+        notificationsService: null,
+        credentialsService: null,
+        integrationService: null,
+        resourceInvocationService: undefined
+      })
+
+      const tool = createResourceInvocationTool({
+        name: 'invoke_lead_validation',
+        description: 'Validate lead data',
+        resource: mockWorkflowDefinition
+      })
+
+      await expect(
+        tool.execute({
+          input: { email: 'test@test.com', company: 'ACME' },
+          executionContext: mockContext
+        })
+      ).rejects.toThrow('ResourceInvocationService is unavailable')
+    })
+
+    it('throws if context missing', async () => {
+      const tool = createResourceInvocationTool({
+        name: 'invoke_lead_validation',
+        description: 'Validate lead data',
+        resource: mockWorkflowDefinition
+      })
+
+      await expect(
+        tool.execute({
+          input: { email: 'test@test.com', company: 'ACME' }
+          // No executionContext
+        })
+      ).rejects.toThrow('ExecutionContext is unavailable')
+    })
+  })
+
+  describe('organization context', () => {
+    it('uses organizationName from executionContext', async () => {
+      const tool = createResourceInvocationTool({
+        name: 'invoke_lead_validation',
+        description: 'Validate lead data',
+        resource: mockWorkflowDefinition
+      })
+
+      const contextWithOrg = createMockExecutionContext({
+        organizationName: 'acme-corp'
+      })
+
+      const mockResult: ResourceInvocationResult = {
+        success: true,
+        output: { valid: true, errors: [] },
+        executionId: 'exec-org',
+        resourceType: 'workflow'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      await tool.execute({
+        input: { email: 'test@test.com', company: 'ACME' },
+        executionContext: contextWithOrg
+      })
+
+      expect(mockService.executeSync).toHaveBeenCalledWith(
+        'validation-workflow',
+        expect.anything(),
+        'acme-corp',
+        contextWithOrg
+      )
+    })
+  })
+})
+
+describe('createDynamicResourceInvocationTool', () => {
+  const mockContext = createMockExecutionContext({
+    organizationId: 'org-123',
+    organizationName: 'test-org',
+    executionId: 'exec-parent'
+  })
+
+  let mockService: ResourceInvocationService
+
+  beforeEach(() => {
+    mockService = {
+      executeSync: vi.fn()
+    } as unknown as ResourceInvocationService
+
+    vi.mocked(getToolServices).mockReturnValue({
+      commandQueueService: null,
+      taskSchedulerService: null,
+      notificationsService: null,
+      credentialsService: null,
+      integrationService: null,
+      resourceInvocationService: mockService
+    })
+  })
+
+  describe('tool creation', () => {
+    it('creates tool with dynamic input schema', () => {
+      const tool = createDynamicResourceInvocationTool()
+
+      expect(tool.name).toBe('invoke_resource')
+      expect(tool.description).toContain('Invoke any resource')
+      expect(tool.inputSchema).toBeDefined()
+      expect(tool.outputSchema).toBeDefined()
+    })
+  })
+
+  describe('tool execution', () => {
+    it('returns full ResourceInvocationResult', async () => {
+      const tool = createDynamicResourceInvocationTool()
+
+      const mockResult: ResourceInvocationResult = {
+        success: true,
+        output: { data: 'result' },
+        executionId: 'exec-dynamic',
+        resourceType: 'workflow'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      const result = await tool.execute({
+        input: {
+          resourceId: 'validation-workflow',
+          input: { email: 'test@test.com' }
+        },
+        executionContext: mockContext
+      })
+
+      expect(result).toEqual(mockResult)
+      expect(mockService.executeSync).toHaveBeenCalledWith(
+        'validation-workflow',
+        { email: 'test@test.com' },
+        'test-org',
+        mockContext
+      )
+    })
+
+    it('invokes agent resource dynamically', async () => {
+      const tool = createDynamicResourceInvocationTool()
+
+      const mockResult: ResourceInvocationResult = {
+        success: true,
+        output: { findings: 'results' },
+        executionId: 'exec-agent',
+        resourceType: 'agent'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      const result = await tool.execute({
+        input: {
+          resourceId: 'research-agent',
+          input: { query: 'test query' }
+        },
+        executionContext: mockContext
+      })
+
+      expect(result).toEqual(mockResult)
+      expect((result as ResourceInvocationResult).resourceType).toBe('agent')
+    })
+
+    it('returns complete result with metadata', async () => {
+      const tool = createDynamicResourceInvocationTool()
+
+      const mockResult: ResourceInvocationResult = {
+        success: true,
+        output: { value: 'test' },
+        executionId: 'exec-metadata',
+        resourceType: 'workflow'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      const result = await tool.execute({
+        input: {
+          resourceId: 'any-resource',
+          input: { key: 'value' }
+        },
+        executionContext: mockContext
+      })
+
+      // Verify all metadata fields present
+      expect(result).toHaveProperty('success')
+      expect(result).toHaveProperty('output')
+      expect(result).toHaveProperty('executionId')
+      expect(result).toHaveProperty('resourceType')
+    })
+
+    it('returns failed result without throwing', async () => {
+      const tool = createDynamicResourceInvocationTool()
+
+      const mockResult: ResourceInvocationResult = {
+        success: false,
+        output: null,
+        executionId: '',
+        resourceType: 'workflow',
+        error: 'Resource not found'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      const result = await tool.execute({
+        input: {
+          resourceId: 'non-existent',
+          input: {}
+        },
+        executionContext: mockContext
+      })
+
+      // Dynamic tool returns full result, doesn't throw
+      expect(result).toEqual(mockResult)
+      expect((result as ResourceInvocationResult).success).toBe(false)
+      expect((result as ResourceInvocationResult).error).toBe('Resource not found')
+    })
+  })
+
+  describe('service availability', () => {
+    it('throws if service not initialized', async () => {
+      vi.mocked(getToolServices).mockReturnValue({
+        commandQueueService: null,
+        taskSchedulerService: null,
+        notificationsService: null,
+        credentialsService: null,
+        integrationService: null,
+        resourceInvocationService: undefined
+      })
+
+      const tool = createDynamicResourceInvocationTool()
+
+      await expect(
+        tool.execute({
+          input: {
+            resourceId: 'test-resource',
+            input: {}
+          },
+          executionContext: mockContext
+        })
+      ).rejects.toThrow('ResourceInvocationService is unavailable')
+    })
+
+    it('throws if context missing', async () => {
+      const tool = createDynamicResourceInvocationTool()
+
+      await expect(
+        tool.execute({
+          input: {
+            resourceId: 'test-resource',
+            input: {}
+          }
+          // No executionContext
+        })
+      ).rejects.toThrow('ExecutionContext is unavailable')
+    })
+  })
+
+  describe('organization context', () => {
+    it('uses organizationName from executionContext', async () => {
+      const tool = createDynamicResourceInvocationTool()
+
+      const contextWithOrg = createMockExecutionContext({
+        organizationName: 'different-org'
+      })
+
+      const mockResult: ResourceInvocationResult = {
+        success: true,
+        output: { data: 'test' },
+        executionId: 'exec-ctx',
+        resourceType: 'workflow'
+      }
+      vi.mocked(mockService.executeSync).mockResolvedValue(mockResult)
+
+      await tool.execute({
+        input: {
+          resourceId: 'some-resource',
+          input: { key: 'value' }
+        },
+        executionContext: contextWithOrg
+      })
+
+      expect(mockService.executeSync).toHaveBeenCalledWith(
+        'some-resource',
+        { key: 'value' },
+        'different-org',
+        contextWithOrg
+      )
+    })
+  })
+})

package/src/execution/engine/tools/platform/resource-invocation/dynamic-tool.ts

@@ -0,0 +1,94 @@
+/**
+ * Dynamic Resource Invocation Tool Factory
+ *
+ * Creates a generic tool that can invoke any resource by ID at runtime.
+ * Useful for agents that need to select which resource to invoke dynamically.
+ *
+ * @module resource-invocation/dynamic-tool
+ */
+
+import { z } from 'zod'
+import { serviceUnavailable } from '../../types'
+import type { Tool, ToolExecutionOptions } from '../../types'
+import { getToolServices } from '../../registry'
+
+/**
+ * Input schema for dynamic resource invocation
+ * Takes resourceId as input parameter along with the input payload
+ */
+export const dynamicResourceInvocationSchema = z.object({
+  resourceId: z.string().describe('ID of resource (agent or workflow) to invoke'),
+  input: z.record(z.string(), z.unknown()).describe('Input payload for resource')
+})
+
+/**
+ * Output schema for dynamic resource invocation
+ * Returns complete ResourceInvocationResult including metadata
+ */
+export const dynamicResourceInvocationOutputSchema = z.object({
+  success: z.boolean().describe('Whether resource execution succeeded'),
+  output: z.unknown().describe('Output from resource (or null if no outputSchema)'),
+  executionId: z.string().describe('Execution ID for tracking'),
+  resourceType: z.enum(['agent', 'workflow']).describe('Type of resource executed')
+})
+
+/**
+ * Create a dynamic resource invocation tool
+ *
+ * Unlike createResourceInvocationTool() which binds to a specific resource at build time,
+ * this factory creates a generic tool that accepts resourceId as an input parameter.
+ *
+ * The tool returns the full ResourceInvocationResult (not just output) to provide
+ * visibility into execution metadata.
+ *
+ * @returns Tool that can invoke any resource by ID at runtime
+ *
+ * @example
+ * // Add to agent tools for dynamic resource selection
+ * const agent: AgentDefinition = {
+ *   tools: [
+ *     createDynamicResourceInvocationTool(),
+ *     // ... other tools
+ *   ]
+ * }
+ *
+ * // Agent can now invoke any resource dynamically:
+ * // - invoke_resource({ resourceId: 'lead-validation', input: { email: '...' } })
+ * // - invoke_resource({ resourceId: 'company-research', input: { query: '...' } })
+ */
+export function createDynamicResourceInvocationTool(): Tool {
+  return {
+    name: 'invoke_resource',
+    description: 'Invoke any resource (agent or workflow) by ID with custom input',
+    inputSchema: dynamicResourceInvocationSchema,
+    outputSchema: dynamicResourceInvocationOutputSchema,
+
+    async execute(options: ToolExecutionOptions): Promise<unknown> {
+      // Get resource invocation service from global registry
+      const { resourceInvocationService } = getToolServices()
+
+      if (!resourceInvocationService) {
+        throw serviceUnavailable('ResourceInvocationService')
+      }
+
+      if (!options.executionContext) {
+        throw serviceUnavailable('ExecutionContext', { tool: 'invoke_resource', reason: 'organizationId required for multi-tenant isolation' })
+      }
+
+      // Extract resourceId and input from tool input
+      const { resourceId, input } = options.input as z.infer<typeof dynamicResourceInvocationSchema>
+
+      // Execute resource and return complete result
+      // organizationName is guaranteed to be present in ExecutionContext (extends ExecutionMetadata)
+      const result = await resourceInvocationService.executeSync(
+        resourceId,
+        input,
+        options.executionContext.organizationName,
+        options.executionContext
+      )
+
+      // Return complete result (not just output) for visibility into execution metadata
+      return result
+    }
+  }
+}

package/src/execution/engine/tools/platform/resource-invocation/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Resource Invocation Platform Tool
+ *
+ * Enables agents to invoke other resources (agents and workflows) as tools.
+ * Supports nested execution with parent-child tracking and multi-tenancy isolation.
+ *
+ * @module resource-invocation
+ */
+
+export { ResourceInvocationService, createResourceInvocationService } from './resource-invocation-service'
+export type { ResourceExecutionRequest, ResourceInvocationResult } from './types'
+export { createResourceInvocationTool } from './tool'
+export type { ResourceInvocationToolConfig, ResourceDefinition } from './tool'
+export { createDynamicResourceInvocationTool, dynamicResourceInvocationSchema, dynamicResourceInvocationOutputSchema } from './dynamic-tool'