keystone-cli 0.6.0 → 0.7.0

package/src/runner/standard-tools.ts

@@ -0,0 +1,270 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { ExpressionEvaluator } from '../expression/evaluator';
+import type { AgentTool, Step } from '../parser/schema';
+import { detectShellInjectionRisk } from './shell-executor';
+
+export const STANDARD_TOOLS: AgentTool[] = [
+  {
+    name: 'read_file',
+    description: 'Read the contents of a file',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path to the file to read' },
+      },
+      required: ['path'],
+    },
+    execution: {
+      id: 'std_read_file',
+      type: 'file',
+      op: 'read',
+      path: '${{ args.path }}',
+    },
+  },
+  {
+    name: 'read_file_lines',
+    description: 'Read a specific range of lines from a file',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path to the file to read' },
+        start: { type: 'number', description: 'Starting line number (1-indexed)', default: 1 },
+        count: { type: 'number', description: 'Number of lines to read', default: 100 },
+      },
+      required: ['path'],
+    },
+    execution: {
+      id: 'std_read_file_lines',
+      type: 'script',
+      run: `
+        const fs = require('node:fs');
+        const path = require('node:path');
+        const filePath = args.path;
+        const start = args.start || 1;
+        const count = args.count || 100;
+
+        if (!fs.existsSync(filePath)) {
+          throw new Error('File not found: ' + filePath);
+        }
+
+        const content = fs.readFileSync(filePath, 'utf8');
+        const lines = content.split('\\n');
+        return lines.slice(start - 1, start - 1 + count).join('\\n');
+      `,
+      allowInsecure: true,
+    },
+  },
+  {
+    name: 'write_file',
+    description: 'Write or overwrite a file with content',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path to the file to write' },
+        content: { type: 'string', description: 'Content to write to the file' },
+      },
+      required: ['path', 'content'],
+    },
+    execution: {
+      id: 'std_write_file',
+      type: 'file',
+      op: 'write',
+      path: '${{ args.path }}',
+      content: '${{ args.content }}',
+    },
+  },
+  {
+    name: 'list_files',
+    description: 'List files in a directory',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Directory path (defaults to current directory)',
+          default: '.',
+        },
+      },
+    },
+    execution: {
+      id: 'std_list_files',
+      type: 'script',
+      run: `
+        const fs = require('node:fs');
+        const path = require('node:path');
+        const dir = args.path || '.';
+        if (fs.existsSync(dir)) {
+          const files = fs.readdirSync(dir, { withFileTypes: true });
+          return files.map(f => ({
+            name: f.name,
+            type: f.isDirectory() ? 'directory' : 'file',
+            size: f.isFile() ? fs.statSync(path.join(dir, f.name)).size : undefined
+          }));
+        }
+        throw new Error('Directory not found: ' + dir);
+      `,
+      allowInsecure: true,
+    },
+  },
+  {
+    name: 'search_files',
+    description: 'Search for files by pattern (glob)',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'Glob pattern (e.g. **/*.ts)' },
+        dir: { type: 'string', description: 'Directory to search in', default: '.' },
+      },
+      required: ['pattern'],
+    },
+    execution: {
+      id: 'std_search_files',
+      type: 'script',
+      run: `
+        const fs = require('node:fs');
+        const path = require('node:path');
+        const { globSync } = require('glob');
+        const dir = args.dir || '.';
+        const pattern = args.pattern;
+        try {
+          return globSync(pattern, { cwd: dir, nodir: true });
+        } catch (e) {
+          throw new Error('Search failed: ' + e.message);
+        }
+      `,
+      allowInsecure: true,
+    },
+  },
+  {
+    name: 'search_content',
+    description: 'Search for a string or regex within files',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'String or regex to search for' },
+        pattern: {
+          type: 'string',
+          description: 'Glob pattern of files to search in',
+          default: '**/*',
+        },
+        dir: { type: 'string', description: 'Directory to search in', default: '.' },
+      },
+      required: ['query'],
+    },
+    execution: {
+      id: 'std_search_content',
+      type: 'script',
+      run: `
+        const fs = require('node:fs');
+        const path = require('node:path');
+        const { globSync } = require('glob');
+        const dir = args.dir || '.';
+        const pattern = args.pattern || '**/*';
+        const query = args.query;
+        if (query.length > 500) {
+          throw new Error('Search query exceeds maximum length of 500 characters');
+        }
+        const isRegex = query.startsWith('/') && query.endsWith('/');
+        let regex;
+        try {
+          regex = isRegex ? new RegExp(query.slice(1, -1)) : new RegExp(query.replace(/[.*+?^$\\{}()|[\\]\\\\]/g, '\\\\$&'), 'i');
+        } catch (e) {
+          throw new Error('Invalid regular expression: ' + e.message);
+        }
+
+        const files = globSync(pattern, { cwd: dir, nodir: true });
+        const results = [];
+        for (const file of files) {
+          const fullPath = path.join(dir, file);
+          const content = fs.readFileSync(fullPath, 'utf8');
+          const lines = content.split('\\n');
+          for (let i = 0; i < lines.length; i++) {
+            if (regex.test(lines[i])) {
+              results.push({
+                file,
+                line: i + 1,
+                content: lines[i].trim()
+              });
+            }
+            if (results.length > 100) break; // Limit results
+          }
+          if (results.length > 100) break;
+        }
+        return results;
+      `,
+      allowInsecure: true,
+    },
+  },
+  {
+    name: 'run_command',
+    description: 'Run a shell command',
+    parameters: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'The shell command to run' },
+        dir: { type: 'string', description: 'Working directory for the command' },
+      },
+      required: ['command'],
+    },
+    execution: {
+      id: 'std_run_command',
+      type: 'shell',
+      run: '${{ args.command }}',
+      dir: '${{ args.dir }}',
+    },
+  },
+];
+
+/**
+ * Validate that a tool call is safe to execute based on the LLM step's security flags.
+ */
+export function validateStandardToolSecurity(
+  toolName: string,
+  // biome-ignore lint/suspicious/noExplicitAny: arguments can be any shape
+  args: any,
+  options: { allowOutsideCwd?: boolean; allowInsecure?: boolean }
+): void {
+  // 1. Check path traversal for file tools
+  if (
+    [
+      'read_file',
+      'read_file_lines',
+      'write_file',
+      'list_files',
+      'search_files',
+      'search_content',
+    ].includes(toolName)
+  ) {
+    const rawPath = args.path || args.dir || '.';
+    const cwd = process.cwd();
+    const resolvedPath = path.resolve(cwd, rawPath);
+    const realCwd = fs.realpathSync(cwd);
+
+    const isWithin = (target: string) => {
+      // Find the first existing ancestor to resolve the real path correctly
+      let current = target;
+      while (current !== path.dirname(current) && !fs.existsSync(current)) {
+        current = path.dirname(current);
+      }
+      const realTarget = fs.existsSync(current) ? fs.realpathSync(current) : current;
+      const relativePath = path.relative(realCwd, realTarget);
+      return !(relativePath.startsWith('..') || path.isAbsolute(relativePath));
+    };
+
+    if (!options.allowOutsideCwd && !isWithin(resolvedPath)) {
+      throw new Error(
+        `Access denied: Path '${rawPath}' resolves outside the working directory. Use 'allowOutsideCwd: true' to override.`
+      );
+    }
+  }
+
+  // 2. Check shell risk for run_command
+  if (toolName === 'run_command' && !options.allowInsecure) {
+    if (detectShellInjectionRisk(args.command)) {
+      throw new Error(
+        `Security Error: Command contains risky shell characters. Use 'allowInsecure: true' on the llm step to execute this.`
+      );
+    }
+  }
+}

package/src/runner/step-executor.test.ts

@@ -13,6 +13,7 @@ import * as dns from 'node:dns/promises';
 import { mkdirSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import type { MemoryDb } from '../db/memory-db';
 import type { ExpressionContext } from '../expression/evaluator';
 import type {
   FileStep,
@@ -22,6 +23,8 @@ import type {
   SleepStep,
   WorkflowStep,
 } from '../parser/schema';
+import type { SafeSandbox } from '../utils/sandbox';
+import type { getAdapter } from './llm-adapter';
 import { executeStep } from './step-executor';
 
 // Mock executeLlmStep
@@ -227,6 +230,196 @@ describe('step-executor', () => {
         }
       }
     });
+
+    it('should block path traversal outside cwd by default', async () => {
+      const outsidePath = join(process.cwd(), '..', 'outside.txt');
+      const step: FileStep = {
+        id: 'f1',
+        type: 'file',
+        needs: [],
+        op: 'read',
+        path: outsidePath,
+      };
+
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('Access denied');
+    });
+
+    it('should block path traversal with .. inside path resolving outside', async () => {
+      const outsidePath = 'foo/../../passwd';
+      const step: FileStep = {
+        id: 'f1',
+        type: 'file',
+        needs: [],
+        op: 'read',
+        path: outsidePath,
+      };
+
+      const result = await executeStep(step, context);
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('Access denied');
+    });
+  });
+
+  describe('script', () => {
+    const mockSandbox = {
+      execute: mock((code) => {
+        if (code === 'fail') throw new Error('Script failed');
+        return Promise.resolve('script-result');
+      }),
+    };
+
+    it('should fail if allowInsecure is not set', async () => {
+      // @ts-ignore
+      const step = {
+        id: 's1',
+        type: 'script',
+        run: 'console.log("hello")',
+      };
+      const result = await executeStep(step, context, undefined, {
+        sandbox: mockSandbox as unknown as typeof SafeSandbox,
+      });
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('Script execution is disabled by default');
+    });
+
+    it('should execute script if allowInsecure is true', async () => {
+      // @ts-ignore
+      const step = {
+        id: 's1',
+        type: 'script',
+        run: 'console.log("hello")',
+        allowInsecure: true,
+      };
+      const result = await executeStep(step, context, undefined, {
+        sandbox: mockSandbox as unknown as typeof SafeSandbox,
+      });
+      expect(result.status).toBe('success');
+      expect(result.output).toBe('script-result');
+    });
+
+    it('should handle script failure', async () => {
+      // @ts-ignore
+      const step = {
+        id: 's1',
+        type: 'script',
+        run: 'fail',
+        allowInsecure: true,
+      };
+      const result = await executeStep(step, context, undefined, {
+        sandbox: mockSandbox as unknown as typeof SafeSandbox,
+      });
+      expect(result.status).toBe('failed');
+      expect(result.error).toBe('Script failed');
+    });
+  });
+
+  describe('memory', () => {
+    const mockMemoryDb = {
+      store: mock(() => Promise.resolve('mem-id')),
+      search: mock(() => Promise.resolve([{ content: 'found', similarity: 0.9 }])),
+    };
+
+    const mockGetAdapter = mock((model) => {
+      if (model === 'no-embed') return { adapter: {}, resolvedModel: model };
+      return {
+        adapter: {
+          embed: mock((text) => Promise.resolve([0.1, 0.2, 0.3])),
+        },
+        resolvedModel: model,
+      };
+    });
+
+    it('should fail if memoryDb is not provided', async () => {
+      // @ts-ignore
+      const step = { id: 'm1', type: 'memory', op: 'store', text: 'foo' };
+      const result = await executeStep(step, context, undefined, {
+        getAdapter: mockGetAdapter as unknown as typeof getAdapter,
+      });
+      expect(result.status).toBe('failed');
+      expect(result.error).toBe('Memory database not initialized');
+    });
+
+    it('should fail if adapter does not support embedding', async () => {
+      // @ts-ignore
+      const step = { id: 'm1', type: 'memory', op: 'store', text: 'foo', model: 'no-embed' };
+      // @ts-ignore
+      const result = await executeStep(step, context, undefined, {
+        memoryDb: mockMemoryDb as unknown as MemoryDb,
+        getAdapter: mockGetAdapter as unknown as typeof getAdapter,
+      });
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('does not support embeddings');
+    });
+
+    it('should store memory', async () => {
+      // @ts-ignore
+      const step = {
+        id: 'm1',
+        type: 'memory',
+        op: 'store',
+        text: 'foo',
+        metadata: { source: 'test' },
+      };
+      // @ts-ignore
+      const result = await executeStep(step, context, undefined, {
+        memoryDb: mockMemoryDb as unknown as MemoryDb,
+        getAdapter: mockGetAdapter as unknown as typeof getAdapter,
+      });
+      expect(result.status).toBe('success');
+      expect(result.output).toEqual({ id: 'mem-id', status: 'stored' });
+      expect(mockMemoryDb.store).toHaveBeenCalledWith('foo', [0.1, 0.2, 0.3], { source: 'test' });
+    });
+
+    it('should search memory', async () => {
+      // @ts-ignore
+      const step = { id: 'm1', type: 'memory', op: 'search', query: 'foo', limit: 5 };
+      // @ts-ignore
+      const result = await executeStep(step, context, undefined, {
+        memoryDb: mockMemoryDb as unknown as MemoryDb,
+        getAdapter: mockGetAdapter as unknown as typeof getAdapter,
+      });
+      expect(result.status).toBe('success');
+      expect(result.output).toEqual([{ content: 'found', similarity: 0.9 }]);
+      expect(mockMemoryDb.search).toHaveBeenCalledWith([0.1, 0.2, 0.3], 5);
+    });
+
+    it('should fail store if text is missing', async () => {
+      // @ts-ignore
+      const step = { id: 'm1', type: 'memory', op: 'store' };
+      // @ts-ignore
+      const result = await executeStep(step, context, undefined, {
+        memoryDb: mockMemoryDb as unknown as MemoryDb,
+        getAdapter: mockGetAdapter as unknown as typeof getAdapter,
+      });
+      expect(result.status).toBe('failed');
+      expect(result.error).toBe('Text is required for memory store operation');
+    });
+
+    it('should fail search if query is missing', async () => {
+      // @ts-ignore
+      const step = { id: 'm1', type: 'memory', op: 'search' };
+      // @ts-ignore
+      const result = await executeStep(step, context, undefined, {
+        memoryDb: mockMemoryDb as unknown as MemoryDb,
+        getAdapter: mockGetAdapter as unknown as typeof getAdapter,
+      });
+      expect(result.status).toBe('failed');
+      expect(result.error).toBe('Query is required for memory search operation');
+    });
+
+    it('should fail for unknown memory operation', async () => {
+      // @ts-ignore
+      const step = { id: 'm1', type: 'memory', op: 'unknown', text: 'foo' };
+      // @ts-ignore
+      const result = await executeStep(step, context, undefined, {
+        memoryDb: mockMemoryDb as unknown as MemoryDb,
+        getAdapter: mockGetAdapter as unknown as typeof getAdapter,
+      });
+      expect(result.status).toBe('failed');
+      expect(result.error).toContain('Unknown memory operation');
+    });
   });
 
   describe('sleep', () => {
@@ -517,7 +710,7 @@ describe('step-executor', () => {
       );
 
       // @ts-ignore
-      const result = await executeStep(step, context, undefined, executeWorkflowFn);
+      const result = await executeStep(step, context, undefined, { executeWorkflowFn });
       expect(result.status).toBe('success');
       expect(result.output).toBe('child-output');
       expect(executeWorkflowFn).toHaveBeenCalled();

package/src/runner/step-executor.ts

@@ -48,6 +48,20 @@ export interface StepResult {
   };
 }
 
+/**
+ * Execute a single step based on its type
+ */
+export interface StepExecutorOptions {
+  executeWorkflowFn?: (step: WorkflowStep, context: ExpressionContext) => Promise<StepResult>;
+  mcpManager?: MCPManager;
+  memoryDb?: MemoryDb;
+  workflowDir?: string;
+  dryRun?: boolean;
+  // Dependency injection for testing
+  getAdapter?: typeof getAdapter;
+  sandbox?: typeof SafeSandbox;
+}
+
 /**
  * Execute a single step based on its type
  */
@@ -55,12 +69,18 @@ export async function executeStep(
   step: Step,
   context: ExpressionContext,
   logger: Logger = new ConsoleLogger(),
-  executeWorkflowFn?: (step: WorkflowStep, context: ExpressionContext) => Promise<StepResult>,
-  mcpManager?: MCPManager,
-  memoryDb?: MemoryDb,
-  workflowDir?: string,
-  dryRun?: boolean
+  options: StepExecutorOptions = {}
 ): Promise<StepResult> {
+  const {
+    executeWorkflowFn,
+    mcpManager,
+    memoryDb,
+    workflowDir,
+    dryRun,
+    getAdapter: injectedGetAdapter,
+    sandbox: injectedSandbox,
+  } = options;
+
   try {
     let result: StepResult;
     switch (step.type) {
@@ -83,15 +103,14 @@ export async function executeStep(
         result = await executeLlmStep(
           step,
           context,
-          (s, c) =>
-            executeStep(s, c, logger, executeWorkflowFn, mcpManager, memoryDb, workflowDir, dryRun),
+          (s, c) => executeStep(s, c, logger, options),
           logger,
           mcpManager,
           workflowDir
         );
         break;
       case 'memory':
-        result = await executeMemoryStep(step, context, logger, memoryDb);
+        result = await executeMemoryStep(step, context, logger, memoryDb, injectedGetAdapter);
         break;
       case 'workflow':
         if (!executeWorkflowFn) {
@@ -100,7 +119,7 @@ export async function executeStep(
         result = await executeWorkflowFn(step, context);
         break;
       case 'script':
-        result = await executeScriptStep(step, context, logger);
+        result = await executeScriptStep(step, context, logger, injectedSandbox);
         break;
       default:
         throw new Error(`Unknown step type: ${(step as Step).type}`);
@@ -383,7 +402,13 @@ async function executeRequestStep(
     output: {
       status: response.status,
       statusText: response.statusText,
-      headers: Object.fromEntries(response.headers.entries()),
+      headers: (() => {
+        const h: Record<string, string> = {};
+        response.headers.forEach((v, k) => {
+          h[k] = v;
+        });
+        return h;
+      })(),
       data: responseData,
     },
     status: response.ok ? 'success' : 'failed',
@@ -416,7 +441,11 @@ async function executeHumanStep(
     return {
       output:
         step.inputType === 'confirm'
-          ? answer === true || answer === 'true' || answer === 'yes' || answer === 'y'
+          ? answer === true ||
+            (typeof answer === 'string' &&
+              (answer.toLowerCase() === 'true' ||
+                answer.toLowerCase() === 'yes' ||
+                answer.toLowerCase() === 'y'))
           : answer,
       status: 'success',
     };
@@ -503,7 +532,8 @@ async function executeSleepStep(
 async function executeScriptStep(
   step: ScriptStep,
   context: ExpressionContext,
-  _logger: Logger
+  _logger: Logger,
+  sandbox = SafeSandbox
 ): Promise<StepResult> {
   try {
     if (!step.allowInsecure) {
@@ -513,7 +543,7 @@ async function executeScriptStep(
       );
     }
 
-    const result = await SafeSandbox.execute(
+    const result = await sandbox.execute(
       step.run,
       {
         inputs: context.inputs,
@@ -546,14 +576,15 @@ async function executeMemoryStep(
   step: MemoryStep,
   context: ExpressionContext,
   logger: Logger,
-  memoryDb?: MemoryDb
+  memoryDb?: MemoryDb,
+  getAdapterFn = getAdapter
 ): Promise<StepResult> {
   if (!memoryDb) {
     throw new Error('Memory database not initialized');
   }
 
   try {
-    const { adapter, resolvedModel } = getAdapter(step.model || 'local');
+    const { adapter, resolvedModel } = getAdapterFn(step.model || 'local');
     if (!adapter.embed) {
       throw new Error(`Provider for model ${step.model || 'local'} does not support embeddings`);
     }