@machina.ai/cell-cli-core 1.10.0-rc1 → 1.13.0-rc1

package/dist/src/agents/executor.test.js

@@ -8,15 +8,15 @@ import { AgentExecutor } from './executor.js';
 import { makeFakeConfig } from '../test-utils/config.js';
 import { ToolRegistry } from '../tools/tool-registry.js';
 import { LSTool } from '../tools/ls.js';
-import { ReadFileTool } from '../tools/read-file.js';
+import { LS_TOOL_NAME, READ_FILE_TOOL_NAME } from '../tools/tool-names.js';
 import { GeminiChat, StreamEventType, } from '../core/geminiChat.js';
 import {} from '@google/genai';
 import { MockTool } from '../test-utils/mock-tool.js';
 import { getDirectoryContextString } from '../utils/environmentContext.js';
 import { z } from 'zod';
 import { promptIdContext } from '../utils/promptIdContext.js';
-import { logAgentStart, logAgentFinish } from '../telemetry/loggers.js';
-import { AgentStartEvent, AgentFinishEvent } from '../telemetry/types.js';
+import { logAgentStart, logAgentFinish, logRecoveryAttempt, } from '../telemetry/loggers.js';
+import { AgentStartEvent, AgentFinishEvent, RecoveryAttemptEvent, } from '../telemetry/types.js';
 import { AgentTerminateMode } from './types.js';
 const { mockSendMessageStream, mockExecuteToolCall } = vi.hoisted(() => ({
     mockSendMessageStream: vi.fn(),
@@ -38,6 +38,7 @@ vi.mock('../utils/environmentContext.js');
 vi.mock('../telemetry/loggers.js', () => ({
     logAgentStart: vi.fn(),
     logAgentFinish: vi.fn(),
+    logRecoveryAttempt: vi.fn(),
 }));
 vi.mock('../utils/promptIdContext.js', async (importOriginal) => {
     const actual = await importOriginal();
@@ -55,6 +56,7 @@ const mockedGetDirectoryContextString = vi.mocked(getDirectoryContextString);
 const mockedPromptIdContext = vi.mocked(promptIdContext);
 const mockedLogAgentStart = vi.mocked(logAgentStart);
 const mockedLogAgentFinish = vi.mocked(logAgentFinish);
+const mockedLogRecoveryAttempt = vi.mocked(logRecoveryAttempt);
 // Constants for testing
 const TASK_COMPLETE_TOOL_NAME = 'complete_task';
 const MOCK_TOOL_NOT_ALLOWED = new MockTool({ name: 'write_file_interactive' });
@@ -102,7 +104,7 @@ let parentToolRegistry;
 /**
  * Type-safe helper to create agent definitions for tests.
  */
-const createTestDefinition = (tools = [LSTool.Name], runConfigOverrides = {}, outputConfigMode = 'default', schema = z.string()) => {
+const createTestDefinition = (tools = [LS_TOOL_NAME], runConfigOverrides = {}, outputConfigMode = 'default', schema = z.string()) => {
     let outputConfig;
     if (outputConfigMode === 'default') {
         outputConfig = {
@@ -144,7 +146,7 @@ describe('AgentExecutor', () => {
         mockConfig = makeFakeConfig();
         parentToolRegistry = new ToolRegistry(mockConfig);
         parentToolRegistry.registerTool(new LSTool(mockConfig));
-        parentToolRegistry.registerTool(new ReadFileTool(mockConfig));
+        parentToolRegistry.registerTool(new MockTool({ name: READ_FILE_TOOL_NAME }));
         parentToolRegistry.registerTool(MOCK_TOOL_NOT_ALLOWED);
         vi.spyOn(mockConfig, 'getToolRegistry').mockResolvedValue(parentToolRegistry);
         mockedGetDirectoryContextString.mockResolvedValue('Mocked Environment Context');
@@ -158,7 +160,7 @@ describe('AgentExecutor', () => {
     });
     describe('create (Initialization and Validation)', () => {
         it('should create successfully with allowed tools', async () => {
-            const definition = createTestDefinition([LSTool.Name]);
+            const definition = createTestDefinition([LS_TOOL_NAME]);
             const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
             expect(executor).toBeInstanceOf(AgentExecutor);
         });
@@ -167,11 +169,14 @@ describe('AgentExecutor', () => {
             await expect(AgentExecutor.create(definition, mockConfig, onActivity)).rejects.toThrow(/not on the allow-list for non-interactive execution/);
         });
         it('should create an isolated ToolRegistry for the agent', async () => {
-            const definition = createTestDefinition([LSTool.Name, ReadFileTool.Name]);
+            const definition = createTestDefinition([
+                LS_TOOL_NAME,
+                READ_FILE_TOOL_NAME,
+            ]);
             const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
             const agentRegistry = executor['toolRegistry'];
             expect(agentRegistry).not.toBe(parentToolRegistry);
-            expect(agentRegistry.getAllToolNames()).toEqual(expect.arrayContaining([LSTool.Name, ReadFileTool.Name]));
+            expect(agentRegistry.getAllToolNames()).toEqual(expect.arrayContaining([LS_TOOL_NAME, READ_FILE_TOOL_NAME]));
             expect(agentRegistry.getAllToolNames()).toHaveLength(2);
             expect(agentRegistry.getTool(MOCK_TOOL_NOT_ALLOWED.name)).toBeUndefined();
         });
@@ -204,12 +209,12 @@ describe('AgentExecutor', () => {
             const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
             const inputs = { goal: 'Find files' };
             // Turn 1: Model calls ls
-            mockModelResponse([{ name: LSTool.Name, args: { path: '.' }, id: 'call1' }], 'T1: Listing');
+            mockModelResponse([{ name: LS_TOOL_NAME, args: { path: '.' }, id: 'call1' }], 'T1: Listing');
             mockExecuteToolCall.mockResolvedValueOnce({
                 status: 'success',
                 request: {
                     callId: 'call1',
-                    name: LSTool.Name,
+                    name: LS_TOOL_NAME,
                     args: { path: '.' },
                     isClientInitiated: false,
                     prompt_id: 'test-prompt',
@@ -222,7 +227,7 @@ describe('AgentExecutor', () => {
                     responseParts: [
                         {
                             functionResponse: {
-                                name: LSTool.Name,
+                                name: LS_TOOL_NAME,
                                 response: { result: 'file1.txt' },
                                 id: 'call1',
                             },
@@ -255,7 +260,7 @@ describe('AgentExecutor', () => {
             const sentTools = firstToolGroup.functionDeclarations;
             expect(sentTools).toBeDefined();
             expect(sentTools).toEqual(expect.arrayContaining([
-                expect.objectContaining({ name: LSTool.Name }),
+                expect.objectContaining({ name: LS_TOOL_NAME }),
                 expect.objectContaining({ name: TASK_COMPLETE_TOOL_NAME }),
             ]));
             const completeToolDef = sentTools.find((t) => t.name === TASK_COMPLETE_TOOL_NAME);
@@ -281,7 +286,7 @@ describe('AgentExecutor', () => {
                 }),
                 expect.objectContaining({
                     type: 'TOOL_CALL_END',
-                    data: { name: LSTool.Name, output: 'file1.txt' },
+                    data: { name: LS_TOOL_NAME, output: 'file1.txt' },
                 }),
                 expect.objectContaining({
                     type: 'TOOL_CALL_START',
@@ -300,16 +305,16 @@ describe('AgentExecutor', () => {
             ]));
         });
         it('should execute successfully when model calls complete_task without output (Happy Path No Output)', async () => {
-            const definition = createTestDefinition([LSTool.Name], {}, 'none');
+            const definition = createTestDefinition([LS_TOOL_NAME], {}, 'none');
             const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
             mockModelResponse([
-                { name: LSTool.Name, args: { path: '.' }, id: 'call1' },
+                { name: LS_TOOL_NAME, args: { path: '.' }, id: 'call1' },
             ]);
             mockExecuteToolCall.mockResolvedValueOnce({
                 status: 'success',
                 request: {
                     callId: 'call1',
-                    name: LSTool.Name,
+                    name: LS_TOOL_NAME,
                     args: { path: '.' },
                     isClientInitiated: false,
                     prompt_id: 'test-prompt',
@@ -322,7 +327,7 @@ describe('AgentExecutor', () => {
                     responseParts: [
                         {
                             functionResponse: {
-                                name: LSTool.Name,
+                                name: LS_TOOL_NAME,
                                 response: {},
                                 id: 'call1',
                             },
@@ -353,13 +358,13 @@ describe('AgentExecutor', () => {
             const definition = createTestDefinition();
             const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
             mockModelResponse([
-                { name: LSTool.Name, args: { path: '.' }, id: 'call1' },
+                { name: LS_TOOL_NAME, args: { path: '.' }, id: 'call1' },
             ]);
             mockExecuteToolCall.mockResolvedValueOnce({
                 status: 'success',
                 request: {
                     callId: 'call1',
-                    name: LSTool.Name,
+                    name: LS_TOOL_NAME,
                     args: { path: '.' },
                     isClientInitiated: false,
                     prompt_id: 'test-prompt',
@@ -372,7 +377,7 @@ describe('AgentExecutor', () => {
                     responseParts: [
                         {
                             functionResponse: {
-                                name: LSTool.Name,
+                                name: LS_TOOL_NAME,
                                 response: {},
                                 id: 'call1',
                             },
@@ -383,15 +388,18 @@ describe('AgentExecutor', () => {
                     contentLength: undefined,
                 },
             });
+            // Turn 2 (protocol violation)
             mockModelResponse([], 'I think I am done.');
+            // Turn 3 (recovery turn - also fails)
+            mockModelResponse([], 'I still give up.');
             const output = await executor.run({ goal: 'Strict test' }, signal);
-            expect(mockSendMessageStream).toHaveBeenCalledTimes(2);
-            const expectedError = `Agent stopped calling tools but did not call '${TASK_COMPLETE_TOOL_NAME}' to finalize the session.`;
-            expect(output.terminate_reason).toBe(AgentTerminateMode.ERROR);
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(3);
+            const expectedError = `Agent stopped calling tools but did not call '${TASK_COMPLETE_TOOL_NAME}'.`;
+            expect(output.terminate_reason).toBe(AgentTerminateMode.ERROR_NO_COMPLETE_TASK_CALL);
             expect(output.result).toBe(expectedError);
             // Telemetry check for error
             expect(mockedLogAgentFinish).toHaveBeenCalledWith(mockConfig, expect.objectContaining({
-                terminate_reason: AgentTerminateMode.ERROR,
+                terminate_reason: AgentTerminateMode.ERROR_NO_COMPLETE_TASK_CALL,
             }));
             expect(activities).toContainEqual(expect.objectContaining({
                 type: 'ERROR',
@@ -464,15 +472,15 @@ describe('AgentExecutor', () => {
             expect(errors[0].data['error']).toContain('Task already marked complete in this turn');
         });
         it('should execute parallel tool calls and then complete', async () => {
-            const definition = createTestDefinition([LSTool.Name]);
+            const definition = createTestDefinition([LS_TOOL_NAME]);
             const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
             const call1 = {
-                name: LSTool.Name,
+                name: LS_TOOL_NAME,
                 args: { path: '/a' },
                 id: 'c1',
             };
             const call2 = {
-                name: LSTool.Name,
+                name: LS_TOOL_NAME,
                 args: { path: '/b' },
                 id: 'c2',
             };
@@ -543,13 +551,13 @@ describe('AgentExecutor', () => {
             ]));
         });
         it('SECURITY: should block unauthorized tools and provide explicit failure to model', async () => {
-            const definition = createTestDefinition([LSTool.Name]);
+            const definition = createTestDefinition([LS_TOOL_NAME]);
             const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
             // Turn 1: Model tries to use a tool not in its config
             const badCallId = 'bad_call_1';
             mockModelResponse([
                 {
-                    name: ReadFileTool.Name,
+                    name: READ_FILE_TOOL_NAME,
                     args: { path: 'secret.txt' },
                     id: badCallId,
                 },
@@ -578,7 +586,7 @@ describe('AgentExecutor', () => {
             expect(parts[0]).toEqual(expect.objectContaining({
                 functionResponse: expect.objectContaining({
                     id: badCallId,
-                    name: ReadFileTool.Name,
+                    name: READ_FILE_TOOL_NAME,
                     response: {
                         error: expect.stringContaining('Unauthorized tool call'),
                     },
@@ -589,19 +597,19 @@ describe('AgentExecutor', () => {
                 type: 'ERROR',
                 data: expect.objectContaining({
                     context: 'tool_call_unauthorized',
-                    name: ReadFileTool.Name,
+                    name: READ_FILE_TOOL_NAME,
                 }),
             }));
         });
     });
     describe('run (Termination Conditions)', () => {
         const mockWorkResponse = (id) => {
-            mockModelResponse([{ name: LSTool.Name, args: { path: '.' }, id }]);
+            mockModelResponse([{ name: LS_TOOL_NAME, args: { path: '.' }, id }]);
             mockExecuteToolCall.mockResolvedValueOnce({
                 status: 'success',
                 request: {
                     callId: id,
-                    name: LSTool.Name,
+                    name: LS_TOOL_NAME,
                     args: { path: '.' },
                     isClientInitiated: false,
                     prompt_id: 'test-prompt',
@@ -612,7 +620,7 @@ describe('AgentExecutor', () => {
                     callId: id,
                     resultDisplay: 'ok',
                     responseParts: [
-                        { functionResponse: { name: LSTool.Name, response: {}, id } },
+                        { functionResponse: { name: LS_TOOL_NAME, response: {}, id } },
                     ],
                     error: undefined,
                     errorType: undefined,
@@ -622,22 +630,66 @@ describe('AgentExecutor', () => {
         };
         it('should terminate when max_turns is reached', async () => {
             const MAX = 2;
-            const definition = createTestDefinition([LSTool.Name], {
+            const definition = createTestDefinition([LS_TOOL_NAME], {
                 max_turns: MAX,
             });
             const executor = await AgentExecutor.create(definition, mockConfig);
             mockWorkResponse('t1');
             mockWorkResponse('t2');
+            // Recovery turn
+            mockModelResponse([], 'I give up');
             const output = await executor.run({ goal: 'Turns test' }, signal);
             expect(output.terminate_reason).toBe(AgentTerminateMode.MAX_TURNS);
-            expect(mockSendMessageStream).toHaveBeenCalledTimes(MAX);
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(MAX + 1);
+        });
+        it('should terminate with TIMEOUT if a model call takes too long', async () => {
+            const definition = createTestDefinition([LS_TOOL_NAME], {
+                max_time_minutes: 0.5, // 30 seconds
+            });
+            const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
+            // Mock a model call that is interruptible by an abort signal.
+            mockSendMessageStream.mockImplementationOnce(async (_model, params) => {
+                const signal = params?.config?.abortSignal;
+                // eslint-disable-next-line require-yield
+                return (async function* () {
+                    await new Promise((resolve) => {
+                        // This promise resolves when aborted, ending the generator.
+                        signal?.addEventListener('abort', () => {
+                            resolve();
+                        });
+                    });
+                })();
+            });
+            // Recovery turn
+            mockModelResponse([], 'I give up');
+            const runPromise = executor.run({ goal: 'Timeout test' }, signal);
+            // Advance time past the timeout to trigger the abort.
+            await vi.advanceTimersByTimeAsync(31 * 1000);
+            const output = await runPromise;
+            expect(output.terminate_reason).toBe(AgentTerminateMode.TIMEOUT);
+            expect(output.result).toContain('Agent timed out after 0.5 minutes.');
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(2);
+            // Verify activity stream reported the timeout
+            expect(activities).toContainEqual(expect.objectContaining({
+                type: 'ERROR',
+                data: expect.objectContaining({
+                    context: 'timeout',
+                    error: 'Agent timed out after 0.5 minutes.',
+                }),
+            }));
+            // Verify telemetry
+            expect(mockedLogAgentFinish).toHaveBeenCalledWith(mockConfig, expect.objectContaining({
+                terminate_reason: AgentTerminateMode.TIMEOUT,
+            }));
         });
-        it('should terminate if timeout is reached', async () => {
-            const definition = createTestDefinition([LSTool.Name], {
+        it('should terminate with TIMEOUT if a tool call takes too long', async () => {
+            const definition = createTestDefinition([LS_TOOL_NAME], {
                 max_time_minutes: 1,
             });
             const executor = await AgentExecutor.create(definition, mockConfig);
-            mockModelResponse([{ name: LSTool.Name, args: { path: '.' }, id: 't1' }]);
+            mockModelResponse([
+                { name: LS_TOOL_NAME, args: { path: '.' }, id: 't1' },
+            ]);
             // Long running tool
             mockExecuteToolCall.mockImplementationOnce(async (_ctx, reqInfo) => {
                 await vi.advanceTimersByTimeAsync(61 * 1000);
@@ -656,9 +708,11 @@ describe('AgentExecutor', () => {
                     },
                 };
             });
+            // Recovery turn
+            mockModelResponse([], 'I give up');
             const output = await executor.run({ goal: 'Timeout test' }, signal);
             expect(output.terminate_reason).toBe(AgentTerminateMode.TIMEOUT);
-            expect(mockSendMessageStream).toHaveBeenCalledTimes(1);
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(2);
         });
         it('should terminate when AbortSignal is triggered', async () => {
             const definition = createTestDefinition();
@@ -676,5 +730,282 @@ describe('AgentExecutor', () => {
             expect(output.terminate_reason).toBe(AgentTerminateMode.ABORTED);
         });
     });
+    describe('run (Recovery Turns)', () => {
+        const mockWorkResponse = (id) => {
+            mockModelResponse([{ name: LS_TOOL_NAME, args: { path: '.' }, id }]);
+            mockExecuteToolCall.mockResolvedValueOnce({
+                status: 'success',
+                request: {
+                    callId: id,
+                    name: LS_TOOL_NAME,
+                    args: { path: '.' },
+                    isClientInitiated: false,
+                    prompt_id: 'test-prompt',
+                },
+                tool: {},
+                invocation: {},
+                response: {
+                    callId: id,
+                    resultDisplay: 'ok',
+                    responseParts: [
+                        { functionResponse: { name: LS_TOOL_NAME, response: {}, id } },
+                    ],
+                    error: undefined,
+                    errorType: undefined,
+                    contentLength: undefined,
+                },
+            });
+        };
+        it('should recover successfully if complete_task is called during the grace turn after MAX_TURNS', async () => {
+            const MAX = 1;
+            const definition = createTestDefinition([LS_TOOL_NAME], {
+                max_turns: MAX,
+            });
+            const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
+            // Turn 1 (hits max_turns)
+            mockWorkResponse('t1');
+            // Recovery Turn (succeeds)
+            mockModelResponse([
+                {
+                    name: TASK_COMPLETE_TOOL_NAME,
+                    args: { finalResult: 'Recovered!' },
+                    id: 't2',
+                },
+            ], 'Recovering from max turns');
+            const output = await executor.run({ goal: 'Turns recovery' }, signal);
+            expect(output.terminate_reason).toBe(AgentTerminateMode.GOAL);
+            expect(output.result).toBe('Recovered!');
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(MAX + 1); // 1 regular + 1 recovery
+            expect(activities).toContainEqual(expect.objectContaining({
+                type: 'THOUGHT_CHUNK',
+                data: {
+                    text: 'Execution limit reached (MAX_TURNS). Attempting one final recovery turn with a grace period.',
+                },
+            }));
+            expect(activities).toContainEqual(expect.objectContaining({
+                type: 'THOUGHT_CHUNK',
+                data: { text: 'Graceful recovery succeeded.' },
+            }));
+        });
+        it('should fail if complete_task is NOT called during the grace turn after MAX_TURNS', async () => {
+            const MAX = 1;
+            const definition = createTestDefinition([LS_TOOL_NAME], {
+                max_turns: MAX,
+            });
+            const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
+            // Turn 1 (hits max_turns)
+            mockWorkResponse('t1');
+            // Recovery Turn (fails by calling no tools)
+            mockModelResponse([], 'I give up again.');
+            const output = await executor.run({ goal: 'Turns recovery fail' }, signal);
+            expect(output.terminate_reason).toBe(AgentTerminateMode.MAX_TURNS);
+            expect(output.result).toContain('Agent reached max turns limit');
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(MAX + 1);
+            expect(activities).toContainEqual(expect.objectContaining({
+                type: 'ERROR',
+                data: expect.objectContaining({
+                    context: 'recovery_turn',
+                    error: 'Graceful recovery attempt failed. Reason: stop',
+                }),
+            }));
+        });
+        it('should recover successfully from a protocol violation (no complete_task)', async () => {
+            const definition = createTestDefinition();
+            const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
+            // Turn 1: Normal work
+            mockWorkResponse('t1');
+            // Turn 2: Protocol violation (no tool calls)
+            mockModelResponse([], 'I think I am done, but I forgot the right tool.');
+            // Turn 3: Recovery turn (succeeds)
+            mockModelResponse([
+                {
+                    name: TASK_COMPLETE_TOOL_NAME,
+                    args: { finalResult: 'Recovered from violation!' },
+                    id: 't3',
+                },
+            ], 'My mistake, here is the completion.');
+            const output = await executor.run({ goal: 'Violation recovery' }, signal);
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(3);
+            expect(output.terminate_reason).toBe(AgentTerminateMode.GOAL);
+            expect(output.result).toBe('Recovered from violation!');
+            expect(activities).toContainEqual(expect.objectContaining({
+                type: 'THOUGHT_CHUNK',
+                data: {
+                    text: 'Execution limit reached (ERROR_NO_COMPLETE_TASK_CALL). Attempting one final recovery turn with a grace period.',
+                },
+            }));
+        });
+        it('should fail recovery from a protocol violation if it violates again', async () => {
+            const definition = createTestDefinition();
+            const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
+            // Turn 1: Normal work
+            mockWorkResponse('t1');
+            // Turn 2: Protocol violation (no tool calls)
+            mockModelResponse([], 'I think I am done, but I forgot the right tool.');
+            // Turn 3: Recovery turn (fails again)
+            mockModelResponse([], 'I still dont know what to do.');
+            const output = await executor.run({ goal: 'Violation recovery fail' }, signal);
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(3);
+            expect(output.terminate_reason).toBe(AgentTerminateMode.ERROR_NO_COMPLETE_TASK_CALL);
+            expect(output.result).toContain(`Agent stopped calling tools but did not call '${TASK_COMPLETE_TOOL_NAME}'`);
+            expect(activities).toContainEqual(expect.objectContaining({
+                type: 'ERROR',
+                data: expect.objectContaining({
+                    context: 'recovery_turn',
+                    error: 'Graceful recovery attempt failed. Reason: stop',
+                }),
+            }));
+        });
+        it('should recover successfully from a TIMEOUT', async () => {
+            const definition = createTestDefinition([LS_TOOL_NAME], {
+                max_time_minutes: 0.5, // 30 seconds
+            });
+            const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
+            // Mock a model call that gets interrupted by the timeout.
+            mockSendMessageStream.mockImplementationOnce(async (_model, params) => {
+                const signal = params?.config?.abortSignal;
+                // eslint-disable-next-line require-yield
+                return (async function* () {
+                    // This promise never resolves, it waits for abort.
+                    await new Promise((resolve) => {
+                        signal?.addEventListener('abort', () => resolve());
+                    });
+                })();
+            });
+            // Recovery turn (succeeds)
+            mockModelResponse([
+                {
+                    name: TASK_COMPLETE_TOOL_NAME,
+                    args: { finalResult: 'Recovered from timeout!' },
+                    id: 't2',
+                },
+            ], 'Apologies for the delay, finishing up.');
+            const runPromise = executor.run({ goal: 'Timeout recovery' }, signal);
+            // Advance time past the timeout to trigger the abort and recovery.
+            await vi.advanceTimersByTimeAsync(31 * 1000);
+            const output = await runPromise;
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(2); // 1 failed + 1 recovery
+            expect(output.terminate_reason).toBe(AgentTerminateMode.GOAL);
+            expect(output.result).toBe('Recovered from timeout!');
+            expect(activities).toContainEqual(expect.objectContaining({
+                type: 'THOUGHT_CHUNK',
+                data: {
+                    text: 'Execution limit reached (TIMEOUT). Attempting one final recovery turn with a grace period.',
+                },
+            }));
+        });
+        it('should fail recovery from a TIMEOUT if the grace period also times out', async () => {
+            const definition = createTestDefinition([LS_TOOL_NAME], {
+                max_time_minutes: 0.5, // 30 seconds
+            });
+            const executor = await AgentExecutor.create(definition, mockConfig, onActivity);
+            mockSendMessageStream.mockImplementationOnce(async (_model, params) => {
+                const signal = params?.config?.abortSignal;
+                // eslint-disable-next-line require-yield
+                return (async function* () {
+                    await new Promise((resolve) => signal?.addEventListener('abort', () => resolve()));
+                })();
+            });
+            // Mock the recovery call to also be long-running
+            mockSendMessageStream.mockImplementationOnce(async (_model, params) => {
+                const signal = params?.config?.abortSignal;
+                // eslint-disable-next-line require-yield
+                return (async function* () {
+                    await new Promise((resolve) => signal?.addEventListener('abort', () => resolve()));
+                })();
+            });
+            const runPromise = executor.run({ goal: 'Timeout recovery fail' }, signal);
+            // 1. Trigger the main timeout
+            await vi.advanceTimersByTimeAsync(31 * 1000);
+            // 2. Let microtasks run (start recovery turn)
+            await vi.advanceTimersByTimeAsync(1);
+            // 3. Trigger the grace period timeout (60s)
+            await vi.advanceTimersByTimeAsync(61 * 1000);
+            const output = await runPromise;
+            expect(mockSendMessageStream).toHaveBeenCalledTimes(2);
+            expect(output.terminate_reason).toBe(AgentTerminateMode.TIMEOUT);
+            expect(output.result).toContain('Agent timed out after 0.5 minutes.');
+            expect(activities).toContainEqual(expect.objectContaining({
+                type: 'ERROR',
+                data: expect.objectContaining({
+                    context: 'recovery_turn',
+                    error: 'Graceful recovery attempt failed. Reason: stop',
+                }),
+            }));
+        });
+    });
+    describe('Telemetry and Logging', () => {
+        const mockWorkResponse = (id) => {
+            mockModelResponse([{ name: LS_TOOL_NAME, args: { path: '.' }, id }]);
+            mockExecuteToolCall.mockResolvedValueOnce({
+                status: 'success',
+                request: {
+                    callId: id,
+                    name: LS_TOOL_NAME,
+                    args: { path: '.' },
+                    isClientInitiated: false,
+                    prompt_id: 'test-prompt',
+                },
+                tool: {},
+                invocation: {},
+                response: {
+                    callId: id,
+                    resultDisplay: 'ok',
+                    responseParts: [
+                        { functionResponse: { name: LS_TOOL_NAME, response: {}, id } },
+                    ],
+                    error: undefined,
+                    errorType: undefined,
+                    contentLength: undefined,
+                },
+            });
+        };
+        beforeEach(() => {
+            mockedLogRecoveryAttempt.mockClear();
+        });
+        it('should log a RecoveryAttemptEvent when a recoverable error occurs and recovery fails', async () => {
+            const MAX = 1;
+            const definition = createTestDefinition([LS_TOOL_NAME], {
+                max_turns: MAX,
+            });
+            const executor = await AgentExecutor.create(definition, mockConfig);
+            // Turn 1 (hits max_turns)
+            mockWorkResponse('t1');
+            // Recovery Turn (fails by calling no tools)
+            mockModelResponse([], 'I give up again.');
+            await executor.run({ goal: 'Turns recovery fail' }, signal);
+            expect(mockedLogRecoveryAttempt).toHaveBeenCalledTimes(1);
+            const recoveryEvent = mockedLogRecoveryAttempt.mock.calls[0][1];
+            expect(recoveryEvent).toBeInstanceOf(RecoveryAttemptEvent);
+            expect(recoveryEvent.agent_name).toBe(definition.name);
+            expect(recoveryEvent.reason).toBe(AgentTerminateMode.MAX_TURNS);
+            expect(recoveryEvent.success).toBe(false);
+            expect(recoveryEvent.turn_count).toBe(1);
+            expect(recoveryEvent.duration_ms).toBeGreaterThanOrEqual(0);
+        });
+        it('should log a successful RecoveryAttemptEvent when recovery succeeds', async () => {
+            const MAX = 1;
+            const definition = createTestDefinition([LS_TOOL_NAME], {
+                max_turns: MAX,
+            });
+            const executor = await AgentExecutor.create(definition, mockConfig);
+            // Turn 1 (hits max_turns)
+            mockWorkResponse('t1');
+            // Recovery Turn (succeeds)
+            mockModelResponse([
+                {
+                    name: TASK_COMPLETE_TOOL_NAME,
+                    args: { finalResult: 'Recovered!' },
+                    id: 't2',
+                },
+            ], 'Recovering from max turns');
+            await executor.run({ goal: 'Turns recovery success' }, signal);
+            expect(mockedLogRecoveryAttempt).toHaveBeenCalledTimes(1);
+            const recoveryEvent = mockedLogRecoveryAttempt.mock.calls[0][1];
+            expect(recoveryEvent).toBeInstanceOf(RecoveryAttemptEvent);
+            expect(recoveryEvent.success).toBe(true);
+            expect(recoveryEvent.reason).toBe(AgentTerminateMode.MAX_TURNS);
+        });
+    });
 });
 //# sourceMappingURL=executor.test.js.map