Cleaner support of conversation history (#18)

* Cleaner support of conversation history
* Typing on conversation changes

Author: steven10a

examples/basic/agents_sdk.ts

@@ -12,6 +12,7 @@
 import * as readline from 'readline';
 import { GuardrailAgent } from '../../src';
 import { InputGuardrailTripwireTriggered, OutputGuardrailTripwireTriggered } from '@openai/agents';
+import type { AgentInputItem } from '@openai/agents';
 
 // Define your pipeline configuration
 const PIPELINE_CONFIG = {
@@ -82,6 +83,9 @@ async function main(): Promise<void> {
     // Dynamic import to avoid bundling issues
     const { run } = await import('@openai/agents');
 
+    // Maintain conversation history locally (TypeScript Agents SDK doesn't support Sessions yet)
+    let thread: AgentInputItem[] = [];
+
     const rl = createReadlineInterface();
 
     // Handle graceful shutdown
@@ -108,14 +112,21 @@ async function main(): Promise<void> {
 
         console.log('🤔 Processing...\n');
 
-        const result = await run(agent, userInput);
+        // Pass conversation history with the new user message
+        const result = await run(agent, thread.concat({ role: 'user', content: userInput }));
+        
+        // Update thread with the complete history including newly generated items
+        thread = result.history;
+        
         console.log(`Assistant: ${result.finalOutput}\n`);
       } catch (error: any) {
         // Handle guardrail tripwire exceptions
-        if (error instanceof InputGuardrailTripwireTriggered) {
+        const errorType = error?.constructor?.name;
+        
+        if (errorType === 'InputGuardrailTripwireTriggered' || error instanceof InputGuardrailTripwireTriggered) {
           console.log('🛑 Input guardrail triggered! Please try a different message.\n');
           continue;
-        } else if (error instanceof OutputGuardrailTripwireTriggered) {
+        } else if (errorType === 'OutputGuardrailTripwireTriggered' || error instanceof OutputGuardrailTripwireTriggered) {
           console.log('🛑 Output guardrail triggered! The response was blocked.\n');
           continue;
         } else {

src/__tests__/unit/chat-resources.test.ts

@@ -22,6 +22,9 @@ vi.mock('../../streaming.js', () => ({
 }));
 
 const baseClientMock = () => {
+  const normalizedMessages = [{ role: 'user', content: 'normalized' }];
+  const normalizedString = [{ role: 'user', content: 'Tell me something' }];
+
   return {
     extractLatestUserTextMessage: vi.fn().mockReturnValue(['latest user', 1]),
     runStageGuardrails: vi.fn(),
@@ -38,6 +41,12 @@ const baseClientMock = () => {
         create: vi.fn().mockResolvedValue({ id: 'responses-api' }),
       },
     },
+    normalizeConversationHistory: vi
+      .fn()
+      .mockImplementation((payload) =>
+        typeof payload === 'string' ? normalizedString : normalizedMessages
+      ),
+    loadConversationHistoryFromPreviousResponse: vi.fn().mockResolvedValue([]),
   };
 };
 
@@ -70,15 +79,15 @@ describe('Chat resource', () => {
       1,
       'pre_flight',
       'latest user',
-      messages,
+      client.normalizeConversationHistory.mock.results[0].value,
       false,
       false
     );
     expect(client.runStageGuardrails).toHaveBeenNthCalledWith(
       2,
       'input',
       'latest user',
-      messages,
+      client.normalizeConversationHistory.mock.results[0].value,
       false,
       false
     );
@@ -92,7 +101,7 @@ describe('Chat resource', () => {
       { id: 'chat-response' },
       [{ stage: 'preflight' }],
       [{ stage: 'input' }],
-      messages,
+      client.normalizeConversationHistory.mock.results[0].value,
       false
     );
     expect(result).toEqual({ result: 'handled' });
@@ -124,20 +133,21 @@ describe('Responses resource', () => {
       model: 'gpt-4o',
     });
 
+    expect(client.loadConversationHistoryFromPreviousResponse).toHaveBeenCalledWith(undefined);
     expect(client.extractLatestUserTextMessage).not.toHaveBeenCalled(); // string input path
     expect(client.runStageGuardrails).toHaveBeenNthCalledWith(
       1,
       'pre_flight',
       'Tell me something',
-      undefined,
+      client.normalizeConversationHistory.mock.results[0].value,
       false,
       false
     );
     expect(client.runStageGuardrails).toHaveBeenNthCalledWith(
       2,
       'input',
       'Tell me something',
-      undefined,
+      client.normalizeConversationHistory.mock.results[0].value,
       false,
       false
     );
@@ -152,7 +162,7 @@ describe('Responses resource', () => {
       { id: 'responses-api' },
       [{ stage: 'preflight' }],
       [{ stage: 'input' }],
-      'Tell me something',
+      client.normalizeConversationHistory.mock.results[0].value,
       false
     );
     expect(payload).toEqual({ result: 'handled' });

src/__tests__/unit/utils/conversation.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import {
+  appendAssistantResponse,
+  mergeConversationWithItems,
+  normalizeConversation,
+  parseConversationInput,
+} from '../../../utils/conversation';
+
+describe('conversation utilities', () => {
+  describe('normalizeConversation', () => {
+    it('normalizes plain user strings', () => {
+      const result = normalizeConversation('hello');
+      expect(result).toEqual([{ role: 'user', content: 'hello' }]);
+    });
+
+    it('normalizes mixed message objects and tool calls', () => {
+      const result = normalizeConversation([
+        { role: 'user', content: 'search for docs' },
+        {
+          role: 'assistant',
+          tool_calls: [
+            {
+              id: 'call_1',
+              function: { name: 'search_docs', arguments: '{"query": "docs"}' },
+            },
+          ],
+        },
+      ]);
+
+      expect(result).toEqual([
+        { role: 'user', content: 'search for docs' },
+        { role: 'assistant' },
+        {
+          type: 'function_call',
+          tool_name: 'search_docs',
+          arguments: '{"query": "docs"}',
+          call_id: 'call_1',
+        },
+      ]);
+    });
+
+    it('handles responses API content arrays', () => {
+      const result = normalizeConversation([
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'hello' },
+            { type: 'text', text: 'world' },
+          ],
+        },
+      ]);
+
+      expect(result).toEqual([{ role: 'user', content: 'hello world' }]);
+    });
+  });
+
+  describe('appendAssistantResponse', () => {
+    it('appends assistant output from chat responses', () => {
+      const history = [{ role: 'user', content: 'hi' }];
+      const response = {
+        choices: [
+          {
+            message: {
+              role: 'assistant',
+              content: 'hello back',
+            },
+          },
+        ],
+      };
+
+      const result = appendAssistantResponse(history, response);
+      expect(result).toEqual([
+        { role: 'user', content: 'hi' },
+        { role: 'assistant', content: 'hello back' },
+      ]);
+    });
+  });
+
+  describe('mergeConversationWithItems', () => {
+    it('extends conversation history with additional tool output items', () => {
+      const history = [{ role: 'user', content: 'plan trip' }];
+      const items = [
+        {
+          type: 'function_call_output',
+          tool_name: 'calendar',
+          arguments: '{"date":"2025-01-01"}',
+          output: '{"available": true}',
+        },
+      ];
+
+      const result = mergeConversationWithItems(history, items);
+      expect(result).toEqual([
+        { role: 'user', content: 'plan trip' },
+        {
+          type: 'function_call_output',
+          tool_name: 'calendar',
+          arguments: '{"date":"2025-01-01"}',
+          output: '{"available": true}',
+        },
+      ]);
+    });
+  });
+
+  describe('parseConversationInput', () => {
+    it('parses JSON strings extracting messages', () => {
+      const payload = JSON.stringify({ messages: [{ role: 'user', content: 'hello' }] });
+      const result = parseConversationInput(payload);
+      expect(result).toEqual([{ role: 'user', content: 'hello' }]);
+    });
+
+    it('falls back to empty array for unsupported payloads', () => {
+      expect(parseConversationInput(123)).toEqual([]);
+    });
+  });
+});