keystone-cli 0.1.0

package/src/runner/step-executor.ts

@@ -0,0 +1,354 @@
+import type { ExpressionContext } from '../expression/evaluator.ts';
+import { ExpressionEvaluator } from '../expression/evaluator.ts';
+// Removed synchronous file I/O imports - using Bun's async file API instead
+import type {
+  FileStep,
+  HumanStep,
+  RequestStep,
+  ShellStep,
+  SleepStep,
+  Step,
+  WorkflowStep,
+} from '../parser/schema.ts';
+import { executeShell } from './shell-executor.ts';
+import type { Logger } from './workflow-runner.ts';
+
+import * as readline from 'node:readline/promises';
+import { executeLlmStep } from './llm-executor.ts';
+import type { MCPManager } from './mcp-manager.ts';
+
+export class WorkflowSuspendedError extends Error {
+  constructor(
+    public readonly message: string,
+    public readonly stepId: string,
+    public readonly inputType: 'confirm' | 'text'
+  ) {
+    super(message);
+    this.name = 'WorkflowSuspendedError';
+  }
+}
+
+export interface StepResult {
+  output: unknown;
+  status: 'success' | 'failed' | 'suspended';
+  error?: string;
+}
+
+/**
+ * Execute a single step based on its type
+ */
+export async function executeStep(
+  step: Step,
+  context: ExpressionContext,
+  logger: Logger = console,
+  executeWorkflowFn?: (step: WorkflowStep, context: ExpressionContext) => Promise<StepResult>,
+  mcpManager?: MCPManager
+): Promise<StepResult> {
+  try {
+    let result: StepResult;
+    switch (step.type) {
+      case 'shell':
+        result = await executeShellStep(step, context, logger);
+        break;
+      case 'file':
+        result = await executeFileStep(step, context, logger);
+        break;
+      case 'request':
+        result = await executeRequestStep(step, context, logger);
+        break;
+      case 'human':
+        result = await executeHumanStep(step, context, logger);
+        break;
+      case 'sleep':
+        result = await executeSleepStep(step, context, logger);
+        break;
+      case 'llm':
+        result = await executeLlmStep(
+          step,
+          context,
+          (s, c) => executeStep(s, c, logger, executeWorkflowFn, mcpManager),
+          logger,
+          mcpManager
+        );
+        break;
+      case 'workflow':
+        if (!executeWorkflowFn) {
+          throw new Error('Workflow executor not provided');
+        }
+        result = await executeWorkflowFn(step, context);
+        break;
+      default:
+        throw new Error(`Unknown step type: ${(step as Step).type}`);
+    }
+
+    // Apply transformation if specified and step succeeded
+    if (step.transform && result.status === 'success') {
+      const transformContext = {
+        // Provide raw output properties (like stdout, data) directly in context
+        // Fix: Spread output FIRST, then context to prevent shadowing
+        ...(typeof result.output === 'object' && result.output !== null ? result.output : {}),
+        output: result.output,
+        ...context,
+      };
+
+      try {
+        // If it's wrapped in ${{ }}, extract it, otherwise treat as raw expression
+        let expr = step.transform.trim();
+        if (expr.startsWith('${{') && expr.endsWith('}}')) {
+          expr = expr.slice(3, -2).trim();
+        }
+        result.output = ExpressionEvaluator.evaluateExpression(expr, transformContext);
+      } catch (error) {
+        throw new Error(
+          `Transform failed for step ${step.id}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+
+    return result;
+  } catch (error) {
+    return {
+      output: null,
+      status: 'failed',
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Execute a shell step
+ */
+async function executeShellStep(
+  step: ShellStep,
+  context: ExpressionContext,
+  logger: Logger
+): Promise<StepResult> {
+  const result = await executeShell(step, context, logger);
+
+  if (result.stdout) {
+    logger.log(result.stdout.trim());
+  }
+
+  if (result.exitCode !== 0) {
+    return {
+      output: {
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+      },
+      status: 'failed',
+      error: `Shell command exited with code ${result.exitCode}: ${result.stderr}`,
+    };
+  }
+
+  return {
+    output: {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exitCode,
+    },
+    status: 'success',
+  };
+}
+
+/**
+ * Execute a file step (read, write, append)
+ */
+async function executeFileStep(
+  step: FileStep,
+  context: ExpressionContext,
+  _logger: Logger
+): Promise<StepResult> {
+  const path = ExpressionEvaluator.evaluate(step.path, context) as string;
+
+  switch (step.op) {
+    case 'read': {
+      const file = Bun.file(path);
+      if (!(await file.exists())) {
+        throw new Error(`File not found: ${path}`);
+      }
+      const content = await file.text();
+      return {
+        output: content,
+        status: 'success',
+      };
+    }
+
+    case 'write': {
+      if (!step.content) {
+        throw new Error('Content is required for write operation');
+      }
+      const content = ExpressionEvaluator.evaluate(step.content, context) as string;
+      const bytes = await Bun.write(path, content);
+      return {
+        output: { path, bytes },
+        status: 'success',
+      };
+    }
+
+    case 'append': {
+      if (!step.content) {
+        throw new Error('Content is required for append operation');
+      }
+      const content = ExpressionEvaluator.evaluate(step.content, context) as string;
+
+      // Use Node.js fs for efficient append operation
+      const fs = await import('node:fs/promises');
+      await fs.appendFile(path, content, 'utf-8');
+
+      return {
+        output: { path, bytes: content.length },
+        status: 'success',
+      };
+    }
+
+    default:
+      throw new Error(`Unknown file operation: ${step.op}`);
+  }
+}
+
+/**
+ * Execute an HTTP request step
+ */
+async function executeRequestStep(
+  step: RequestStep,
+  context: ExpressionContext,
+  _logger: Logger
+): Promise<StepResult> {
+  const url = ExpressionEvaluator.evaluate(step.url, context) as string;
+
+  // Evaluate headers
+  const headers: Record<string, string> = {};
+  if (step.headers) {
+    for (const [key, value] of Object.entries(step.headers)) {
+      headers[key] = ExpressionEvaluator.evaluate(value, context) as string;
+    }
+  }
+
+  // Evaluate body
+  let body: string | undefined;
+  if (step.body) {
+    const evaluatedBody = ExpressionEvaluator.evaluateObject(step.body, context);
+
+    const contentType = Object.entries(headers).find(
+      ([k]) => k.toLowerCase() === 'content-type'
+    )?.[1];
+
+    if (contentType?.includes('application/x-www-form-urlencoded')) {
+      if (typeof evaluatedBody === 'object' && evaluatedBody !== null) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(evaluatedBody)) {
+          params.append(key, String(value));
+        }
+        body = params.toString();
+      } else {
+        body = String(evaluatedBody);
+      }
+    } else {
+      // Default to JSON if not form-encoded and not already a string
+      body = typeof evaluatedBody === 'string' ? evaluatedBody : JSON.stringify(evaluatedBody);
+
+      // Auto-set Content-Type to application/json if not already set and body is an object
+      if (!contentType && typeof evaluatedBody === 'object' && evaluatedBody !== null) {
+        headers['Content-Type'] = 'application/json';
+      }
+    }
+  }
+
+  const response = await fetch(url, {
+    method: step.method,
+    headers,
+    body,
+  });
+
+  const responseText = await response.text();
+  let responseData: unknown;
+
+  try {
+    responseData = JSON.parse(responseText);
+  } catch {
+    responseData = responseText;
+  }
+
+  return {
+    output: {
+      status: response.status,
+      statusText: response.statusText,
+      headers: Object.fromEntries(response.headers.entries()),
+      data: responseData,
+    },
+    status: response.ok ? 'success' : 'failed',
+    error: response.ok ? undefined : `HTTP ${response.status}: ${response.statusText}`,
+  };
+}
+
+/**
+ * Execute a human input step
+ */
+async function executeHumanStep(
+  step: HumanStep,
+  context: ExpressionContext,
+  logger: Logger
+): Promise<StepResult> {
+  const message = ExpressionEvaluator.evaluate(step.message, context) as string;
+
+  // If not a TTY (e.g. MCP server), suspend execution
+  if (!process.stdin.isTTY) {
+    return {
+      output: null,
+      status: 'suspended',
+      error: message,
+    };
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    if (step.inputType === 'confirm') {
+      logger.log(`\n❓ ${message}`);
+      logger.log('Press Enter to continue, or Ctrl+C to cancel...');
+      await rl.question('');
+      return {
+        output: true,
+        status: 'success',
+      };
+    }
+
+    // Text input
+    logger.log(`\n❓ ${message}`);
+    logger.log('Enter your response:');
+    const input = await rl.question('');
+    return {
+      output: input.trim(),
+      status: 'success',
+    };
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Execute a sleep step
+ */
+async function executeSleepStep(
+  step: SleepStep,
+  context: ExpressionContext,
+  _logger: Logger
+): Promise<StepResult> {
+  const evaluated = ExpressionEvaluator.evaluate(step.duration.toString(), context);
+  const duration = Number(evaluated);
+
+  if (Number.isNaN(duration)) {
+    throw new Error(`Invalid sleep duration: ${evaluated}`);
+  }
+
+  await new Promise((resolve) => setTimeout(resolve, duration));
+
+  return {
+    output: { slept: duration },
+    status: 'success',
+  };
+}

package/src/runner/timeout.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'bun:test';
+import { TimeoutError, withTimeout } from './timeout';
+
+describe('timeout', () => {
+  it('should resolve if the promise completes before the timeout', async () => {
+    const promise = Promise.resolve('ok');
+    const result = await withTimeout(promise, 100);
+    expect(result).toBe('ok');
+  });
+
+  it('should reject if the promise takes longer than the timeout', async () => {
+    const promise = new Promise((resolve) => setTimeout(() => resolve('ok'), 200));
+    await expect(withTimeout(promise, 50)).rejects.toThrow(TimeoutError);
+  });
+
+  it('should include the operation name in the error message', async () => {
+    const promise = new Promise((resolve) => setTimeout(() => resolve('ok'), 100));
+    await expect(withTimeout(promise, 10, 'MyStep')).rejects.toThrow(/MyStep timed out/);
+  });
+});

package/src/runner/timeout.ts

@@ -0,0 +1,30 @@
+/**
+ * Execute a promise with a timeout
+ * Throws a TimeoutError if the operation exceeds the timeout
+ */
+export class TimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TimeoutError';
+  }
+}
+
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  operation = 'Operation'
+): Promise<T> {
+  let timeoutId: Timer;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new TimeoutError(`${operation} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

package/src/runner/tool-integration.test.ts

@@ -0,0 +1,198 @@
+import { afterAll, beforeAll, describe, expect, it, mock } from 'bun:test';
+import { OpenAIAdapter, CopilotAdapter, AnthropicAdapter } from './llm-adapter';
+import { MCPClient } from './mcp-client';
+import { executeLlmStep } from './llm-executor';
+import type { LlmStep, Step } from '../parser/schema';
+import type { ExpressionContext } from '../expression/evaluator';
+import type { StepResult } from './step-executor';
+import { join } from 'node:path';
+import { mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
+
+interface MockToolCall {
+  function: {
+    name: string;
+  };
+}
+
+describe('llm-executor with tools and MCP', () => {
+  const agentsDir = join(process.cwd(), '.keystone', 'workflows', 'agents');
+  const agentPath = join(agentsDir, 'tool-test-agent.md');
+
+  beforeAll(() => {
+    try {
+      mkdirSync(agentsDir, { recursive: true });
+    } catch (e) {}
+    const agentContent = `---
+name: tool-test-agent
+tools:
+  - name: agent-tool
+    execution:
+      id: agent-tool-exec
+      type: shell
+      run: echo "agent tool"
+---
+Test system prompt`;
+    writeFileSync(agentPath, agentContent);
+  });
+
+  afterAll(() => {
+    try {
+      unlinkSync(agentPath);
+    } catch (e) {}
+  });
+
+  it('should merge tools from agent, step and MCP', async () => {
+    const originalOpenAIChat = OpenAIAdapter.prototype.chat;
+    const originalCopilotChat = CopilotAdapter.prototype.chat;
+    const originalAnthropicChat = AnthropicAdapter.prototype.chat;
+    let capturedTools: MockToolCall[] = [];
+
+    const mockChat = mock(async (_messages: unknown, options: unknown) => {
+      capturedTools = (options as { tools?: MockToolCall[] })?.tools || [];
+      return {
+        message: { role: 'assistant', content: 'Final response' },
+      };
+    });
+
+    OpenAIAdapter.prototype.chat = mockChat as any;
+    CopilotAdapter.prototype.chat = mockChat as any;
+    AnthropicAdapter.prototype.chat = mockChat as any;
+
+    // Use mock.module for MCPClient
+    const originalInitialize = MCPClient.prototype.initialize;
+    const originalListTools = MCPClient.prototype.listTools;
+    const originalStop = MCPClient.prototype.stop;
+
+    const mockInitialize = mock(async () => ({}) as any);
+    const mockListTools = mock(async () => [
+      {
+        name: 'mcp-tool',
+        description: 'MCP tool',
+        inputSchema: { type: 'object', properties: {} },
+      },
+    ]);
+    const mockStop = mock(() => {});
+
+    MCPClient.prototype.initialize = mockInitialize;
+    MCPClient.prototype.listTools = mockListTools;
+    MCPClient.prototype.stop = mockStop;
+
+    const step: LlmStep = {
+      id: 'l1',
+      type: 'llm',
+      agent: 'tool-test-agent',
+      prompt: 'test',
+      needs: [],
+      tools: [
+        {
+          name: 'step-tool',
+          execution: { id: 'step-tool-exec', type: 'shell', run: 'echo step' },
+        },
+      ],
+      mcpServers: [{ name: 'test-mcp', command: 'node', args: ['-e', ''] }],
+    };
+
+    const context: ExpressionContext = { inputs: {}, steps: {} };
+    const executeStepFn = async () => ({ status: 'success' as const, output: {} });
+
+    await executeLlmStep(
+      step,
+      context,
+      executeStepFn as unknown as (step: Step, context: ExpressionContext) => Promise<StepResult>
+    );
+
+    const toolNames = capturedTools.map((t) => t.function.name);
+    expect(toolNames).toContain('agent-tool');
+    expect(toolNames).toContain('step-tool');
+    expect(toolNames).toContain('mcp-tool');
+
+    OpenAIAdapter.prototype.chat = originalOpenAIChat;
+    CopilotAdapter.prototype.chat = originalCopilotChat;
+    AnthropicAdapter.prototype.chat = originalAnthropicChat;
+    MCPClient.prototype.initialize = originalInitialize;
+    MCPClient.prototype.listTools = originalListTools;
+    MCPClient.prototype.stop = originalStop;
+  });
+
+  it('should execute MCP tool when called', async () => {
+    const originalOpenAIChat = OpenAIAdapter.prototype.chat;
+    const originalCopilotChat = CopilotAdapter.prototype.chat;
+    const originalAnthropicChat = AnthropicAdapter.prototype.chat;
+    let chatCount = 0;
+
+    const mockChat = mock(async () => {
+      chatCount++;
+      if (chatCount === 1) {
+        return {
+          message: {
+            role: 'assistant',
+            tool_calls: [
+              {
+                id: 'call-1',
+                type: 'function',
+                function: { name: 'mcp-tool', arguments: '{}' },
+              },
+            ],
+          },
+        };
+      }
+      return {
+        message: { role: 'assistant', content: 'Done' },
+      };
+    });
+
+    OpenAIAdapter.prototype.chat = mockChat as any;
+    CopilotAdapter.prototype.chat = mockChat as any;
+    AnthropicAdapter.prototype.chat = mockChat as any;
+
+    const originalInitialize = MCPClient.prototype.initialize;
+    const originalListTools = MCPClient.prototype.listTools;
+    const originalCallTool = MCPClient.prototype.callTool;
+    const originalStop = MCPClient.prototype.stop;
+
+    const mockInitialize = mock(async () => ({}) as any);
+    const mockListTools = mock(async () => [
+      {
+        name: 'mcp-tool',
+        description: 'MCP tool',
+        inputSchema: { type: 'object', properties: {} },
+      },
+    ]);
+    const mockCallTool = mock(async () => ({ result: 'mcp success' }));
+    const mockStop = mock(() => {});
+
+    MCPClient.prototype.initialize = mockInitialize;
+    MCPClient.prototype.listTools = mockListTools;
+    MCPClient.prototype.callTool = mockCallTool;
+    MCPClient.prototype.stop = mockStop;
+
+    const step: LlmStep = {
+      id: 'l1',
+      type: 'llm',
+      agent: 'tool-test-agent',
+      prompt: 'test',
+      needs: [],
+      mcpServers: [{ name: 'test-mcp', command: 'node', args: ['-e', ''] }],
+    };
+
+    const context: ExpressionContext = { inputs: {}, steps: {} };
+    const executeStepFn = async () => ({ status: 'success' as const, output: {} });
+
+    await executeLlmStep(
+      step,
+      context,
+      executeStepFn as unknown as (step: Step, context: ExpressionContext) => Promise<StepResult>
+    );
+
+    expect(mockCallTool).toHaveBeenCalledWith('mcp-tool', {});
+    expect(chatCount).toBe(2);
+
+    OpenAIAdapter.prototype.chat = originalOpenAIChat;
+    CopilotAdapter.prototype.chat = originalCopilotChat;
+    AnthropicAdapter.prototype.chat = originalAnthropicChat;
+    MCPClient.prototype.initialize = originalInitialize;
+    MCPClient.prototype.listTools = originalListTools;
+    MCPClient.prototype.callTool = originalCallTool;
+    MCPClient.prototype.stop = originalStop;
+  });
+});