@elevasis/core 0.1.0

package/src/execution/engine/tools/llm/index.ts

@@ -0,0 +1,11 @@
+/**
+ * LLM Tools - Browser-safe exports
+ *
+ * NOTE: Server-only tool factory (createLLMCallTool) is exported from @repo/core/server
+ * to prevent browser build failures (depends on server-only LLM adapters).
+ *
+ * This file exports only browser-safe types.
+ */
+
+// Type-only exports (safe for browser - types are erased at runtime)
+export type { LLMCallToolConfig } from './server/llm-call-tool'

package/src/execution/engine/tools/llm/server/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Server-only LLM Tools
+ *
+ * These tools use server-only adapters (createLLMAdapter)
+ * and should only be imported from @repo/core/server
+ */
+
+export { createLLMCallTool, type LLMCallToolConfig } from './llm-call-tool'

package/src/execution/engine/tools/llm/server/llm-call-tool.ts

@@ -0,0 +1,118 @@
+/**
+ * LLM Call Tool Factory
+ * Creates a tool that allows agents to make additional LLM calls during iteration
+ */
+
+import { z } from 'zod'
+import type { Tool, ToolExecutionOptions } from '../../types'
+import { createLLMAdapter } from '../../../llm/adapters/server/adapter-factory'
+import type { ModelConfig } from '../../../llm/model-info'
+
+/**
+ * Input type for LLM call tool
+ */
+interface LLMCallToolInput {
+  messages: Array<{ role: 'system' | 'user' | 'assistant'; content: string }>
+  responseSchema?: Record<string, unknown>
+  temperature?: number
+  maxOutputTokens?: number
+}
+
+/**
+ * Check if a schema is valid (has a type field)
+ * Invalid/placeholder schemas like { placeholderField: "ignored" } are rejected
+ */
+function isValidSchema(schema: unknown): schema is Record<string, unknown> {
+  if (!schema || typeof schema !== 'object') return false
+  const obj = schema as Record<string, unknown>
+  // Valid JSON Schema must have a 'type' field (object, string, array, etc.)
+  return 'type' in obj && typeof obj.type === 'string'
+}
+
+export interface LLMCallToolConfig {
+  /** Model configuration (provider, model, API key) */
+  modelConfig: ModelConfig
+  /** Optional custom tool name (default: 'llm_call') */
+  name?: string
+  /** Optional custom description */
+  description?: string
+}
+
+/**
+ * Create an LLM call tool for agent use
+ *
+ * @example
+ * ```typescript
+ * const tool = createLLMCallTool({
+ *   modelConfig: {
+ *     provider: 'openrouter',
+ *     model: 'openrouter/anthropic/claude-sonnet-4.5',
+ *     apiKey: process.env.OPENROUTER_API_KEY!
+ *   }
+ * })
+ *
+ * // Add to agent definition
+ * const agent: AgentDefinition = {
+ *   tools: [tool, ...otherTools]
+ * }
+ * ```
+ */
+export function createLLMCallTool(config: LLMCallToolConfig): Tool {
+  const toolName = config.name ?? 'llm_call'
+
+  return {
+    name: toolName,
+    description:
+      config.description ??
+      'Make an LLM call with structured output. Use for text analysis, content generation, or AI assistance.',
+
+    inputSchema: z.object({
+      messages: z
+        .array(
+          z.object({
+            role: z.enum(['system', 'user', 'assistant']),
+            content: z.string()
+          })
+        )
+        .min(1),
+      responseSchema: z.record(z.string(), z.unknown()).optional(),
+      temperature: z.number().min(0).max(2).optional(),
+      maxOutputTokens: z.number().min(100).optional()
+    }),
+
+    outputSchema: z.unknown(),
+
+    execute: async ({ input, executionContext, iterationContext }: ToolExecutionOptions) => {
+      const { messages, responseSchema, temperature, maxOutputTokens } = input as LLMCallToolInput
+
+      const adapter = createLLMAdapter(
+        {
+          ...config.modelConfig,
+          ...(temperature !== undefined && { temperature }),
+          ...(maxOutputTokens !== undefined && { maxOutputTokens })
+        },
+        executionContext?.aiUsageCollector,
+        'tool',
+        {
+          type: 'tool',
+          toolName,
+          parentIteration: iterationContext?.iteration
+        }
+      )
+
+      // Only pass responseSchema if it's a valid JSON Schema (has a 'type' field)
+      // Invalid/placeholder schemas like { placeholderField: "ignored" } are skipped
+      // This prevents Google API errors when the agent doesn't need structured output
+      const validSchema = isValidSchema(responseSchema) ? responseSchema : undefined
+
+      const response = await adapter.generate({
+        messages,
+        responseSchema: validSchema,
+        temperature,
+        maxOutputTokens
+      })
+
+      return response.output
+    }
+  }
+}

package/src/execution/engine/tools/platform/__tests__/approval.test.ts

@@ -0,0 +1,242 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { z } from 'zod'
+import { createApprovalTool } from '../approval'
+import { ToolingError } from '../../types'
+import type { ApprovalToolConfig } from '../types'
+import { getToolServices } from '../../registry'
+import { createMockExecutionContext } from '../../../test-utils/mocks'
+
+vi.mock('../../registry', () => ({
+  getToolServices: vi.fn()
+}))
+
+describe('createApprovalTool', () => {
+  const mockConfig: ApprovalToolConfig = {
+    name: 'request_payment_approval',
+    description: 'Request approval for payment',
+    inputSchema: z.object({
+      amount: z.number(),
+      recipient: z.string()
+    }),
+    outputSchema: z.object({
+      taskId: z.string()
+    }),
+    approveTargetResourceId: 'payment-processor',
+    rejectTargetResourceId: 'payment-rejection-handler',
+    priority: 8
+  }
+
+  const mockContext = createMockExecutionContext({
+    organizationId: 'org-123',
+    executionId: 'exec-456',
+    resourceId: 'agent-789',
+    resourceType: 'agent'
+  })
+
+  const mockCommandQueue = {
+    createTask: vi.fn().mockResolvedValue({ id: 'task-123' })
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockCommandQueue.createTask.mockResolvedValue({ id: 'task-123' })
+    vi.mocked(getToolServices).mockReturnValue({
+      commandQueueService: mockCommandQueue,
+      taskSchedulerService: null,
+      notificationsService: null,
+      credentialsService: null,
+      integrationService: null
+    })
+  })
+
+  it('creates tool with correct properties', () => {
+    const tool = createApprovalTool(mockConfig)
+
+    expect(tool.name).toBe('request_payment_approval')
+    expect(tool.description).toBe('Request approval for payment')
+    expect(tool.inputSchema).toBe(mockConfig.inputSchema)
+    expect(tool.outputSchema).toBe(mockConfig.outputSchema)
+    expect(tool.execute).toBeInstanceOf(Function)
+  })
+
+  it('creates approval task with all parameters', async () => {
+    const tool = createApprovalTool(mockConfig)
+    const input = { amount: 1000, recipient: 'vendor@example.com' }
+
+    const result = await tool.execute({
+      input,
+      executionContext: mockContext
+    })
+
+    expect(result).toEqual({ taskId: 'task-123' })
+    expect(mockCommandQueue.createTask).toHaveBeenCalledWith({
+      organizationId: 'org-123',
+      originExecutionId: 'exec-456',
+      originResourceType: 'agent',
+      originResourceId: 'agent-789',
+      actions: [
+        {
+          id: 'approve',
+          label: 'Approve',
+          type: 'primary',
+          icon: 'IconCheck',
+          color: 'green',
+          target: {
+            resourceType: 'agent',
+            resourceId: 'payment-processor'
+          }
+        },
+        {
+          id: 'reject',
+          label: 'Reject',
+          type: 'danger',
+          icon: 'IconX',
+          color: 'red',
+          target: {
+            resourceType: 'agent',
+            resourceId: 'payment-rejection-handler'
+          }
+        }
+      ],
+      context: input,
+      priority: 8,
+      expiresAt: undefined
+    })
+  })
+
+  it('uses default priority when not specified', async () => {
+    const configNoPriority = { ...mockConfig, priority: undefined }
+    const tool = createApprovalTool(configNoPriority)
+    const input = { amount: 500, recipient: 'test@example.com' }
+
+    await tool.execute({
+      input,
+      executionContext: mockContext
+    })
+
+    expect(mockCommandQueue.createTask).toHaveBeenCalledWith(
+      expect.objectContaining({ priority: 5 })
+    )
+  })
+
+  it('supports optional reject target and expiration', async () => {
+    const expiresAt = new Date('2025-12-31')
+    const configOptional = {
+      ...mockConfig,
+      rejectTargetResourceId: undefined,
+      expiresAt
+    }
+    const tool = createApprovalTool(configOptional)
+
+    await tool.execute({
+      input: { amount: 100, recipient: 'test@test.com' },
+      executionContext: mockContext
+    })
+
+    expect(mockCommandQueue.createTask).toHaveBeenCalledWith(
+      expect.objectContaining({
+        actions: [
+          {
+            id: 'approve',
+            label: 'Approve',
+            type: 'primary',
+            icon: 'IconCheck',
+            color: 'green',
+            target: {
+              resourceType: 'agent',
+              resourceId: 'payment-processor'
+            }
+          }
+        ],
+        expiresAt
+      })
+    )
+  })
+
+  it('throws ToolingError when executionContext is missing', async () => {
+    const tool = createApprovalTool(mockConfig)
+    const input = { amount: 1000, recipient: 'vendor@example.com' }
+
+    await expect(tool.execute({ input })).rejects.toThrow(ToolingError)
+    await expect(tool.execute({ input })).rejects.toThrow(
+      'ExecutionContext is unavailable'
+    )
+  })
+
+  it('throws ToolingError when commandQueue service is unavailable', async () => {
+    vi.mocked(getToolServices).mockReturnValue({
+      commandQueueService: null,
+      taskSchedulerService: null,
+      notificationsService: null,
+      credentialsService: null,
+      integrationService: null
+    })
+
+    const tool = createApprovalTool(mockConfig)
+    const input = { amount: 1000, recipient: 'vendor@example.com' }
+
+    try {
+      await tool.execute({
+        input,
+        executionContext: mockContext
+      })
+      expect.fail('Should have thrown')
+    } catch (error) {
+      expect(error).toBeInstanceOf(ToolingError)
+      const toolingError = error as ToolingError
+      expect(toolingError.errorType).toBe('service_unavailable')
+      expect(toolingError.message).toBe('CommandQueueService is unavailable')
+      expect(toolingError.details).toMatchObject({
+        tool: 'request_payment_approval',
+        message: expect.stringContaining('toolServicesRegistry.initialize()')
+      })
+    }
+  })
+
+  it('propagates errors from commandQueue.createTask', async () => {
+    mockCommandQueue.createTask.mockRejectedValue(new Error('Database error'))
+
+    const tool = createApprovalTool(mockConfig)
+    const input = { amount: 1000, recipient: 'vendor@example.com' }
+
+    await expect(
+      tool.execute({
+        input,
+        executionContext: mockContext
+      })
+    ).rejects.toThrow('Database error')
+  })
+
+  it('handles multiple concurrent approval requests', async () => {
+    mockCommandQueue.createTask
+      .mockResolvedValueOnce({ id: 'task-1' })
+      .mockResolvedValueOnce({ id: 'task-2' })
+      .mockResolvedValueOnce({ id: 'task-3' })
+
+    const tool = createApprovalTool(mockConfig)
+
+    const promises = [
+      tool.execute({
+        input: { amount: 100, recipient: 'a@test.com' },
+        executionContext: mockContext
+      }),
+      tool.execute({
+        input: { amount: 200, recipient: 'b@test.com' },
+        executionContext: mockContext
+      }),
+      tool.execute({
+        input: { amount: 300, recipient: 'c@test.com' },
+        executionContext: mockContext
+      })
+    ]
+
+    const results = await Promise.all(promises)
+
+    expect(results).toEqual([
+      { taskId: 'task-1' },
+      { taskId: 'task-2' },
+      { taskId: 'task-3' }
+    ])
+    expect(mockCommandQueue.createTask).toHaveBeenCalledTimes(3)
+  })
+})