add sleep tool.

Author: bhouston

src/tools/getTools.ts

@@ -1,15 +1,16 @@
-import { subAgentTool } from '../tools/interaction/subAgent.js';
-import { readFileTool } from '../tools/io/readFile.js';
-import { userPromptTool } from '../tools/interaction/userPrompt.js';
-import { sequenceCompleteTool } from '../tools/system/sequenceComplete.js';
-import { fetchTool } from '../tools/io/fetch.js';
+import { subAgentTool } from './interaction/subAgent.js';
+import { readFileTool } from './io/readFile.js';
+import { userPromptTool } from './interaction/userPrompt.js';
+import { sequenceCompleteTool } from './system/sequenceComplete.js';
+import { fetchTool } from './io/fetch.js';
 import { Tool } from '../core/types.js';
 import { updateFileTool } from './io/updateFile.js';
 import { shellStartTool } from './system/shellStart.js';
 import { shellMessageTool } from './system/shellMessage.js';
 import { browseMessageTool } from './browser/browseMessage.js';
 import { browseStartTool } from './browser/browseStart.js';
 import { respawnTool } from './system/respawn.js';
+import { sleepTool } from './system/sleep.js';
 
 export function getTools(): Tool[] {
   return [
@@ -24,5 +25,6 @@ export function getTools(): Tool[] {
     browseStartTool,
     browseMessageTool,
     respawnTool,
+    sleepTool,
   ] as Tool[];
 }

src/tools/index.ts

@@ -23,11 +23,11 @@ export const respawnTool: Tool = {
     type: 'string',
     description: 'A message indicating that the respawn has been initiated',
   },
-  execute: async (
-    params: Record<string, any>,
-    context: ToolContext,
+  execute: (
+    _params: Record<string, any>,
+    _context: ToolContext,
   ): Promise<string> => {
     // This is a special case tool - the actual respawn logic is handled in toolAgent
-    return 'Respawn initiated';
+    return Promise.resolve('Respawn initiated');
   },
 };

src/tools/system/respawn.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { processStates, shellStartTool } from './shellStart.js';
 import { MockLogger } from '../../utils/mockLogger.js';
 import { shellMessageTool, NodeSignals } from './shellMessage.js';
+import { sleep } from '../../utils/sleep.js';
 
 const logger = new MockLogger();
 
@@ -85,7 +86,7 @@ describe('shellMessageTool', () => {
     const instanceId = getInstanceId(startResult);
 
     // Wait a moment for process to complete
-    await new Promise((resolve) => setTimeout(resolve, 150));
+    await sleep(150);
 
     const result = await shellMessageTool.execute(
       {
@@ -123,7 +124,7 @@ describe('shellMessageTool', () => {
     );
     expect(result.signaled).toBe(true);
 
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await sleep(50);
 
     const result2 = await shellMessageTool.execute(
       {
@@ -187,7 +188,7 @@ describe('shellMessageTool', () => {
       { logger },
     );
 
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await sleep(50);
 
     // Check process state after signal
     const checkResult = await shellMessageTool.execute(

src/tools/system/shellMessage.test.ts

@@ -2,6 +2,7 @@ import { Tool } from '../../core/types.js';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { processStates } from './shellStart.js';
+import { sleep } from '../../utils/sleep.js';
 
 // Define NodeJS signals as an enum
 export enum NodeSignals {
@@ -114,7 +115,7 @@ export const shellMessageTool: Tool<Parameters, ReturnType> = {
       }
 
       // Wait a brief moment for output to be processed
-      await new Promise((resolve) => setTimeout(resolve, 100));
+      await sleep(100);
 
       // Get accumulated output
       const stdout = processState.stdout.join('');

src/tools/system/shellMessage.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { processStates, shellStartTool } from './shellStart.js';
 import { MockLogger } from '../../utils/mockLogger.js';
+import { sleep } from '../../utils/sleep.js';
 
 const logger = new MockLogger();
 
@@ -126,7 +127,7 @@ describe('shellStartTool', () => {
         processState.process.stdin.end();
 
         // Wait for output
-        await new Promise((resolve) => setTimeout(resolve, 200));
+        await sleep(200);
 
         // Check stdout in processState
         expect(processState.stdout.join('')).toContain('test');

src/tools/system/shellStart.test.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { Tool } from '../../core/types.js';
+import { sleep } from '../../utils/sleep.js';
+
+const MAX_SLEEP_SECONDS = 3600; // 1 hour
+
+const parametersSchema = z.object({
+  seconds: z
+    .number()
+    .min(0)
+    .max(MAX_SLEEP_SECONDS)
+    .describe('Number of seconds to sleep (max 1 hour)'),
+});
+
+const returnsSchema = z.object({
+  sleptFor: z.number().describe('Actual number of seconds slept'),
+});
+
+export const sleepTool: Tool = {
+  name: 'sleep',
+  description:
+    'Pauses execution for the specified number of seconds, useful when waiting for async tools to make progress before checking on them',
+  parameters: zodToJsonSchema(parametersSchema),
+  returns: zodToJsonSchema(returnsSchema),
+  async execute(params) {
+    const { seconds } = parametersSchema.parse(params);
+
+    await sleep(seconds * 1000);
+
+    return returnsSchema.parse({
+      sleptFor: seconds,
+    });
+  },
+  logParameters({ seconds }, { logger }) {
+    logger.info( `sleeping for ${seconds} seconds` );
+  },
+  logReturns() {
+  },
+};

src/tools/system/sleep.ts

@@ -0,0 +1,2 @@
+export const sleep = (milliseconds: number) =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));

src/utils/sleep.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { sleepTool } from '../../../src/tools/system/sleep';
+
+describe('sleep tool', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it('should sleep for the specified duration', async () => {
+    const startTime = Date.now();
+    const sleepPromise = sleepTool.execute({ seconds: 2 });
+    
+    await vi.advanceTimersByTimeAsync(2000);
+    const result = await sleepPromise;
+    
+    expect(result).toEqual({ sleptFor: 2 });
+  });
+
+  it('should reject negative sleep duration', async () => {
+    await expect(sleepTool.execute({ seconds: -1 })).rejects.toThrow();
+  });
+
+  it('should reject sleep duration over 1 hour', async () => {
+    await expect(sleepTool.execute({ seconds: 3601 })).rejects.toThrow();
+  });
+
+  it('should format log parameters correctly', () => {
+    expect(sleepTool.logParameters({ seconds: 5 })).toBe('sleeping for 5 seconds');
+  });
+
+  it('should format log returns correctly', () => {
+    expect(sleepTool.logReturns({ sleptFor: 5 })).toBe('');
+  });
+});