universal-llm-client 4.0.0 → 4.2.0

package/src/tests/ai-model.test.ts

@@ -0,0 +1,1614 @@
+import { fromZod } from '../zod-adapter.js';
+/**
+ * Tests for ai-model.ts — Universal Client (AIModel)
+ */
+import { describe, it, expect, beforeEach, afterEach, mock } from 'bun:test';
+import { z } from 'zod';
+import { AIModel, type AIModelConfig, AIModelApiType, BufferedAuditor, StructuredOutputError } from '../index.js';
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function createTestConfig(overrides: Partial<AIModelConfig> = {}): AIModelConfig {
+    return {
+        model: 'test-model',
+        providers: [
+            { type: AIModelApiType.Ollama, url: 'http://localhost:11434' },
+        ],
+        ...overrides,
+    };
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('AIModel', () => {
+    const originalFetch = globalThis.fetch;
+
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+
+    describe('constructor', () => {
+        it('creates with single provider', () => {
+            const model = new AIModel(createTestConfig());
+            expect(model.model).toBe('test-model');
+        });
+
+        it('creates with multiple providers', () => {
+            const model = new AIModel(createTestConfig({
+                providers: [
+                    { type: 'ollama', url: 'http://localhost:11434' },
+                    { type: 'openai', apiKey: 'sk-test' },
+                ],
+            }));
+            expect(model.model).toBe('test-model');
+        });
+
+        it('creates with all supported provider types', () => {
+            const model = new AIModel(createTestConfig({
+                providers: [
+                    { type: 'ollama' },
+                    { type: 'openai', apiKey: 'sk-test' },
+                    { type: 'google', apiKey: 'test-key' },
+                    { type: 'vertex', apiKey: 'token', region: 'us-east1' },
+                    { type: 'llamacpp', url: 'http://localhost:8080' },
+                ],
+            }));
+            expect(model.model).toBe('test-model');
+        });
+
+        it('throws for unknown provider type', () => {
+            expect(() => new AIModel(createTestConfig({
+                providers: [{ type: 'unknown' as never }],
+            }))).toThrow('Unknown provider type');
+        });
+    });
+
+    describe('model management', () => {
+        it('returns model name', () => {
+            const model = new AIModel(createTestConfig());
+            expect(model.model).toBe('test-model');
+        });
+
+        it('switches model at runtime', () => {
+            const model = new AIModel(createTestConfig());
+            model.setModel('new-model');
+            expect(model.model).toBe('new-model');
+        });
+    });
+
+    describe('chat (with fetch mock)', () => {
+        it('chat returns a response from Ollama provider', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: 'Hello from Ollama' },
+                    done: true,
+                    prompt_eval_count: 10,
+                    eval_count: 5,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const response = await model.chat([
+                { role: 'user', content: 'Hello' },
+            ]);
+
+            expect(response.message.role).toBe('assistant');
+            expect(response.message.content).toBe('Hello from Ollama');
+            expect(response.provider).toBe('ollama');
+        });
+
+        it('chat returns a response from OpenAI provider', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    id: 'chatcmpl-test',
+                    object: 'chat.completion',
+                    created: Date.now(),
+                    model: 'test-model',
+                    choices: [{
+                        index: 0,
+                        message: { role: 'assistant', content: 'Hello from OpenAI' },
+                        finish_reason: 'stop',
+                    }],
+                    usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const response = await model.chat([
+                { role: 'user', content: 'Hello' },
+            ]);
+
+            expect(response.message.content).toBe('Hello from OpenAI');
+            expect(response.provider).toBe('openai');
+            expect(response.usage?.totalTokens).toBe(15);
+        });
+
+        it('chat returns a response from Google provider', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    candidates: [{
+                        content: {
+                            parts: [{ text: 'Hello from Google' }],
+                            role: 'model',
+                        },
+                        finishReason: 'STOP',
+                        index: 0,
+                    }],
+                    usageMetadata: {
+                        promptTokenCount: 10,
+                        candidatesTokenCount: 5,
+                        totalTokenCount: 15,
+                    },
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'google', apiKey: 'test-key' }],
+            }));
+
+            const response = await model.chat([
+                { role: 'user', content: 'Hello' },
+            ]);
+
+            expect(response.message.content).toBe('Hello from Google');
+            expect(response.provider).toBe('google');
+        });
+    });
+
+    describe('failover', () => {
+        it('fails over from unhealthy provider to healthy one', async () => {
+            let callCount = 0;
+            globalThis.fetch = mock(async (url: string | URL | Request) => {
+                callCount++;
+                const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+                if (urlStr.includes('11434')) {
+                    return new Response('Server Error', { status: 500 });
+                }
+                return new Response(JSON.stringify({
+                    id: 'test',
+                    object: 'chat.completion',
+                    created: Date.now(),
+                    model: 'test-model',
+                    choices: [{
+                        index: 0,
+                        message: { role: 'assistant', content: 'From backup' },
+                        finish_reason: 'stop',
+                    }],
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                retries: 0, // No retries for faster test
+                providers: [
+                    { type: 'ollama', url: 'http://localhost:11434' },
+                    { type: 'openai', url: 'http://localhost:8080', apiKey: 'test' },
+                ],
+            }));
+
+            const response = await model.chat([
+                { role: 'user', content: 'Hello' },
+            ]);
+
+            expect(response.message.content).toBe('From backup');
+            expect(response.provider).toBe('openai');
+        });
+    });
+
+    describe('tool registration', () => {
+        it('registers a tool', () => {
+            const model = new AIModel(createTestConfig());
+            model.registerTool(
+                'test_tool',
+                'A test tool',
+                { type: 'object', properties: {} },
+                async () => 'result',
+            );
+            // If no error, registration succeeded
+            expect(true).toBe(true);
+        });
+
+        it('registers multiple tools', () => {
+            const model = new AIModel(createTestConfig());
+            model.registerTools([
+                {
+                    name: 'tool_a',
+                    description: 'Tool A',
+                    parameters: { type: 'object' },
+                    handler: async () => 'a',
+                },
+                {
+                    name: 'tool_b',
+                    description: 'Tool B',
+                    parameters: { type: 'object' },
+                    handler: async () => 'b',
+                },
+            ]);
+            expect(true).toBe(true);
+        });
+    });
+
+    describe('provider status', () => {
+        it('returns provider status', () => {
+            const model = new AIModel(createTestConfig({
+                providers: [
+                    { type: 'ollama' },
+                    { type: 'openai', apiKey: 'sk-test' },
+                ],
+            }));
+
+            const status = model.getProviderStatus();
+            expect(status).toHaveLength(2);
+            expect(status[0]!.healthy).toBe(true);
+            expect(status[1]!.healthy).toBe(true);
+        });
+    });
+
+    describe('observability', () => {
+        it('records events through auditor', async () => {
+            const auditor = new BufferedAuditor();
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test', created_at: '', done: true,
+                    message: { role: 'assistant', content: 'ok' },
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({ auditor }));
+            await model.chat([{ role: 'user', content: 'test' }]);
+
+            const events = auditor.getEvents();
+            expect(events.length).toBeGreaterThan(0);
+
+            const types = events.map(e => e.type);
+            expect(types).toContain('request');
+            expect(types).toContain('response');
+        });
+    });
+
+    describe('lifecycle', () => {
+        it('dispose flushes auditor', async () => {
+            let flushed = false;
+            const auditor = new BufferedAuditor({
+                onFlush: async () => { flushed = true; },
+            });
+            auditor.record({ timestamp: Date.now(), type: 'request' });
+
+            const model = new AIModel(createTestConfig({ auditor }));
+            await model.dispose();
+
+            expect(flushed).toBe(true);
+        });
+    });
+
+    // ========================================================================
+    // Structured Output Tests (VAL-API-001, VAL-API-002, VAL-API-003, VAL-API-006, VAL-API-007)
+    // ========================================================================
+
+    describe('generateStructured', () => {
+        const UserSchema = z.object({
+            name: z.string(),
+            age: z.number(),
+            email: z.string().email().optional(),
+        });
+
+        type User = z.infer<typeof UserSchema>;
+
+        it('returns typed object matching schema (VAL-API-001)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Alice", "age": 30}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.generateStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            expect(result.name).toBe('Alice');
+            expect(result.age).toBe(30);
+        });
+
+        it('returns typed object with optional fields', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Bob", "age": 25, "email": "bob@example.com"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.generateStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user with email' },
+            ]);
+
+            expect(result.name).toBe('Bob');
+            expect(result.age).toBe(25);
+            expect(result.email).toBe('bob@example.com');
+        });
+
+        it('passes options (temperature, maxTokens) to provider (VAL-API-002)', async () => {
+            let capturedBody: Record<string, unknown> | undefined;
+            globalThis.fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+                if (init?.body) {
+                    capturedBody = JSON.parse(init.body as string);
+                }
+                return new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Test", "age": 20}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            await model.generateStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ], { temperature: 0.5, maxTokens: 100 });
+
+            // Ollama uses 'options' object for temperature and max_tokens
+            expect(capturedBody?.options).toBeDefined();
+            expect((capturedBody?.options as Record<string, unknown>)?.temperature).toBe(0.5);
+        });
+
+        it('failover works across providers with same structured output request (VAL-API-003)', async () => {
+            let firstProviderCalled = false;
+            globalThis.fetch = mock(async (url: string | URL | Request) => {
+                const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+                // First provider (Ollama) fails
+                if (urlStr.includes('11434') && !firstProviderCalled) {
+                    firstProviderCalled = true;
+                    return new Response('Server Error', { status: 500 });
+                }
+                // Second provider (OpenAI-compatible) succeeds
+                return new Response(JSON.stringify({
+                    id: 'chatcmpl-test',
+                    object: 'chat.completion',
+                    created: Date.now(),
+                    model: 'test-model',
+                    choices: [{
+                        index: 0,
+                        message: { role: 'assistant', content: '{"name": "Failover", "age": 40}' },
+                        finish_reason: 'stop',
+                    }],
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                retries: 0,
+                providers: [
+                    { type: 'ollama', url: 'http://localhost:11434' },
+                    { type: 'openai', url: 'http://localhost:8080/v1', apiKey: 'test' },
+                ],
+            }));
+
+            const result = await model.generateStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            expect(result.name).toBe('Failover');
+            expect(result.age).toBe(40);
+        });
+
+        it('throws StructuredOutputError on validation failure (VAL-API-001)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Alice", "age": "not a number"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+
+            expect(
+                model.generateStructured(fromZod(UserSchema), [{ role: 'user', content: 'Generate a user' }])
+            ).rejects.toThrow(StructuredOutputError);
+        });
+
+        it('throws StructuredOutputError on invalid JSON response', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: 'not valid json' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+
+            expect(
+                model.generateStructured(fromZod(UserSchema), [{ role: 'user', content: 'Generate a user' }])
+            ).rejects.toThrow(StructuredOutputError);
+        });
+
+        it('accepts raw JSON Schema instead of Zod', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Schema", "age": 50}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.generateStructured(fromZod(UserSchema),
+                [{ role: 'user', content: 'Generate a user' }],
+            );
+
+            expect(result.name).toBe('Schema');
+            expect(result.age).toBe(50);
+        });
+
+        it('works with nested object schemas', async () => {
+            const NestedSchema = z.object({
+                user: z.object({
+                    name: z.string(),
+                    address: z.object({
+                        city: z.string(),
+                        country: z.string(),
+                    }),
+                }),
+            });
+
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: {
+                        role: 'assistant',
+                        content: '{"user": {"name": "Nested", "address": {"city": "NYC", "country": "USA"}}}',
+                    },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.generateStructured(fromZod(NestedSchema), [
+                { role: 'user', content: 'Generate a nested user' },
+            ]);
+
+            expect(result.user.name).toBe('Nested');
+            expect(result.user.address.city).toBe('NYC');
+        });
+
+        it('works with array schemas', async () => {
+            const ArraySchema = z.object({
+                items: z.array(z.string()),
+            });
+
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"items": ["a", "b", "c"]}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.generateStructured(fromZod(ArraySchema), [
+                { role: 'user', content: 'Generate items' },
+            ]);
+
+            expect(result.items).toEqual(['a', 'b', 'c']);
+        });
+
+        it('works with enum schemas', async () => {
+            const EnumSchema = z.object({
+                status: z.enum(['active', 'inactive', 'pending']),
+            });
+
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"status": "active"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.generateStructured(fromZod(EnumSchema), [
+                { role: 'user', content: 'Generate status' },
+            ]);
+
+            expect(result.status).toBe('active');
+        });
+    });
+
+    describe('tryParseStructured', () => {
+        const UserSchema = z.object({
+            name: z.string(),
+            age: z.number(),
+        });
+
+        type User = z.infer<typeof UserSchema>;
+
+        it('returns { ok: true, value } on success (VAL-API-006)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Alice", "age": 30}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.tryParseStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value.name).toBe('Alice');
+                expect(result.value.age).toBe(30);
+            }
+        });
+
+        it('returns { ok: false, error, rawOutput } on validation failure (VAL-API-007)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Alice", "age": "wrong type"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.tryParseStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error).toBeInstanceOf(StructuredOutputError);
+                expect(result.rawOutput).toBe('{"name": "Alice", "age": "wrong type"}');
+            }
+        });
+
+        it('returns { ok: false, ... } on malformed JSON (VAL-API-007)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: 'not valid json at all' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.tryParseStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.error).toBeInstanceOf(StructuredOutputError);
+                expect(result.rawOutput).toBe('not valid json at all');
+            }
+        });
+
+        it('never throws, always returns result object (VAL-API-007)', async () => {
+            // Test with valid response
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Test", "age": 25}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+
+            // Should not throw on success
+            const result1 = await model.tryParseStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Test' },
+            ]);
+            expect(result1.ok).toBe(true);
+
+            // Now test with invalid response - need to re-mock
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: 'invalid' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            // Should not throw on failure
+            const result2 = await model.tryParseStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Test' },
+            ]);
+            expect(result2.ok).toBe(false);
+        });
+
+        it('includes raw output in failure result for debugging', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"unexpected": "structure"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.tryParseStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            expect(result.ok).toBe(false);
+            if (!result.ok) {
+                expect(result.rawOutput).toBe('{"unexpected": "structure"}');
+                expect(result.error.message).toContain('Validation failed');
+            }
+        });
+
+        it('handles options (temperature, maxTokens)', async () => {
+            let capturedBody: Record<string, unknown> | undefined;
+            globalThis.fetch = mock(async (url: string | URL | Request, init?: RequestInit) => {
+                if (init?.body) {
+                    capturedBody = JSON.parse(init.body as string);
+                }
+                return new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Test", "age": 20}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const result = await model.tryParseStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ], { temperature: 0.3, maxTokens: 50 });
+
+            expect(result.ok).toBe(true);
+            // Verify options were passed to provider
+            expect(capturedBody?.options).toBeDefined();
+        });
+
+        it('works with failover across providers', async () => {
+            let firstProviderCalled = false;
+            globalThis.fetch = mock(async (url: string | URL | Request) => {
+                const urlStr = typeof url === 'string' ? url : url instanceof URL ? url.toString() : url.url;
+                // First provider (Ollama) fails
+                if (urlStr.includes('11434') && !firstProviderCalled) {
+                    firstProviderCalled = true;
+                    return new Response('Server Error', { status: 500 });
+                }
+                // Second provider succeeds
+                return new Response(JSON.stringify({
+                    id: 'chatcmpl-test',
+                    object: 'chat.completion',
+                    created: Date.now(),
+                    model: 'test-model',
+                    choices: [{
+                        index: 0,
+                        message: { role: 'assistant', content: '{"name": "Failover", "age": 99}' },
+                        finish_reason: 'stop',
+                    }],
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                retries: 0,
+                providers: [
+                    { type: 'ollama', url: 'http://localhost:11434' },
+                    { type: 'openai', url: 'http://localhost:8080/v1', apiKey: 'test' },
+                ],
+            }));
+
+            const result = await model.tryParseStructured(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            expect(result.ok).toBe(true);
+            if (result.ok) {
+                expect(result.value.name).toBe('Failover');
+                expect(result.value.age).toBe(99);
+            }
+        });
+    });
+
+    // ========================================================================
+    // Chat with output parameter Tests (VAL-API-004, VAL-API-005)
+    // ========================================================================
+
+    describe('chat with output parameter', () => {
+        const UserSchema = z.object({
+            name: z.string(),
+            age: z.number(),
+        });
+
+        it('returns response with structured property when output is provided (VAL-API-004)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Alice", "age": 30}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const response = await model.chat([
+                { role: 'user', content: 'Generate a user' },
+            ], {
+                output: { schema: fromZod(UserSchema) },
+            });
+
+            // Response should have both message.content and structured property
+            expect(response.message.content).toBe('{"name": "Alice", "age": 30}');
+            expect(response.structured).toBeDefined();
+            expect(response.structured?.name).toBe('Alice');
+            expect(response.structured?.age).toBe(30);
+        });
+
+        it('returns structured property with type inference from schema', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Bob", "age": 25}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const response = await model.chat([
+                { role: 'user', content: 'Generate a user' },
+            ], {
+                output: { schema: fromZod(UserSchema) },
+            });
+
+            // Type check: response.structured should be typed correctly
+            if (response.structured) {
+                const name: string = response.structured.name;
+                const age: number = response.structured.age;
+                expect(name).toBe('Bob');
+                expect(age).toBe(25);
+            }
+        });
+
+        it('output parameter with name and description', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Charlie", "age": 40}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const response = await model.chat([
+                { role: 'user', content: 'Generate a user' },
+            ], {
+                output: {
+                    schema: fromZod(UserSchema),
+                    name: 'User',
+                    description: 'A user object',
+                },
+            });
+
+            expect(response.structured?.name).toBe('Charlie');
+            expect(response.structured?.age).toBe(40);
+        });
+
+        it('throws StructuredOutputError when response fails validation', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Alice", "age": "not a number"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+
+            expect(
+                model.chat([{ role: 'user', content: 'Generate a user' }], {
+                    output: { schema: fromZod(UserSchema) },
+                })
+            ).rejects.toThrow(StructuredOutputError);
+        });
+
+        it('structured is undefined when output is not provided', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: 'Hello world' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const response = await model.chat([
+                { role: 'user', content: 'Hello' },
+            ]);
+
+            expect(response.structured).toBeUndefined();
+        });
+
+        it('works with all providers (OpenAI)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    id: 'chatcmpl-test',
+                    object: 'chat.completion',
+                    created: Date.now(),
+                    model: 'test-model',
+                    choices: [{
+                        index: 0,
+                        message: { role: 'assistant', content: '{"name": "OpenAI", "age": 35}' },
+                        finish_reason: 'stop',
+                    }],
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const response = await model.chat(
+                [{ role: 'user', content: 'Generate a user' }],
+                { output: { schema: fromZod(UserSchema) } },
+            );
+
+            expect(response.structured?.name).toBe('OpenAI');
+            expect(response.structured?.age).toBe(35);
+        });
+
+        it('works with all providers (Google)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    candidates: [{
+                        content: {
+                            parts: [{ text: '{"name": "Google", "age": 20}' }],
+                            role: 'model',
+                        },
+                        finishReason: 'STOP',
+                        index: 0,
+                    }],
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'google', apiKey: 'test-key' }],
+            }));
+
+            const response = await model.chat(
+                [{ role: 'user', content: 'Generate a user' }],
+                { output: { schema: fromZod(UserSchema) } },
+            );
+
+            expect(response.structured?.name).toBe('Google');
+            expect(response.structured?.age).toBe(20);
+        });
+    });
+
+    describe('output and tools combined usage (VAL-API-005)', () => {
+        const TestSchema = z.object({
+            result: z.string(),
+        });
+
+        it('allows both output and tools in the same request', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"result": "structured response"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const response = await model.chat([{ role: 'user', content: 'test' }], {
+                output: { schema: fromZod(TestSchema) },
+                tools: [{ type: 'function', function: { name: 'test', description: 'test', parameters: { type: 'object' } } }],
+            });
+
+            // When the model returns content (not tool calls), structured output should be validated
+            expect(response.structured?.result).toBe('structured response');
+        });
+
+        it('skips validation when response contains tool calls', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: {
+                        role: 'assistant',
+                        content: '',
+                        tool_calls: [{ id: 'call_1', type: 'function', function: { name: 'test', arguments: '{}' } }],
+                    },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const response = await model.chat([{ role: 'user', content: 'test' }], {
+                output: { schema: fromZod(TestSchema) },
+                tools: [{ type: 'function', function: { name: 'test', description: 'test', parameters: { type: 'object' } } }],
+            });
+
+            // Response should contain tool calls without throwing validation errors
+            expect(response.message.tool_calls).toBeDefined();
+            expect(response.message.tool_calls!.length).toBe(1);
+        });
+
+        it('works with output only (no tools)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"result": "success"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const response = await model.chat([{ role: 'user', content: 'test' }], {
+                output: { schema: fromZod(TestSchema) },
+            });
+
+            expect(response.structured?.result).toBe('success');
+        });
+
+        it('works with tools only (no output)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: 'Using tool...' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+            const response = await model.chat([{ role: 'user', content: 'test' }], {
+                tools: [{ type: 'function', function: { name: 'test', description: 'test', parameters: { type: 'object' } } }],
+            });
+
+            expect(response.message.content).toBe('Using tool...');
+            expect(response.structured).toBeUndefined();
+        });
+
+        it('allows output with empty tools array (no tools)', async () => {
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"result": "success"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+
+            // Empty tools array should be allowed with output (no actual tools)
+            const response = await model.chat([{ role: 'user', content: 'test' }], {
+                output: { schema: fromZod(TestSchema) },
+                tools: [],
+            });
+
+            expect(response.structured?.result).toBe('success');
+        });
+    });
+
+    describe('generateStructuredStream', () => {
+        const UserSchema = z.object({
+            name: z.string(),
+            age: z.number(),
+            email: z.string().optional(),
+        });
+
+        it('yields partial validated objects during streaming (VAL-API-008)', async () => {
+            // Mock streaming response that yields chunks
+            const chunks = [
+                'data: {"choices":[{"delta":{"content":"{\\"name\\":"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":"\\"Alice\\""}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":", \\"age\\":30"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":"}"}}]}\n\n',
+                'data: [DONE]\n\n',
+            ];
+
+            let chunkIndex = 0;
+            globalThis.fetch = mock(async () => {
+                return new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'text/event-stream' },
+                });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const partials: unknown[] = [];
+            const stream = model.generateStructuredStream(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            for await (const partial of stream) {
+                partials.push(partial);
+            }
+
+            // Should have yielded partial objects
+            expect(partials.length).toBeGreaterThan(0);
+            
+            // Final partial should match schema
+            const lastPartial = partials[partials.length - 1];
+            expect(lastPartial).toHaveProperty('name');
+        });
+
+        it('returns complete validated object as generator return value (VAL-API-008)', async () => {
+            // Mock streaming response - produce valid JSON: {"name": "Bob", "age": 25}
+            const chunks = [
+                'data: {"choices":[{"delta":{"content":"{\\"name\\":"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":" \\"Bob\\""}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":", \\"age\\": 25"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":"}"}}]}\n\n',
+                'data: [DONE]\n\n',
+            ];
+
+            globalThis.fetch = mock(async () => {
+                return new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'text/event-stream' },
+                });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const stream = model.generateStructuredStream(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            // Consume the stream
+            const partials: unknown[] = [];
+            for await (const partial of stream) {
+                partials.push(partial);
+            }
+
+            // Verify we got partials
+            expect(partials.length).toBeGreaterThan(0);
+        });
+
+        it('handles validation errors mid-stream gracefully', async () => {
+            // Mock streaming response with invalid data mid-stream that becomes valid
+            const chunks = [
+                'data: {"choices":[{"delta":{"content":"{\\"name\\":"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":"\\"test\\""}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":", \\"age\\": \\"invalid\\""}}]}\n\n', // age should be number
+                'data: {"choices":[{"delta":{"content":\\"}"}}]}\n\n',
+                'data: [DONE]\n\n',
+            ];
+
+            globalThis.fetch = mock(async () => {
+                return new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'text/event-stream' },
+                });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const stream = model.generateStructuredStream(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            // Consume the stream - should either yield valid partials or throw at the end
+            const partials: unknown[] = [];
+            try {
+                for await (const partial of stream) {
+                    partials.push(partial);
+                }
+                // If no error was thrown, check that we handled it gracefully
+                expect(partials.length).toBeGreaterThanOrEqual(0);
+            } catch (error) {
+                // If error is thrown, it should be StructuredOutputError
+                expect(error).toBeInstanceOf(StructuredOutputError);
+            }
+        });
+
+        it('works with Ollama provider (VAL-PROVIDER-OLLAMA-005)', async () => {
+            // Mock NDJSON streaming response from Ollama
+            const chunks = [
+                JSON.stringify({ model: 'test', message: { content: '{"name":' }, done: false }) + '\n',
+                JSON.stringify({ model: 'test', message: { content: ' "Ollama",' }, done: false }) + '\n',
+                JSON.stringify({ model: 'test', message: { content: ' "age": 35' }, done: false }) + '\n',
+                JSON.stringify({ model: 'test', message: { content: '}' }, done: true }) + '\n',
+            ];
+
+            globalThis.fetch = mock(async () => {
+                return new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/x-ndjson' },
+                });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig());
+
+            const stream = model.generateStructuredStream(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            const partials: unknown[] = [];
+            for await (const partial of stream) {
+                partials.push(partial);
+            }
+
+            // Should have yielded partials
+            expect(partials.length).toBeGreaterThan(0);
+        });
+
+        it('works with Google provider (VAL-PROVIDER-GOOGLE-005)', async () => {
+            // Mock SSE streaming response from Google
+            const chunks = [
+                'data: {"candidates":[{"content":{"parts":[{"text":"{"}]}}]}\n\n',
+                'data: {"candidates":[{"content":{"parts":[{"text":"\\"name\\": \\"Google\\""}]}}]}\n\n',
+                'data: {"candidates":[{"content":{"parts":[{"text":", \\"age\\": 42"}]}}]}\n\n',
+                'data: {"candidates":[{"content":{"parts":[{"text":"}"}]}}]}\n\n',
+                'data: [DONE]\n\n',
+            ];
+
+            globalThis.fetch = mock(async () => {
+                return new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'text/event-stream' },
+                });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'google', apiKey: 'test-key' }],
+            }));
+
+            const stream = model.generateStructuredStream(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            const partials: unknown[] = [];
+            for await (const partial of stream) {
+                partials.push(partial);
+            }
+
+            // Should have yielded partials
+            expect(partials.length).toBeGreaterThan(0);
+        });
+
+        it('accepts ChatOptions (temperature, maxTokens)', async () => {
+            // Mock streaming response
+            const chunks = [
+                'data: {"choices":[{"delta":{"content":"{\\"name\\": \\"Test\\""}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":", \\"age\\": 1}"}}]}\n\n',
+                'data: [DONE]\n\n',
+            ];
+
+            globalThis.fetch = mock(async () => {
+                return new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'text/event-stream' },
+                });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const stream = model.generateStructuredStream(fromZod(UserSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ], { temperature: 0.5, maxTokens: 100 });
+
+            // Consume the stream
+            const partials: unknown[] = [];
+            for await (const partial of stream) {
+                partials.push(partial);
+            }
+
+            expect(partials.length).toBeGreaterThan(0);
+        });
+
+        it('throws StructuredOutputError on final validation failure', async () => {
+            // Mock streaming response that ends with invalid JSON
+            const chunks = [
+                'data: {"choices":[{"delta":{"content":"{\\"name\\":"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":"\\"test\\""}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":"}"}}]}\n\n', // Missing age (required by schema)
+                'data: [DONE]\n\n',
+            ];
+
+            globalThis.fetch = mock(async () => {
+                return new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'text/event-stream' },
+                });
+            }) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const StrictSchema = z.object({
+                name: z.string(),
+                age: z.number(), // Required
+            });
+
+            const stream = model.generateStructuredStream(fromZod(StrictSchema), [
+                { role: 'user', content: 'Generate a user' },
+            ]);
+
+            // Consume the stream - expect StructuredOutputError at the end
+            let errorCaught: Error | null = null;
+            try {
+                for await (const _ of stream) {
+                    // Consume partials
+                }
+            } catch (error) {
+                errorCaught = error as Error;
+            }
+
+            // Should either gracefully handle partial objects or throw validation error
+            // Both behaviors are acceptable
+            if (errorCaught) {
+                expect(errorCaught).toBeInstanceOf(StructuredOutputError);
+            }
+        });
+    });
+});
+
+// ============================================================================
+// Structured Output Auditor Tests (VAL-CROSS-003)
+// ============================================================================
+
+describe('structured output auditor events', () => {
+    const TestSchema = z.object({
+        name: z.string(),
+        value: z.number(),
+    });
+
+    const originalFetch = globalThis.fetch;
+
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+
+    describe('generateStructured auditor events', () => {
+        it('emits structured_request and structured_response events on success', async () => {
+            const auditor = new BufferedAuditor();
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Alice", "value": 42}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({ auditor }));
+            await model.generateStructured(fromZod(TestSchema), [
+                { role: 'user', content: 'Generate data' },
+            ]);
+
+            const events = auditor.getEvents();
+            const types = events.map(e => e.type);
+
+            // Should emit structured_request and structured_response
+            expect(types).toContain('structured_request');
+            expect(types).toContain('structured_response');
+
+            // Check structured_request event details
+            const requestEvent = events.find(e => e.type === 'structured_request');
+            expect(requestEvent?.schemaName).toBe('response');
+
+            // Check structured_response event details
+            const responseEvent = events.find(e => e.type === 'structured_response');
+            expect(responseEvent?.schemaName).toBe('response');
+            expect(responseEvent?.duration).toBeDefined();
+        });
+
+        it('emits structured_validation_error on validation failure', async () => {
+            const auditor = new BufferedAuditor();
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Alice", "value": "not a number"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({ auditor }));
+
+            try {
+                await model.generateStructured(fromZod(TestSchema), [
+                    { role: 'user', content: 'Generate data' },
+                ]);
+            } catch {
+                // Expected to throw StructuredOutputError
+            }
+
+            const events = auditor.getEvents();
+            const types = events.map(e => e.type);
+
+            // Should emit structured_request and structured_validation_error
+            expect(types).toContain('structured_request');
+            expect(types).toContain('structured_validation_error');
+
+            // Check structured_validation_error event details
+            const validationError = events.find(e => e.type === 'structured_validation_error');
+            expect(validationError?.schemaName).toBe('response');
+            expect(validationError?.error).toBeDefined();
+            expect(validationError?.rawOutput).toBeDefined();
+        });
+
+        it('uses custom schema name when provided', async () => {
+            const auditor = new BufferedAuditor();
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Test", "value": 1}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({ auditor }));
+            await model.generateStructured(fromZod(TestSchema), [
+                { role: 'user', content: 'Generate data' },
+            ], { schemaName: 'CustomSchema' });
+
+            const events = auditor.getEvents();
+
+            // Check structured_request event has custom schema name
+            const requestEvent = events.find(e => e.type === 'structured_request');
+            expect(requestEvent?.schemaName).toBe('CustomSchema');
+
+            // Check structured_response event has custom schema name
+            const responseEvent = events.find(e => e.type === 'structured_response');
+            expect(responseEvent?.schemaName).toBe('CustomSchema');
+        });
+    });
+
+    describe('chat output parameter auditor events', () => {
+        it('emits structured_request and structured_response with output parameter', async () => {
+            const auditor = new BufferedAuditor();
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"name": "Bob", "value": 100}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({ auditor }));
+            const response = await model.chat([
+                { role: 'user', content: 'Generate data' },
+            ], { output: { schema: fromZod(TestSchema), name: 'TestData' } });
+
+            const events = auditor.getEvents();
+            const types = events.map(e => e.type);
+
+            // Should emit structured_request and structured_response
+            expect(types).toContain('structured_request');
+            expect(types).toContain('structured_response');
+
+            // Verify structured property is populated
+            expect(response.structured?.name).toBe('Bob');
+            expect(response.structured?.value).toBe(100);
+        });
+
+        it('emits structured_validation_error when output validation fails', async () => {
+            const auditor = new BufferedAuditor();
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: '{"invalid": "data"}' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({ auditor }));
+
+            try {
+                await model.chat([
+                    { role: 'user', content: 'Generate data' },
+                ], { output: { schema: fromZod(TestSchema) } });
+            } catch {
+                // Expected to throw StructuredOutputError
+            }
+
+            const events = auditor.getEvents();
+            const types = events.map(e => e.type);
+
+            expect(types).toContain('structured_request');
+            expect(types).toContain('structured_validation_error');
+
+            const validationError = events.find(e => e.type === 'structured_validation_error');
+            expect(validationError?.rawOutput).toBe('{"invalid": "data"}');
+        });
+    });
+
+    describe('generateStructuredStream auditor events', () => {
+        it('emits structured_request on stream start and structured_response on completion', async () => {
+            const auditor = new BufferedAuditor();
+            const chunks = [
+                'data: {"choices":[{"delta":{"content":"{\\"name\\":"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":" \\"Stream\\""}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":", \\"value\\": 99"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":"}"}}]}\n\n',
+                'data: [DONE]\n\n',
+            ];
+
+            globalThis.fetch = mock(async () =>
+                new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'text/event-stream' },
+                })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                auditor,
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const stream = model.generateStructuredStream(fromZod(TestSchema), [
+                { role: 'user', content: 'Generate data' },
+            ]);
+
+            // Consume the stream
+            for await (const _ of stream) {
+                // Just consume the partials
+            }
+
+            const events = auditor.getEvents();
+            const types = events.map(e => e.type);
+
+            // Should emit structured_request at start and structured_response at end
+            expect(types).toContain('structured_request');
+            expect(types).toContain('structured_response');
+
+            // Check order: request before response
+            const requestIdx = types.indexOf('structured_request');
+            const responseIdx = types.indexOf('structured_response');
+            expect(requestIdx).toBeLessThan(responseIdx);
+        });
+
+        it('emits structured_validation_error when stream validation fails', async () => {
+            const auditor = new BufferedAuditor();
+            // Invalid JSON that doesn't match schema
+            const chunks = [
+                'data: {"choices":[{"delta":{"content":"{\\"name\\":"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":"\\"invalid\\""}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":"}"}}]}\n\n', // Missing required 'value' field
+                'data: [DONE]\n\n',
+            ];
+
+            globalThis.fetch = mock(async () =>
+                new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'text/event-stream' },
+                })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                auditor,
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const StrictSchema = z.object({
+                name: z.string(),
+                value: z.number(),
+            });
+
+            try {
+                const stream = model.generateStructuredStream(fromZod(StrictSchema), [
+                    { role: 'user', content: 'Generate data' },
+                ]);
+                for await (const _ of stream) {
+                    // Consume stream
+                }
+            } catch {
+                // Expected to throw
+            }
+
+            const events = auditor.getEvents();
+            const types = events.map(e => e.type);
+
+            // Should emit structured_request and structured_validation_error
+            expect(types).toContain('structured_request');
+            expect(types).toContain('structured_validation_error');
+        });
+    });
+
+    describe('existing chat/stream auditor events still work', () => {
+        it('chat without structured output still emits request/response events', async () => {
+            const auditor = new BufferedAuditor();
+            globalThis.fetch = mock(async () =>
+                new Response(JSON.stringify({
+                    model: 'test-model',
+                    created_at: new Date().toISOString(),
+                    message: { role: 'assistant', content: 'Hello world' },
+                    done: true,
+                }), { status: 200, headers: { 'Content-Type': 'application/json' } })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({ auditor }));
+            await model.chat([{ role: 'user', content: 'Hello' }]);
+
+            const events = auditor.getEvents();
+            const types = events.map(e => e.type);
+
+            // Should emit standard request/response events (not structured events)
+            expect(types).toContain('request');
+            expect(types).toContain('response');
+            expect(types).not.toContain('structured_request');
+            expect(types).not.toContain('structured_response');
+        });
+
+        it('chatStream emits stream_start and stream_end events', async () => {
+            const auditor = new BufferedAuditor();
+            const chunks = [
+                'data: {"choices":[{"delta":{"content":"Hello"}}]}\n\n',
+                'data: {"choices":[{"delta":{"content":" world"}}]}\n\n',
+                'data: [DONE]\n\n',
+            ];
+
+            globalThis.fetch = mock(async () =>
+                new Response(chunks.join(''), {
+                    status: 200,
+                    headers: { 'Content-Type': 'text/event-stream' },
+                })
+            ) as typeof fetch;
+
+            const model = new AIModel(createTestConfig({
+                auditor,
+                providers: [{ type: 'openai', apiKey: 'sk-test' }],
+            }));
+
+            const stream = model.chatStream([{ role: 'user', content: 'Hello' }]);
+            for await (const _ of stream) {
+                // Consume stream
+            }
+
+            const events = auditor.getEvents();
+            const types = events.map(e => e.type);
+
+            // Should emit stream_start and stream_end, not structured events
+            expect(types).toContain('stream_start');
+            expect(types).toContain('stream_end');
+            expect(types).not.toContain('structured_request');
+            expect(types).not.toContain('structured_response');
+        });
+    });
+});