@qduc/term2 0.7.2 → 0.8.0

package/dist/lib/openai-agent-client.public-methods.test.js

@@ -1,6 +1,10 @@
-import test from 'ava';
-import { OpenAIAgentClient } from './openai-agent-client.js';
+import { it, expect, beforeEach } from 'vitest';
+import { AgentClient } from './agent-client.js';
 import { registerProvider } from '../providers/registry.js';
+const createSessionContextService = () => ({
+    runWithContext: (_context, fn) => fn(),
+    getContext: () => null,
+});
 // ========== Mock Utilities ==========
 function createMockLogger() {
     return {
@@ -63,6 +67,8 @@ let chainingProviderRegistered = false;
 let chainingRunnerCalls = [];
 let codexProviderRegistered = false;
 let codexRunnerCalls = [];
+let openaiProviderRegistered = false;
+let openaiRunnerCalls = [];
 let failingProviderRegistered = false;
 function ensureMentorProvidersRegistered() {
     if (!mentorProviderRegistered) {
@@ -127,7 +133,7 @@ function ensureChainingProvidersRegistered() {
             label: 'Mock Chaining False',
             createRunner: () => ({
                 run: async (_agent, _input, options) => {
-                    chainingRunnerCalls.push({ options, providerId: 'mock-chaining-false' });
+                    chainingRunnerCalls.push({ input: _input, options, providerId: 'mock-chaining-false' });
                     return {
                         status: 'completed',
                         finalOutput: 'ok',
@@ -146,7 +152,7 @@ function ensureChainingProvidersRegistered() {
             label: 'Mock Chaining True',
             createRunner: () => ({
                 run: async (_agent, _input, options) => {
-                    chainingRunnerCalls.push({ options, providerId: 'mock-chaining-true' });
+                    chainingRunnerCalls.push({ input: _input, options, providerId: 'mock-chaining-true' });
                     return {
                         status: 'completed',
                         finalOutput: 'ok',
@@ -182,11 +188,37 @@ function ensureCodexProviderRegistered() {
             capabilities: {
                 supportsConversationChaining: true,
                 supportsTracingControl: true,
+                supportsPromptCacheKey: true,
             },
         }, { allowOverride: true });
         codexProviderRegistered = true;
     }
 }
+function ensureOpenAIProviderRegistered() {
+    if (!openaiProviderRegistered) {
+        registerProvider({
+            id: 'openai',
+            label: 'Mock OpenAI',
+            createRunner: () => ({
+                run: async (agent, _input, options) => {
+                    openaiRunnerCalls.push({ agent, options });
+                    return {
+                        status: 'completed',
+                        finalOutput: 'ok',
+                        messages: [],
+                    };
+                },
+            }),
+            fetchModels: async () => [{ id: 'mock-model' }],
+            capabilities: {
+                supportsConversationChaining: true,
+                supportsTracingControl: true,
+                supportsPromptCacheKey: true,
+            },
+        }, { allowOverride: true });
+        openaiProviderRegistered = true;
+    }
+}
 function ensureFailingProviderRegistered() {
     if (!failingProviderRegistered) {
         registerProvider({
@@ -204,12 +236,13 @@ function ensureFailingProviderRegistered() {
         failingProviderRegistered = true;
     }
 }
-test.beforeEach(() => {
+beforeEach(() => {
     runnerCalls = [];
     ensureProviderRegistered();
     ensureMentorProvidersRegistered();
     ensureChainingProvidersRegistered();
     ensureCodexProviderRegistered();
+    ensureOpenAIProviderRegistered();
     ensureFailingProviderRegistered();
     capturedMainAgentForMentorTest = null;
     mentorInputs = [];
@@ -217,78 +250,482 @@ test.beforeEach(() => {
     mentorResponseCounter = 0;
     chainingRunnerCalls = [];
     codexRunnerCalls = [];
+    openaiRunnerCalls = [];
 });
 // ========== setModel tests ==========
-test.serial('setModel updates the internal model', async (t) => {
+it.sequential('setModel updates the internal model', async () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     // Set a new model
     client.setModel('gpt-4-turbo');
     // Trigger a chat to see what model is used
     await client.chat('test');
-    t.is(runnerCalls.length, 1);
+    expect(runnerCalls.length).toBe(1);
     // The agent should have the updated model
     const agent = runnerCalls[0].agent;
-    t.truthy(agent);
+    expect(agent).toBeTruthy();
 });
 // ========== setProvider / getProvider tests ==========
-test.serial('getProvider returns current provider', (t) => {
+it.sequential('getProvider returns current provider', () => {
     const settings = createMockSettings({ 'agent.provider': 'mock-provider-public-methods' });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
-    t.is(client.getProvider(), 'mock-provider-public-methods');
+    expect(client.getProvider()).toBe('mock-provider-public-methods');
 });
-test.serial('setProvider updates provider and persists to settings', (t) => {
+it.sequential('setProvider updates provider and persists to settings', () => {
     const settings = createMockSettings({ 'agent.provider': 'mock-provider-public-methods' });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     client.setProvider('openai');
-    t.is(client.getProvider(), 'openai');
-    t.is(settings.get('agent.provider'), 'openai');
+    expect(client.getProvider()).toBe('openai');
+    expect(settings.get('agent.provider')).toBe('openai');
 });
-test.serial('setProvider does not initialize provider credentials eagerly', async (t) => {
+it.sequential('setProvider does not initialize provider credentials eagerly', async () => {
     const settings = createMockSettings({ 'agent.provider': 'mock-provider-public-methods' });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     client.setProvider('mock-missing-creds');
-    t.is(client.getProvider(), 'mock-missing-creds');
-    t.is(settings.get('agent.provider'), 'mock-missing-creds');
-    const error = await t.throwsAsync(async () => client.chat('test'));
-    t.is(error?.message, 'Missing credentials');
+    expect(client.getProvider()).toBe('mock-missing-creds');
+    expect(settings.get('agent.provider')).toBe('mock-missing-creds');
+    await expect(async () => client.chat('test')).rejects.toThrow('Missing credentials');
 });
-test.serial('startStream only passes previousResponseId when provider supports chaining', async (t) => {
+it.sequential('startStream only passes previousResponseId when provider supports chaining', async () => {
     const settings = createMockSettings({
         'agent.provider': 'mock-chaining-false',
     });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     await client.startStream('Hello', { previousResponseId: 'prev-1' });
-    t.is(chainingRunnerCalls.length, 1);
-    t.false('previousResponseId' in chainingRunnerCalls[0].options);
+    expect(chainingRunnerCalls.length).toBe(1);
+    expect('previousResponseId' in chainingRunnerCalls[0].options).toBe(false);
     client.setProvider('mock-chaining-true');
     await client.startStream('Hello', { previousResponseId: 'prev-2' });
-    t.is(chainingRunnerCalls.length, 2);
-    t.is(chainingRunnerCalls[1].options.previousResponseId, 'prev-2');
+    expect(chainingRunnerCalls.length).toBe(2);
+    expect(chainingRunnerCalls[1].options.previousResponseId).toBe('prev-2');
+});
+it.sequential('continueRunStream filters replayed history to delta input when chaining from previousResponseId', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    const state = {
+        _context: { context: { turnCount: 0 } },
+        _generatedItems: [
+            { rawItem: { type: 'function_call', callId: 'call-read', name: 'read_file', arguments: '{}' } },
+            { rawItem: { type: 'function_call_output', callId: 'call-read', output: 'done' } },
+        ],
+    };
+    await client.continueRunStream(state, { previousResponseId: 'resp-prev' });
+    expect(chainingRunnerCalls.length).toBe(1);
+    const call = chainingRunnerCalls[0];
+    expect(call.input).toBe(state);
+    expect(call.options.previousResponseId).toBe('resp-prev');
+    const filtered = call.options.callModelInputFilter({
+        context: { turnCount: 0 },
+        modelData: {
+            input: [
+                { role: 'user', type: 'message', content: 'inspect file' },
+                { role: 'assistant', type: 'message', content: [{ type: 'output_text', text: 'I will inspect it.' }] },
+                { type: 'function_call', callId: 'call-read', name: 'read_file', arguments: '{}' },
+                { type: 'function_call_output', callId: 'call-read', output: 'done' },
+            ],
+            instructions: 'system',
+        },
+    });
+    expect(filtered.input).toEqual([{ type: 'function_call_output', callId: 'call-read', output: 'done' }]);
+    expect(filtered.instructions).toBe('system');
+});
+it.sequential('continueRunStream filters replayed history to delta input with function_call_output_result and tool_call_output_item', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    await client.continueRunStream({ _context: { context: { turnCount: 0 } } }, {
+        previousResponseId: 'resp-prev',
+    });
+    const filtered = chainingRunnerCalls[0].options.callModelInputFilter({
+        context: { turnCount: 0 },
+        modelData: {
+            input: [
+                { role: 'user', type: 'message', content: 'inspect file' },
+                { role: 'assistant', type: 'message', content: [{ type: 'output_text', text: 'I will inspect it.' }] },
+                { type: 'function_call', callId: 'call-read', name: 'read_file', arguments: '{}' },
+                { type: 'function_call_output_result', callId: 'call-read', output: 'done' },
+                { type: 'tool_call_output_item', callId: 'call-read', output: 'done' },
+            ],
+            instructions: 'system',
+        },
+    });
+    expect(filtered.input).toEqual([
+        { type: 'function_call_output_result', callId: 'call-read', output: 'done' },
+        { type: 'tool_call_output_item', callId: 'call-read', output: 'done' },
+    ]);
+});
+it.sequential('continueRunStream keeps the latest user item when chained model input replays full history', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    await client.continueRunStream({ _context: { context: { turnCount: 0 } } }, {
+        previousResponseId: 'resp-prev',
+    });
+    const filtered = chainingRunnerCalls[0].options.callModelInputFilter({
+        context: { turnCount: 0 },
+        modelData: {
+            input: [
+                { role: 'user', type: 'message', content: 'first' },
+                { role: 'assistant', type: 'message', content: [{ type: 'output_text', text: 'first response' }] },
+                { role: 'user', type: 'message', content: 'second' },
+            ],
+            instructions: 'system',
+        },
+    });
+    expect(filtered.input).toEqual([{ role: 'user', type: 'message', content: 'second' }]);
+});
+it.sequential('startStream filters replayed history to delta input when chaining from previousResponseId', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    await client.startStream('inspect file', { previousResponseId: 'resp-prev' });
+    expect(chainingRunnerCalls.length).toBe(1);
+    const call = chainingRunnerCalls[0];
+    expect(call.options.previousResponseId).toBe('resp-prev');
+    const filtered = call.options.callModelInputFilter({
+        context: { turnCount: 0 },
+        modelData: {
+            input: [
+                { role: 'user', type: 'message', content: 'inspect file' },
+                { role: 'assistant', type: 'message', content: [{ type: 'output_text', text: 'I will inspect it.' }] },
+                { type: 'function_call', callId: 'call-read', name: 'read_file', arguments: '{}' },
+                { type: 'function_call_output', callId: 'call-read', output: 'done' },
+            ],
+            instructions: 'system',
+        },
+    });
+    expect(filtered.input).toEqual([{ type: 'function_call_output', callId: 'call-read', output: 'done' }]);
+    expect(filtered.instructions).toBe('system');
+});
+it.sequential('continueRunStream keeps only expected approved tool outputs when chaining', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    await client.continueRunStream({ _context: { context: { turnCount: 0 } } }, {
+        previousResponseId: 'resp-prev',
+        toolResultCallIds: ['call-current'],
+    });
+    const filtered = chainingRunnerCalls[0].options.callModelInputFilter({
+        context: { turnCount: 0 },
+        modelData: {
+            input: [
+                { type: 'function_call_output', callId: 'call-old-1', output: 'old one' },
+                { type: 'function_call_output', call_id: 'call-old-2', output: 'old two' },
+                { type: 'function_call_output', callId: 'call-current', output: 'current' },
+            ],
+            instructions: 'system',
+        },
+    });
+    expect(filtered.input).toEqual([{ type: 'function_call_output', callId: 'call-current', output: 'current' }]);
+});
+it.sequential('continueRunStream warns when chained delta input item count spikes', async () => {
+    const warnings = [];
+    const logger = {
+        ...createMockLogger(),
+        warn: (message, meta) => warnings.push({ message, meta }),
+    };
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+    });
+    const client = new AgentClient({
+        deps: { logger, settings, sessionContextService: createSessionContextService() },
+    });
+    await client.continueRunStream({ _context: { context: { turnCount: 0 } } }, {
+        previousResponseId: 'resp-prev',
+    });
+    const filter = chainingRunnerCalls[0].options.callModelInputFilter;
+    filter({
+        context: { turnCount: 0 },
+        modelData: {
+            input: [
+                { type: 'function_call_output', callId: 'call-1', output: 'one' },
+                { type: 'function_call_output', callId: 'call-2', output: 'two' },
+                { type: 'function_call_output', callId: 'call-3', output: 'three' },
+            ],
+        },
+    });
+    filter({
+        context: { turnCount: 1 },
+        modelData: {
+            input: Array.from({ length: 23 }, (_, index) => ({
+                type: 'function_call_output',
+                callId: `call-${index}`,
+                output: `output-${index}`,
+            })),
+        },
+    });
+    const warning = warnings.find((entry) => entry.meta?.eventType === 'provider.chained_delta_input_spike');
+    expect(warning).toBeTruthy();
+    expect(warning.meta.previousInputItems).toBe(3);
+    expect(warning.meta.inputItems).toBe(23);
+});
+it.sequential('continueRunStream filters and keeps user message even with custom type', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    await client.continueRunStream({ _context: { context: { turnCount: 0 } } }, {
+        previousResponseId: 'resp-prev',
+    });
+    const filtered = chainingRunnerCalls[0].options.callModelInputFilter({
+        context: { turnCount: 0 },
+        modelData: {
+            input: [
+                { role: 'user', type: 'message', content: 'first' },
+                { role: 'assistant', type: 'message', content: [{ type: 'output_text', text: 'first response' }] },
+                { role: 'user', type: 'custom_input_type', content: 'second' },
+            ],
+            instructions: 'system',
+        },
+    });
+    expect(filtered.input).toEqual([{ role: 'user', type: 'custom_input_type', content: 'second' }]);
+});
+// ========== Characterization tests for stream lifecycle ==========
+it.sequential('startStream with chaining and input filtering', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    await client.startStream('Hello', { previousResponseId: 'prev-1' });
+    expect(chainingRunnerCalls.length).toBe(1);
+    expect(chainingRunnerCalls[0].options.previousResponseId).toBe('prev-1');
+    expect(typeof chainingRunnerCalls[0].options.callModelInputFilter).toBe('function');
+});
+it.sequential('continueRunStream resuming from a RunState with chaining', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    const state = { _context: { context: { turnCount: 0 } }, _generatedItems: [] };
+    await client.continueRunStream(state, { previousResponseId: 'resp-prev' });
+    expect(chainingRunnerCalls.length).toBe(1);
+    expect(chainingRunnerCalls[0].input).toBe(state);
+    expect(chainingRunnerCalls[0].options.previousResponseId).toBe('resp-prev');
+    expect(chainingRunnerCalls[0].options.stream).toBe(true);
+    expect(typeof chainingRunnerCalls[0].options.callModelInputFilter).toBe('function');
+});
+it.sequential('abort during an active startStream', async () => {
+    let capturedSignal;
+    const testProviderId = 'mock-abort-active-stream';
+    registerProvider({
+        id: testProviderId,
+        label: 'Mock Abort Active Stream',
+        createRunner: () => ({
+            run: async (_agent, _input, options) => {
+                capturedSignal = options.signal;
+                // Wait until aborted before resolving
+                await new Promise((resolve) => {
+                    options.signal.addEventListener('abort', () => resolve());
+                });
+                return { status: 'completed', finalOutput: 'done', messages: [] };
+            },
+        }),
+        fetchModels: async () => [{ id: 'mock-model' }],
+    });
+    let correlationId;
+    const logger = {
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+        security: () => { },
+        setCorrelationId: (id) => {
+            correlationId = id;
+        },
+        clearCorrelationId: () => {
+            correlationId = undefined;
+        },
+        getCorrelationId: () => correlationId,
+        log: () => { },
+    };
+    const settings = createMockSettings({
+        'agent.provider': testProviderId,
+        'agent.model': 'mock-model',
+    });
+    const client = new AgentClient({
+        deps: { logger, settings, sessionContextService: createSessionContextService() },
+    });
+    // Start stream - runner will wait until aborted
+    const streamPromise = client.startStream('Hello');
+    // capturedSignal is set synchronously before startStream awaits the runner
+    expect(correlationId).toBeTruthy();
+    expect(capturedSignal).toBeTruthy();
+    expect(capturedSignal.aborted).toBe(false);
+    // Abort
+    client.abort();
+    await streamPromise;
+    expect(capturedSignal.aborted).toBe(true);
+    expect(correlationId).toBeFalsy();
 });
-test.serial('codex startStream puts prompt_cache_key on agent modelSettings, not run options', async (t) => {
+it.sequential('clearConversations resets chained delta state', async () => {
+    const warnings = [];
+    const logger = {
+        ...createMockLogger(),
+        warn: (message, meta) => warnings.push({ message, meta }),
+    };
+    const settings = createMockSettings({
+        'agent.provider': 'mock-chaining-true',
+        'agent.model': 'mock-model',
+    });
+    const client = new AgentClient({
+        deps: { logger, settings, sessionContextService: createSessionContextService() },
+    });
+    // First stream with chaining - establishes #lastChainedDeltaInputItems
+    await client.startStream('Hello', { previousResponseId: 'prev-1' });
+    chainingRunnerCalls[0].options.callModelInputFilter({
+        context: { turnCount: 0 },
+        modelData: { input: [{ type: 'function_call_output', callId: 'call-1', output: 'one' }] },
+    });
+    // Clear conversations - should reset #lastChainedDeltaInputItems to null
+    client.clearConversations();
+    // Start another stream with chaining after clear
+    await client.startStream('World', { previousResponseId: 'prev-2' });
+    chainingRunnerCalls[1].options.callModelInputFilter({
+        context: { turnCount: 0 },
+        modelData: {
+            input: Array.from({ length: 23 }, (_, i) => ({
+                type: 'function_call_output',
+                callId: `call-${i}`,
+                output: `output-${i}`,
+            })),
+        },
+    });
+    // After clearConversations, #lastChainedDeltaInputItems is null,
+    // so a large jump should NOT trigger the spike warning
+    const spikeWarnings = warnings.filter((w) => w.meta?.eventType === 'provider.chained_delta_input_spike');
+    expect(spikeWarnings.length, 'should not warn about spike after clearConversations resets state').toBe(0);
+});
+it.sequential('chat and chatJson with temp provider/reasoning-effort overrides', async () => {
+    const chatRunnerCalls = [];
+    registerProvider({
+        id: 'mock-chat-override-test',
+        label: 'Mock Chat Override Test',
+        createRunner: () => ({
+            run: async (agent, _input, _options) => {
+                chatRunnerCalls.push({ agent, input: _input, options: _options });
+                return { status: 'completed', finalOutput: 'mock chat response', messages: [] };
+            },
+        }),
+        fetchModels: async () => [{ id: 'chat-override-model' }],
+    });
+    const settings = createMockSettings({
+        'agent.provider': 'mock-provider-public-methods',
+        'agent.model': 'default-model',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    // Call chat with provider, model, and reasoningEffort override
+    const chatResult = await client.chat('Hello', {
+        provider: 'mock-chat-override-test',
+        model: 'chat-override-model',
+        reasoningEffort: 'high',
+    });
+    expect(chatResult).toBe('mock chat response');
+    expect(chatRunnerCalls.length, 'chat should use the override provider').toBe(1);
+    expect(chatRunnerCalls[0].agent.name).toBe('Chat');
+    expect(chatRunnerCalls[0].agent.model).toBe('chat-override-model');
+    expect(chatRunnerCalls[0].agent.modelSettings?.reasoning?.effort).toBe('high');
+    expect(chatRunnerCalls[0].input).toBe('Hello');
+    expect(chatRunnerCalls[0].options.stream).toBe(false);
+    // The default provider should not have been used
+    expect(runnerCalls.length, 'default provider runner should not be called for chat with override').toBe(0);
+    // Now call chatJson with different reasoningEffort
+    const chatJsonResult = await client.chatJson('Hello structured', {
+        provider: 'mock-chat-override-test',
+        model: 'chat-override-model',
+        reasoningEffort: 'medium',
+        outputType: {
+            type: 'json_schema',
+            name: 'test_result',
+            strict: true,
+            schema: {
+                type: 'object',
+                properties: { result: { type: 'string' } },
+                required: ['result'],
+                additionalProperties: false,
+            },
+        },
+    });
+    expect(chatJsonResult).toBe('mock chat response');
+    expect(chatRunnerCalls.length, 'chatJson should use the override provider').toBe(2);
+    expect(chatRunnerCalls[1].agent.name).toBe('Chat');
+    expect(chatRunnerCalls[1].agent.model).toBe('chat-override-model');
+    expect(chatRunnerCalls[1].agent.modelSettings?.reasoning?.effort).toBe('medium');
+    expect(chatRunnerCalls[1].input).toBe('Hello structured');
+    expect(chatRunnerCalls[1].options.stream).toBe(false);
+    expect(chatRunnerCalls[1].agent.outputType).toBeTruthy();
+    // Default provider still not called
+    expect(runnerCalls.length, 'default provider runner should still not be called').toBe(0);
+});
+it.sequential('codex startStream puts prompt_cache_key on agent modelSettings, not run options', async () => {
     const settings = createMockSettings({
         'agent.provider': 'codex',
     });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     await client.startStream('Hello', { sessionId: 'session-123' });
-    t.is(codexRunnerCalls.length, 1);
-    t.is(codexRunnerCalls[0].agent.modelSettings.prompt_cache_key, 'session-123');
-    t.false('modelSettings' in codexRunnerCalls[0].options);
+    expect(codexRunnerCalls.length).toBe(1);
+    expect(codexRunnerCalls[0].agent.modelSettings.prompt_cache_key).toBe('session-123');
+    expect('modelSettings' in codexRunnerCalls[0].options).toBe(false);
+});
+it.sequential('openai startStream puts prompt_cache_key on agent modelSettings, not run options', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'openai',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    await client.startStream('Hello', { sessionId: 'session-456' });
+    expect(openaiRunnerCalls.length).toBe(1);
+    expect(openaiRunnerCalls[0].agent.modelSettings.prompt_cache_key).toBe('session-456');
+    expect('modelSettings' in openaiRunnerCalls[0].options).toBe(false);
+});
+it.sequential('startStream omits prompt_cache_key when provider does not support it', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-provider-public-methods',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    await client.startStream('Hello', { sessionId: 'session-789' });
+    expect(runnerCalls.length).toBe(1);
+    expect(runnerCalls[0].agent.modelSettings?.prompt_cache_key).toBeFalsy();
 });
-test.serial('abort logs with active trace id before clearing correlation', async (t) => {
+it.sequential('abort logs with active trace id before clearing correlation', async () => {
     const debugLogs = [];
     let correlationId;
     const logger = {
@@ -311,37 +748,37 @@ test.serial('abort logs with active trace id before clearing correlation', async
     const settings = createMockSettings({
         'agent.provider': 'mock-chaining-false',
     });
-    const client = new OpenAIAgentClient({
-        deps: { logger, settings },
+    const client = new AgentClient({
+        deps: { logger, settings, sessionContextService: createSessionContextService() },
     });
     await client.startStream('Hello');
     const activeCorrelationId = correlationId;
-    t.truthy(activeCorrelationId);
+    expect(activeCorrelationId).toBeTruthy();
     client.abort();
     const abortLogs = debugLogs.filter((entry) => entry.message === 'Agent operation aborted');
-    t.true(abortLogs.length > 0);
+    expect(abortLogs.length > 0).toBe(true);
     const latestAbortLog = abortLogs[abortLogs.length - 1];
-    t.is(latestAbortLog.meta?.traceId, activeCorrelationId);
-    t.is(correlationId, undefined);
+    expect(latestAbortLog.meta?.traceId).toBe(activeCorrelationId);
+    expect(correlationId).toBe(undefined);
 });
 // ========== addToolInterceptor tests ==========
-test.serial('addToolInterceptor returns removal function', (t) => {
+it.sequential('addToolInterceptor returns removal function', () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     const remove = client.addToolInterceptor(async () => {
         return null;
     });
-    t.is(typeof remove, 'function');
+    expect(typeof remove).toBe('function');
     // Calling remove should work without error
     remove();
-    t.pass();
+    expect(true).toBe(true);
 });
-test.serial('addToolInterceptor can be removed', (t) => {
+it.sequential('addToolInterceptor can be removed', () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     const remove = client.addToolInterceptor(async () => {
         return null;
@@ -350,78 +787,150 @@ test.serial('addToolInterceptor can be removed', (t) => {
     remove();
     // After removal, the interceptor should not be called
     // (We can't directly test this without more complex setup)
-    t.pass();
 });
 // ========== abort tests ==========
-test.serial('abort does not throw when called without active operation', (t) => {
+it.sequential('abort does not throw when called without active operation', () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     // Should not throw
-    t.notThrows(() => client.abort());
+    expect(() => client.abort()).not.toThrow();
 });
-test.serial('abort can be called multiple times', (t) => {
+it.sequential('abort can be called multiple times', () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
-    t.notThrows(() => {
+    expect(() => {
         client.abort();
         client.abort();
         client.abort();
-    });
+    }).not.toThrow();
 });
 // ========== clearConversations tests ==========
-test.serial('clearConversations does not throw', (t) => {
+it.sequential('clearConversations does not throw', () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
-    t.notThrows(() => client.clearConversations());
+    expect(() => client.clearConversations()).not.toThrow();
 });
-test.serial('clearConversations can be called multiple times', (t) => {
+it.sequential('clearConversations can be called multiple times', () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
-    t.notThrows(() => {
+    expect(() => {
         client.clearConversations();
         client.clearConversations();
-    });
+    }).not.toThrow();
 });
 // ========== setReasoningEffort tests ==========
-test.serial('setReasoningEffort accepts valid effort levels', (t) => {
+it.sequential('setReasoningEffort accepts valid effort levels', () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
-    t.notThrows(() => client.setReasoningEffort('high'));
-    t.notThrows(() => client.setReasoningEffort('medium'));
-    t.notThrows(() => client.setReasoningEffort('low'));
-    t.notThrows(() => client.setReasoningEffort('default'));
-    t.notThrows(() => client.setReasoningEffort(undefined));
+    expect(() => client.setReasoningEffort('high')).not.toThrow();
+    expect(() => client.setReasoningEffort('medium')).not.toThrow();
+    expect(() => client.setReasoningEffort('low')).not.toThrow();
+    expect(() => client.setReasoningEffort('default')).not.toThrow();
+    expect(() => client.setReasoningEffort(undefined)).not.toThrow();
 });
 // ========== setTemperature tests ==========
-test.serial('setTemperature accepts numeric values', (t) => {
+it.sequential('setTemperature accepts numeric values', () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
-    t.notThrows(() => client.setTemperature(0.5));
-    t.notThrows(() => client.setTemperature(1.0));
-    t.notThrows(() => client.setTemperature(0));
-    t.notThrows(() => client.setTemperature(undefined));
+    expect(() => client.setTemperature(0.5)).not.toThrow();
+    expect(() => client.setTemperature(1.0)).not.toThrow();
+    expect(() => client.setTemperature(0)).not.toThrow();
+    expect(() => client.setTemperature(undefined)).not.toThrow();
 });
 // ========== setRetryCallback tests ==========
-test.serial('setRetryCallback accepts callback function', (t) => {
+it.sequential('setRetryCallback accepts callback function', () => {
     const settings = createMockSettings();
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
-    t.notThrows(() => client.setRetryCallback(() => { }));
+    expect(() => client.setRetryCallback(() => { })).not.toThrow();
 });
-test.serial('setModel resets mentor conversation chain used by ask_mentor', async (t) => {
+it.sequential('setRetryCallback is forwarded to the provider runner', async () => {
+    const providerId = 'mock-retry-callback-provider';
+    let providerRetryHook;
+    let retryCount = 0;
+    registerProvider({
+        id: providerId,
+        label: 'Mock Retry Callback Provider',
+        createRunner: (deps) => {
+            providerRetryHook = deps.onRetry;
+            return {
+                run: async () => {
+                    deps.onRetry?.();
+                    return {
+                        status: 'completed',
+                        finalOutput: 'mock response',
+                        messages: [],
+                    };
+                },
+            };
+        },
+        fetchModels: async () => [{ id: 'mock-model' }],
+    });
+    const settings = createMockSettings({
+        'agent.provider': providerId,
+        'agent.model': 'mock-model',
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    client.setRetryCallback(() => {
+        retryCount += 1;
+    });
+    await client.chat('trigger retry hook');
+    expect(providerRetryHook).toBeTruthy();
+    expect(retryCount).toBe(1);
+});
+it.sequential('setAskUserAnswer stores and consumes answers by call id', () => {
+    const settings = createMockSettings();
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    client.setAskUserAnswer('call-1', 'Use the existing config');
+    expect(client.getAskUserAnswer('call-1')).toBe('Use the existing config');
+    expect(client.getAskUserAnswer('call-1')).toBeUndefined();
+});
+it.sequential('getAskUserAnswer returns undefined for unknown call ids', () => {
+    const settings = createMockSettings();
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    expect(client.getAskUserAnswer('missing-call')).toBeUndefined();
+    expect(client.getAskUserAnswer()).toBeUndefined();
+});
+it.sequential('ask_user tool executes using the stored approval answer', async () => {
+    const settings = createMockSettings({
+        'agent.provider': 'mock-main-mentor-refresh',
+        'agent.model': 'mock-model',
+        'app.liteMode': false,
+    });
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    await client.chat('prime tools');
+    const askUserTool = capturedMainAgentForMentorTest?.tools?.find((tool) => tool?.name === 'ask_user');
+    expect(askUserTool).toBeTruthy();
+    expect(typeof askUserTool?.invoke).toBe('function');
+    client.setAskUserAnswer('call-bridge', 'Use the safe option');
+    const result = await askUserTool.invoke({}, JSON.stringify({
+        questions: [{ question: 'Which option should I use?', options: ['Use the safe option', 'Ask later'] }],
+    }), { toolCall: { callId: 'call-bridge' } });
+    expect(result).toBe('Use the safe option');
+    expect(client.getAskUserAnswer('call-bridge')).toBeUndefined();
+});
+it.sequential('setModel resets mentor conversation chain used by ask_mentor', async () => {
     const settings = createMockSettings({
         'agent.provider': 'mock-main-mentor-refresh',
         'agent.model': 'mock-model',
@@ -429,27 +938,27 @@ test.serial('setModel resets mentor conversation chain used by ask_mentor', asyn
         'agent.mentorProvider': 'mock-mentor-refresh',
         'app.liteMode': false,
     });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     await client.chat('prime tools');
     const askMentorTool = capturedMainAgentForMentorTest?.tools?.find((tool) => tool?.name === 'ask_mentor');
-    t.truthy(askMentorTool);
-    t.is(typeof askMentorTool?.invoke, 'function');
+    expect(askMentorTool).toBeTruthy();
+    expect(typeof askMentorTool?.invoke).toBe('function');
     await askMentorTool.invoke({}, JSON.stringify({ question: 'first' }), { toolCall: { callId: 'call-1' } });
     await askMentorTool.invoke({}, JSON.stringify({ question: 'second' }), { toolCall: { callId: 'call-2' } });
-    t.is(mentorInputs.length, 2);
-    t.true(Array.isArray(mentorInputs[0]));
-    t.true(Array.isArray(mentorInputs[1]));
-    t.is(mentorInputs[0].length, 1);
-    t.true(mentorInputs[1].length > 1);
+    expect(mentorInputs.length).toBe(2);
+    expect(Array.isArray(mentorInputs[0])).toBe(true);
+    expect(Array.isArray(mentorInputs[1])).toBe(true);
+    expect(mentorInputs[0].length).toBe(1);
+    expect(mentorInputs[1].length > 1).toBe(true);
     client.setModel('mock-model-v2');
     await askMentorTool.invoke({}, JSON.stringify({ question: 'third' }), { toolCall: { callId: 'call-3' } });
-    t.is(mentorInputs.length, 3);
-    t.true(Array.isArray(mentorInputs[2]));
-    t.is(mentorInputs[2].length, 1);
+    expect(mentorInputs.length).toBe(3);
+    expect(Array.isArray(mentorInputs[2])).toBe(true);
+    expect(mentorInputs[2].length).toBe(1);
 });
-test.serial('ask_mentor resets conversation chain when mentor provider changes', async (t) => {
+it.sequential('ask_mentor resets conversation chain when mentor provider changes', async () => {
     const settings = createMockSettings({
         'agent.provider': 'mock-main-mentor-refresh',
         'agent.model': 'mock-model',
@@ -457,27 +966,27 @@ test.serial('ask_mentor resets conversation chain when mentor provider changes',
         'agent.mentorProvider': 'mock-mentor-refresh',
         'app.liteMode': false,
     });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     await client.chat('prime tools');
     const askMentorTool = capturedMainAgentForMentorTest?.tools?.find((tool) => tool?.name === 'ask_mentor');
-    t.truthy(askMentorTool);
-    t.is(typeof askMentorTool?.invoke, 'function');
+    expect(askMentorTool).toBeTruthy();
+    expect(typeof askMentorTool?.invoke).toBe('function');
     await askMentorTool.invoke({}, JSON.stringify({ question: 'first' }), { toolCall: { callId: 'call-1' } });
     await askMentorTool.invoke({}, JSON.stringify({ question: 'second' }), { toolCall: { callId: 'call-2' } });
-    t.is(mentorInputs.length, 2);
-    t.true(Array.isArray(mentorInputs[0]));
-    t.true(Array.isArray(mentorInputs[1]));
-    t.is(mentorInputs[0].length, 1);
-    t.true(mentorInputs[1].length > 1);
+    expect(mentorInputs.length).toBe(2);
+    expect(Array.isArray(mentorInputs[0])).toBe(true);
+    expect(Array.isArray(mentorInputs[1])).toBe(true);
+    expect(mentorInputs[0].length).toBe(1);
+    expect(mentorInputs[1].length > 1).toBe(true);
     settings.set('agent.mentorProvider', 'mock-mentor-refresh-alt');
     await askMentorTool.invoke({}, JSON.stringify({ question: 'third' }), { toolCall: { callId: 'call-3' } });
-    t.is(mentorInputsAltProvider.length, 1);
-    t.true(Array.isArray(mentorInputsAltProvider[0]));
-    t.is(mentorInputsAltProvider[0].length, 1);
+    expect(mentorInputsAltProvider.length).toBe(1);
+    expect(Array.isArray(mentorInputsAltProvider[0])).toBe(true);
+    expect(mentorInputsAltProvider[0].length).toBe(1);
 });
-test.serial('setSubagentEventSink defers cleanup to null when subagents are active', async (t) => {
+it.sequential('setSubagentEventSink defers cleanup to null when subagents are active', async () => {
     let subagentPromiseResolve = null;
     registerProvider({
         id: 'mock-deferred-sink-provider',
@@ -504,12 +1013,12 @@ test.serial('setSubagentEventSink defers cleanup to null when subagents are acti
         'agent.mentorProvider': 'mock-deferred-sink-provider',
         'app.liteMode': false,
     });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     await client.chat('prime tools');
     const askMentorTool = capturedMainAgentForMentorTest?.tools?.find((tool) => tool?.name === 'ask_mentor');
-    t.truthy(askMentorTool);
+    expect(askMentorTool).toBeTruthy();
     let eventCount = 0;
     const dummySink = () => {
         eventCount++;
@@ -529,9 +1038,9 @@ test.serial('setSubagentEventSink defers cleanup to null when subagents are acti
     }
     await invokePromise;
     // The event sink should have been kept active until the end of the run
-    t.true(eventCount > 0, 'Should have received events during the active run even after setting sink to null');
+    expect(eventCount > 0).toBe(true);
 });
-test.serial('codex resolves default_reasoning_level if agent.reasoningEffort is default', async (t) => {
+it.sequential('codex resolves default_reasoning_level if agent.reasoningEffort is default', async () => {
     const settings = createMockSettings({
         'agent.provider': 'codex',
         'agent.model': 'gpt-5.3-codex',
@@ -556,17 +1065,17 @@ test.serial('codex resolves default_reasoning_level if agent.reasoningEffort is
             supportsTracingControl: true,
         },
     }, { allowOverride: true });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     await client.startStream('Hello');
-    t.is(codexRunnerCalls.length, 1);
+    expect(codexRunnerCalls.length).toBe(1);
     const agent = codexRunnerCalls[0].agent;
-    t.truthy(agent);
-    t.is(agent.modelSettings?.reasoning?.effort, 'medium');
-    t.is(agent.defaultRunOptions?.reasoning?.effort, 'medium');
+    expect(agent).toBeTruthy();
+    expect(agent.modelSettings?.reasoning?.effort).toBe('medium');
+    expect(agent.defaultRunOptions?.reasoning?.effort).toBe('medium');
 });
-test.serial('codex chat resolves default_reasoning_level if agent.reasoningEffort is default', async (t) => {
+it.sequential('codex chat resolves default_reasoning_level if agent.reasoningEffort is default', async () => {
     const settings = createMockSettings({
         'agent.provider': 'codex',
         'agent.model': 'gpt-5.3-codex',
@@ -591,13 +1100,62 @@ test.serial('codex chat resolves default_reasoning_level if agent.reasoningEffor
             supportsTracingControl: true,
         },
     }, { allowOverride: true });
-    const client = new OpenAIAgentClient({
-        deps: { logger: createMockLogger(), settings },
+    const client = new AgentClient({
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
     });
     await client.chat('Hello', { provider: 'codex', model: 'gpt-5.3-codex', reasoningEffort: 'default' });
-    t.is(codexRunnerCalls.length, 1);
+    expect(codexRunnerCalls.length).toBe(1);
     const agent = codexRunnerCalls[0].agent;
-    t.truthy(agent);
-    t.is(agent.modelSettings?.reasoning?.effort, 'medium');
+    expect(agent).toBeTruthy();
+    expect(agent.modelSettings?.reasoning?.effort).toBe('medium');
+});
+it.sequential('main agent client injects warning into tool output when turns left <= 5', async () => {
+    let executeOutput = null;
+    registerProvider({
+        id: 'mock-provider-maxturns',
+        label: 'Mock Provider MaxTurns',
+        createRunner: () => ({
+            run: async (agent, _input, options) => {
+                if (options.callModelInputFilter) {
+                    // Simulate 96 turns
+                    for (let i = 0; i < 96; i++) {
+                        await options.callModelInputFilter({
+                            modelData: { input: [] },
+                            agent,
+                            context: options.context,
+                        });
+                    }
+                }
+                // Execute a tool to see if the warning is injected
+                const readFileTool = agent.tools.find((tool) => tool.name === 'read_file');
+                if (readFileTool) {
+                    const mockRunContext = {
+                        context: options.context,
+                    };
+                    executeOutput = await readFileTool.invoke(mockRunContext, JSON.stringify({ path: 'package.json' }), {});
+                }
+                return {
+                    status: 'completed',
+                    finalOutput: 'done',
+                    history: [],
+                    messages: [],
+                };
+            },
+        }),
+        fetchModels: async () => [{ id: 'mock-model' }],
+    });
+    const settings = createMockSettings({
+        'agent.provider': 'mock-provider-maxturns',
+        'agent.model': 'mock-model',
+    });
+    const client = new AgentClient({
+        maxTurns: 100,
+        deps: { logger: createMockLogger(), settings, sessionContextService: createSessionContextService() },
+    });
+    // Trigger startStream to initiate the provider run with correct context
+    await client.startStream('Hello');
+    expect(executeOutput).toBeTruthy();
+    expect(executeOutput.includes('approaching the maximum turn limit')).toBe(true);
+    expect(executeOutput.includes('4 turns left')).toBe(true);
 });
 //# sourceMappingURL=openai-agent-client.public-methods.test.js.map