@@ -0,0 +1,1088 @@
1+# OpenAI Compatibility Refactor Implementation Plan
2+
3+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
4+
5+**Goal:** Separate Ollama-specific code from OpenAI-compliant code to prevent cross-contamination and ensure strict OpenAI API compliance for all OpenAI-compatible providers.
6+
7+**Architecture:** Create shared OpenAI-compliant types and functions in `openai_common.go`. Keep Ollama-specific customizations isolated in `ollama.go`. Refactor OpenCode to use only OpenAI-standard types and remove dependencies on Ollama internals.
8+
9+**Tech Stack:** Go 1.22+, OpenAI SDK (github.com/sashabaranov/go-openai), standard HTTP client
10+
11+**Priority:** OpenAI compliance is paramount. All changes must maintain strict OpenAI Chat Completions API compatibility. Ollama-specific features (like flexible system message placement) stay exclusively in Ollama provider.
12+
13+---
14+
15+## Phase 1: Create OpenAI-Compliant Common Types
16+
17+### Task 1.1: Create openai_common.go with shared types
18+
19+**Files:**
20+- Create: `internal/provider/openai_common.go`
21+
22+**Step 1: Create file with package and imports**
23+
24+```go
25+package provider
26+
27+import (
28+ "encoding/json"
29+ "strings"
30+
31+ "github.com/rs/zerolog/log"
32+ openai "github.com/sashabaranov/go-openai"
33+)
34+```
35+
36+**Step 2: Define OpenAI-compliant response types**
37+
38+Add to `internal/provider/openai_common.go`:
39+
40+```go
41+// OpenAI-compliant response types for providers that follow OpenAI Chat Completions API spec.
42+// These types should NOT include provider-specific extensions.
43+
44+type openaiChatResponse struct {
45+ Choices []openaiChatChoice `json:"choices"`
46+}
47+
48+type openaiChatChoice struct {
49+ Message openaiChatMessage `json:"message"`
50+}
51+
52+type openaiChatMessage struct {
53+ Role string `json:"role"`
54+ Content string `json:"content"`
55+ ToolCalls []openaiChatToolCall `json:"tool_calls,omitempty"`
56+}
57+
58+type openaiChatToolCall struct {
59+ ID string `json:"id"`
60+ Type string `json:"type"`
61+ Function openaiChatFunction `json:"function"`
62+}
63+
64+type openaiChatFunction struct {
65+ Name string `json:"name"`
66+ Arguments string `json:"arguments"`
67+}
68+```
69+
70+**Step 3: Add OpenAI-compliant message conversion function**
71+
72+Add to `internal/provider/openai_common.go`:
73+
74+```go
75+// toOpenAIMessages converts provider-agnostic messages to OpenAI SDK message format.
76+// This function enforces OpenAI Chat Completions API requirements:
77+// - System messages must be first
78+// - User and assistant messages must alternate (as much as possible)
79+// - Tool messages must have tool_call_id and follow assistant messages with tool calls
80+func toOpenAIMessages(messages []Message) []openai.ChatCompletionMessage {
81+ result := make([]openai.ChatCompletionMessage, len(messages))
82+ for i, m := range messages {
83+ msg := openai.ChatCompletionMessage{
84+ Role: m.Role,
85+ Content: m.Content,
86+ }
87+
88+ // Handle tool call results
89+ if m.ToolCallID != "" {
90+ msg.ToolCallID = m.ToolCallID
91+ }
92+
93+ // Handle assistant messages with tool calls
94+ if len(m.ToolCalls) > 0 {
95+ msg.ToolCalls = make([]openai.ToolCall, len(m.ToolCalls))
96+ for j, tc := range m.ToolCalls {
97+ msg.ToolCalls[j] = openai.ToolCall{
98+ ID: tc.ID,
99+ Type: openai.ToolTypeFunction,
100+ Function: openai.FunctionCall{
101+ Name: tc.Name,
102+ Arguments: string(tc.Arguments),
103+ },
104+ }
105+ }
106+ }
107+
108+ result[i] = msg
109+ }
110+ return result
111+}
112+```
113+
114+**Step 4: Add OpenAI-compliant system message merging**
115+
116+Add to `internal/provider/openai_common.go`:
117+
118+```go
119+// mergeSystemMessagesOpenAI merges all system messages into a single message at the start.
120+// OpenAI Chat Completions API requires:
121+// 1. System messages must be first
122+// 2. At least one non-system message must follow
123+//
124+// This function collects ALL system messages regardless of position and places them
125+// at the start as a single merged message. If only system messages exist, it adds
126+// a minimal "Begin." user message to meet OpenAI requirements.
127+func mergeSystemMessagesOpenAI(messages []openai.ChatCompletionMessage) []openai.ChatCompletionMessage {
128+ if len(messages) == 0 {
129+ return messages
130+ }
131+
132+ // Separate system messages from others
133+ var systemBuffer strings.Builder
134+ nonSystemMessages := make([]openai.ChatCompletionMessage, 0, len(messages))
135+
136+ for _, msg := range messages {
137+ if msg.Role == "system" {
138+ if systemBuffer.Len() > 0 {
139+ systemBuffer.WriteString("\n\n")
140+ }
141+ systemBuffer.WriteString(msg.Content)
142+ } else {
143+ nonSystemMessages = append(nonSystemMessages, msg)
144+ }
145+ }
146+
147+ // Build result: system first, then non-system
148+ result := make([]openai.ChatCompletionMessage, 0, len(messages))
149+
150+ if systemBuffer.Len() > 0 {
151+ result = append(result, openai.ChatCompletionMessage{
152+ Role: "system",
153+ Content: systemBuffer.String(),
154+ })
155+ }
156+
157+ result = append(result, nonSystemMessages...)
158+
159+ // OpenAI requires at least one non-system message
160+ // If we only have system messages, add a minimal user message
161+ if len(nonSystemMessages) == 0 && len(result) > 0 {
162+ log.Debug().
163+ Msg("OpenAI: Only system messages present, adding minimal user message")
164+ result = append(result, openai.ChatCompletionMessage{
165+ Role: "user",
166+ Content: "Begin.",
167+ })
168+ }
169+
170+ log.Debug().
171+ Int("original_count", len(messages)).
172+ Int("merged_count", len(result)).
173+ Bool("added_user_msg", len(nonSystemMessages) == 0 && len(result) > 0).
174+ Msg("OpenAI: Merged system messages")
175+
176+ return result
177+}
178+```
179+
180+**Step 5: Add OpenAI tool conversion helper**
181+
182+Add to `internal/provider/openai_common.go`:
183+
184+```go
185+// toOpenAITools converts provider-agnostic tools to OpenAI SDK tool format.
186+// Returns error if any tool has invalid JSON schema.
187+func toOpenAITools(tools []Tool) ([]openai.Tool, error) {
188+ result := make([]openai.Tool, len(tools))
189+ for i, t := range tools {
190+ var params map[string]interface{}
191+ if len(t.Parameters) > 0 {
192+ if err := json.Unmarshal(t.Parameters, ¶ms); err != nil {
193+ // Invalid JSON schema - return error instead of silently failing
194+ return nil, err
195+ }
196+ }
197+ if params == nil {
198+ params = map[string]interface{}{
199+ "type": "object",
200+ "properties": map[string]interface{}{},
201+ }
202+ }
203+
204+ result[i] = openai.Tool{
205+ Type: openai.ToolTypeFunction,
206+ Function: &openai.FunctionDefinition{
207+ Name: t.Name,
208+ Description: t.Description,
209+ Parameters: params,
210+ },
211+ }
212+ }
213+ return result, nil
214+}
215+```
216+
217+**Step 6: Run tests**
218+
219+Run: `cd internal/provider && go build`
220+Expected: Compiles successfully
221+
222+**Step 7: Commit**
223+
224+```bash
225+git add internal/provider/openai_common.go
226+git commit -m "feat(provider): add OpenAI-compliant common types and functions
227+
228+- Add openaiChatResponse types for strict OpenAI compliance
229+- Add toOpenAIMessages with OpenAI spec enforcement
230+- Add mergeSystemMessagesOpenAI with fallback user message
231+- Add toOpenAITools with JSON schema validation
232+- All functions follow OpenAI Chat Completions API spec"
233+```
234+
235+---
236+
237+## Phase 2: Refactor OpenCode Provider to Use Common Types
238+
239+### Task 2.1: Update OpenCode to use openai_common types
240+
241+**Files:**
242+- Modify: `internal/provider/opencode.go`
243+
244+**Step 1: Update imports**
245+
246+In `internal/provider/opencode.go`, imports should already have what we need. Verify imports section looks like:
247+
248+```go
249+import (
250+ "bytes"
251+ "context"
252+ "encoding/json"
253+ "errors"
254+ "fmt"
255+ "io"
256+ "net/http"
257+ "strings"
258+
259+ "github.com/rs/zerolog/log"
260+ openai "github.com/sashabaranov/go-openai"
261+ "golang.org/x/time/rate"
262+)
263+```
264+
265+**Step 2: Update createChatCompletion return type**
266+
267+Find line ~166:
268+```go
269+func (p *OpenCodeProvider) createChatCompletion(ctx context.Context, req openai.ChatCompletionRequest) (*chatCompletionResponse, error) {
270+```
271+
272+Replace with:
273+```go
274+func (p *OpenCodeProvider) createChatCompletion(ctx context.Context, req openai.ChatCompletionRequest) (*openaiChatResponse, error) {
275+```
276+
277+**Step 3: Update response decoding**
278+
279+Find lines ~223-238 (in createChatCompletion):
280+```go
281+ // Read body for logging
282+ bodyBytes, err := io.ReadAll(resp.Body)
283+ if err != nil {
284+ log.Error().
285+ Str("provider", "opencode_zen").
286+ Err(err).
287+ Msg("OpenCode failed to read response body")
288+ return nil, fmt.Errorf("read response body: %w", err)
289+ }
290+
291+ var decoded chatCompletionResponse
292+ if err := json.Unmarshal(bodyBytes, &decoded); err != nil {
293+ log.Error().
294+ Str("provider", "opencode_zen").
295+ Err(err).
296+ Str("body", string(bodyBytes)).
297+ Msg("OpenCode JSON decode failed")
298+ return nil, fmt.Errorf("decode response: %w", err)
299+ }
300+```
301+
302+Replace `chatCompletionResponse` with `openaiChatResponse`:
303+```go
304+ // Read body for logging
305+ bodyBytes, err := io.ReadAll(resp.Body)
306+ if err != nil {
307+ log.Error().
308+ Str("provider", "opencode_zen").
309+ Err(err).
310+ Msg("OpenCode failed to read response body")
311+ return nil, fmt.Errorf("read response body: %w", err)
312+ }
313+
314+ var decoded openaiChatResponse
315+ if err := json.Unmarshal(bodyBytes, &decoded); err != nil {
316+ log.Error().
317+ Str("provider", "opencode_zen").
318+ Err(err).
319+ Str("body", string(bodyBytes)).
320+ Msg("OpenCode JSON decode failed")
321+ return nil, fmt.Errorf("decode response: %w", err)
322+ }
323+```
324+
325+**Step 4: Remove reasoning() call**
326+
327+Find lines ~136-138 (in ChatWithTools):
328+```go
329+ choice := resp.Choices[0]
330+ result := &ChatResponse{
331+ Content: choice.Message.Content,
332+ Reasoning: choice.Message.reasoning(),
333+ }
334+```
335+
336+Replace with (OpenAI standard doesn't have reasoning field):
337+```go
338+ choice := resp.Choices[0]
339+ result := &ChatResponse{
340+ Content: choice.Message.Content,
341+ Reasoning: "", // OpenAI standard doesn't provide reasoning field
342+ }
343+```
344+
345+**Step 5: Update message conversion calls**
346+
347+Find line ~65 (in Chat method):
348+```go
349+ resp, err := p.createChatCompletion(ctx, openai.ChatCompletionRequest{
350+ Model: p.model,
351+ Messages: mergeConsecutiveSystemMessages(toOpenAIMessages(messages)),
352+ Temperature: float32(p.temperature),
353+ })
354+```
355+
356+Replace with:
357+```go
358+ resp, err := p.createChatCompletion(ctx, openai.ChatCompletionRequest{
359+ Model: p.model,
360+ Messages: mergeSystemMessagesOpenAI(toOpenAIMessages(messages)),
361+ Temperature: float32(p.temperature),
362+ })
363+```
364+
365+**Step 6: Update tool conversion**
366+
367+Find lines ~88-114 (tool conversion in ChatWithTools):
368+```go
369+ openaiTools := make([]openai.Tool, len(tools))
370+ for i, t := range tools {
371+ var params map[string]interface{}
372+ if len(t.Parameters) > 0 {
373+ if err := json.Unmarshal(t.Parameters, ¶ms); err != nil {
374+ // If unmarshal fails, use empty object schema
375+ params = map[string]interface{}{
376+ "type": "object",
377+ "properties": map[string]interface{}{},
378+ }
379+ }
380+ }
381+ if params == nil {
382+ params = map[string]interface{}{
383+ "type": "object",
384+ "properties": map[string]interface{}{},
385+ }
386+ }
387+
388+ openaiTools[i] = openai.Tool{
389+ Type: openai.ToolTypeFunction,
390+ Function: &openai.FunctionDefinition{
391+ Name: t.Name,
392+ Description: t.Description,
393+ Parameters: params,
394+ },
395+ }
396+ }
397+```
398+
399+Replace with:
400+```go
401+ openaiTools, err := toOpenAITools(tools)
402+ if err != nil {
403+ return nil, fmt.Errorf("invalid tool schema: %w", err)
404+ }
405+```
406+
407+**Step 7: Update second message conversion call**
408+
409+Find line ~118 (in ChatWithTools):
410+```go
411+ resp, err := p.createChatCompletion(ctx, openai.ChatCompletionRequest{
412+ Model: p.model,
413+ Messages: mergeConsecutiveSystemMessages(toOpenAIMessages(messages)),
414+ Tools: openaiTools,
415+ Temperature: float32(p.temperature),
416+ })
417+```
418+
419+Replace with:
420+```go
421+ resp, err := p.createChatCompletion(ctx, openai.ChatCompletionRequest{
422+ Model: p.model,
423+ Messages: mergeSystemMessagesOpenAI(toOpenAIMessages(messages)),
424+ Tools: openaiTools,
425+ Temperature: float32(p.temperature),
426+ })
427+```
428+
429+**Step 8: Update streaming message conversion**
430+
431+Find line ~250 (in Stream method):
432+```go
433+ stream, err := p.client.CreateChatCompletionStream(ctx, openai.ChatCompletionRequest{
434+ Model: p.model,
435+ Messages: mergeConsecutiveSystemMessages(toOpenAIMessages(messages)),
436+ Temperature: float32(p.temperature),
437+ })
438+```
439+
440+Replace with:
441+```go
442+ stream, err := p.client.CreateChatCompletionStream(ctx, openai.ChatCompletionRequest{
443+ Model: p.model,
444+ Messages: mergeSystemMessagesOpenAI(toOpenAIMessages(messages)),
445+ Temperature: float32(p.temperature),
446+ })
447+```
448+
449+**Step 9: Remove mergeConsecutiveSystemMessages function**
450+
451+Find and DELETE lines ~291-344 (the entire `mergeConsecutiveSystemMessages` function in opencode.go).
452+
453+This function is now replaced by `mergeSystemMessagesOpenAI` in `openai_common.go`.
454+
455+**Step 10: Run tests**
456+
457+Run: `cd internal/provider && go build`
458+Expected: Compiles successfully
459+
460+**Step 11: Commit**
461+
462+```bash
463+git add internal/provider/opencode.go
464+git commit -m "refactor(provider): migrate OpenCode to use OpenAI-compliant common types
465+
466+- Use openaiChatResponse instead of Ollama's chatCompletionResponse
467+- Remove reasoning() method call (not in OpenAI standard)
468+- Use mergeSystemMessagesOpenAI from common file
469+- Use toOpenAITools from common file
470+- Remove duplicate mergeConsecutiveSystemMessages function
471+- OpenCode now fully independent of Ollama internals"
472+```
473+
474+---
475+
476+## Phase 3: Isolate Ollama-Specific Customizations
477+
478+### Task 3.1: Keep Ollama message merging separate
479+
480+**Files:**
481+- Modify: `internal/provider/ollama.go`
482+
483+**Step 1: Document Ollama-specific behavior**
484+
485+Find the `mergeConsecutiveSystemMessagesOllama` function (around line 360) and update its comment:
486+
487+```go
488+// mergeConsecutiveSystemMessagesOllama merges consecutive system messages into a single message.
489+//
490+// OLLAMA-SPECIFIC BEHAVIOR:
491+// Unlike OpenAI, Ollama allows system messages anywhere in the conversation.
492+// This function merges consecutive system messages IN PLACE without moving them to the start.
493+// This preserves Ollama's flexible system message handling.
494+//
495+// DO NOT use this function for OpenAI-compatible providers - use mergeSystemMessagesOpenAI instead.
496+func mergeConsecutiveSystemMessagesOllama(messages []ollamaReqMessage) []ollamaReqMessage {
497+ // ... existing implementation
498+}
499+```
500+
501+**Step 2: Add comment to toOllamaMessages**
502+
503+Find line ~297 (`toOllamaMessages` function) and add comment:
504+
505+```go
506+// toOllamaMessages converts provider messages to Ollama's custom request format.
507+//
508+// OLLAMA-SPECIFIC: Uses custom ollamaReqMessage type instead of OpenAI SDK types.
509+// Ollama has its own message format and tool call structure.
510+func toOllamaMessages(messages []Message) []ollamaReqMessage {
511+ // ... existing implementation
512+}
513+```
514+
515+**Step 3: Add comment to custom types**
516+
517+Find line ~148 (custom Ollama types) and add header comment:
518+
519+```go
520+// OLLAMA-SPECIFIC TYPES
521+// These types are custom to Ollama and should NOT be used by other providers.
522+// They differ from OpenAI standard in structure and field names.
523+
524+type ollamaChatRequest struct {
525+ // ... existing implementation
526+}
527+```
528+
529+**Step 4: Find and document reasoning() method**
530+
531+Find the `reasoning()` method (around line 184) and add comment:
532+
533+```go
534+// reasoning extracts reasoning content from Ollama response.
535+//
536+// OLLAMA-SPECIFIC: Ollama may return reasoning in either "reasoning" or "reasoning_content" fields.
537+// This is an Ollama extension not present in standard OpenAI Chat Completions API.
538+func (m *chatCompletionMessage) reasoning() string {
539+ // ... existing implementation
540+}
541+```
542+
543+**Step 5: Verify Ollama doesn't use OpenAI common functions**
544+
545+Search `ollama.go` for:
546+- `toOpenAIMessages` - should NOT be present
547+- `mergeSystemMessagesOpenAI` - should NOT be present
548+- `toOpenAITools` - should NOT be present
549+
550+If any of these are found, they should be replaced with Ollama-specific equivalents.
551+
552+Expected: Ollama only uses its own `toOllamaMessages`, `toOllamaTools`, and `mergeConsecutiveSystemMessagesOllama`.
553+
554+**Step 6: Run tests**
555+
556+Run: `cd internal/provider && go build`
557+Expected: Compiles successfully
558+
559+**Step 7: Commit**
560+
561+```bash
562+git add internal/provider/ollama.go
563+git commit -m "docs(provider): document Ollama-specific customizations
564+
565+- Mark mergeConsecutiveSystemMessagesOllama as Ollama-only
566+- Document Ollama's flexible system message handling
567+- Mark custom types as Ollama-specific
568+- Mark reasoning() method as Ollama extension
569+- Clarify that Ollama code should not be used for OpenAI providers"
570+```
571+
572+---
573+
574+## Phase 4: Add Message Validation for OpenAI Compliance
575+
576+### Task 4.1: Add orphaned tool message detection
577+
578+**Files:**
579+- Modify: `internal/core/mysis.go`
580+
581+**Step 1: Add helper to detect valid tool call IDs**
582+
583+Find the end of the file (before the last closing brace) and add:
584+
585+```go
586+// collectValidToolCallIDs extracts all tool call IDs from assistant messages.
587+// Used to validate that tool result messages reference existing tool calls.
588+func (m *Mysis) collectValidToolCallIDs(memories []*store.Memory) map[string]bool {
589+ validToolCalls := make(map[string]bool)
590+
591+ for _, mem := range memories {
592+ if mem.Role == store.MemoryRoleAssistant &&
593+ strings.HasPrefix(mem.Content, constants.ToolCallStoragePrefix) {
594+ calls := m.parseStoredToolCalls(mem.Content)
595+ for _, call := range calls {
596+ validToolCalls[call.ID] = true
597+ }
598+ }
599+ }
600+
601+ return validToolCalls
602+}
603+```
604+
605+**Step 2: Add orphaned tool message removal function**
606+
607+Add after the function above:
608+
609+```go
610+// removeOrphanedToolMessages removes tool result messages that don't have
611+// a corresponding assistant tool call message. This can happen due to:
612+// 1. Context window cutting off tool calls but keeping results
613+// 2. Context compaction removing tool call messages
614+//
615+// OpenAI Chat Completions API requires tool results to reference valid tool calls.
616+func (m *Mysis) removeOrphanedToolMessages(memories []*store.Memory) []*store.Memory {
617+ validToolCalls := m.collectValidToolCallIDs(memories)
618+
619+ result := make([]*store.Memory, 0, len(memories))
620+ for _, mem := range memories {
621+ // Check if this is a tool result message
622+ if mem.Role == store.MemoryRoleTool {
623+ idx := strings.Index(mem.Content, constants.ToolCallStorageFieldDelimiter)
624+ if idx > 0 {
625+ toolCallID := mem.Content[:idx]
626+ if !validToolCalls[toolCallID] {
627+ log.Debug().
628+ Str("tool_call_id", toolCallID).
629+ Msg("Removing orphaned tool result - no matching tool call")
630+ continue // Skip orphaned result
631+ }
632+ } else {
633+ // Malformed tool result - skip it
634+ log.Warn().
635+ Str("content", mem.Content).
636+ Msg("Skipping malformed tool result")
637+ continue
638+ }
639+ }
640+ result = append(result, mem)
641+ }
642+
643+ if len(result) < len(memories) {
644+ log.Debug().
645+ Int("removed", len(memories)-len(result)).
646+ Int("original", len(memories)).
647+ Int("final", len(result)).
648+ Msg("Removed orphaned tool messages for OpenAI compliance")
649+ }
650+
651+ return result
652+}
653+```
654+
655+**Step 3: Update getContextMemories to use orphan removal**
656+
657+Find the `getContextMemories` function (around line 890) and add the orphan removal call:
658+
659+Find this section:
660+```go
661+ // Apply compaction to remove redundant snapshot tool results
662+ compacted := a.compactSnapshots(recent)
663+
664+ // Always try to fetch the system prompt and prepend it if not already first
665+ system, err := a.store.GetSystemMemory(a.id)
666+```
667+
668+Replace with:
669+```go
670+ // Apply compaction to remove redundant snapshot tool results
671+ compacted := a.compactSnapshots(recent)
672+
673+ // Remove orphaned tool messages (results without corresponding tool calls)
674+ // This ensures OpenAI Chat Completions API compliance
675+ compacted = a.removeOrphanedToolMessages(compacted)
676+
677+ // Always try to fetch the system prompt and prepend it if not already first
678+ system, err := a.store.GetSystemMemory(a.id)
679+```
680+
681+**Step 4: Run tests**
682+
683+Run: `make test`
684+Expected: All tests pass
685+
686+**Step 5: Commit**
687+
688+```bash
689+git add internal/core/mysis.go
690+git commit -m "feat(core): add orphaned tool message removal for OpenAI compliance
691+
692+- Add collectValidToolCallIDs helper
693+- Add removeOrphanedToolMessages function
694+- Call orphan removal in getContextMemories
695+- Prevents tool results without matching tool calls
696+- Ensures OpenAI Chat Completions API compliance"
697+```
698+
699+---
700+
701+## Phase 5: Add Tool Call Validation
702+
703+### Task 5.1: Validate tool message format in memoriesToMessages
704+
705+**Files:**
706+- Modify: `internal/core/mysis.go`
707+
708+**Step 1: Update tool message handling with validation**
709+
710+Find the tool role handling in `memoriesToMessages` (around line 678):
711+
712+```go
713+ if m.Role == store.MemoryRoleTool {
714+ if idx := strings.Index(m.Content, constants.ToolCallStorageFieldDelimiter); idx > 0 {
715+ msg.ToolCallID = m.Content[:idx]
716+ msg.Content = m.Content[idx+1:]
717+ }
718+ }
719+```
720+
721+Replace with:
722+```go
723+ if m.Role == store.MemoryRoleTool {
724+ idx := strings.Index(m.Content, constants.ToolCallStorageFieldDelimiter)
725+ if idx <= 0 {
726+ log.Warn().
727+ Str("content", m.Content).
728+ Msg("Skipping malformed tool result - missing delimiter")
729+ continue // Skip this message
730+ }
731+ toolCallID := m.Content[:idx]
732+ if toolCallID == "" {
733+ log.Warn().
734+ Str("content", m.Content).
735+ Msg("Skipping tool result with empty tool_call_id")
736+ continue // Skip this message
737+ }
738+ msg.ToolCallID = toolCallID
739+ msg.Content = m.Content[idx+1:]
740+ }
741+```
742+
743+**Step 2: Update assistant tool call handling with validation**
744+
745+Find assistant tool call handling (around line 688):
746+
747+```go
748+ if m.Role == store.MemoryRoleAssistant && strings.HasPrefix(m.Content, constants.ToolCallStoragePrefix) {
749+ msg.ToolCalls = a.parseStoredToolCalls(m.Content)
750+ msg.Content = ""
751+ }
752+```
753+
754+Replace with:
755+```go
756+ if m.Role == store.MemoryRoleAssistant && strings.HasPrefix(m.Content, constants.ToolCallStoragePrefix) {
757+ msg.ToolCalls = a.parseStoredToolCalls(m.Content)
758+ if len(msg.ToolCalls) > 0 {
759+ msg.Content = "" // Only clear content if tool calls were parsed successfully
760+ } else {
761+ log.Warn().
762+ Str("content", m.Content).
763+ Msg("Failed to parse tool calls from assistant message - keeping original content")
764+ // Keep original content as fallback
765+ }
766+ }
767+```
768+
769+**Step 3: Add JSON validation to parseStoredToolCalls**
770+
771+Find `parseStoredToolCalls` function (around line 770) and update:
772+
773+Find the section where tool calls are built:
774+```go
775+ calls = append(calls, provider.ToolCall{
776+ ID: fields[0],
777+ Name: fields[1],
778+ Arguments: json.RawMessage(fields[2]),
779+ })
780+```
781+
782+Replace with:
783+```go
784+ args := json.RawMessage(fields[2])
785+ if !json.Valid(args) {
786+ log.Warn().
787+ Str("tool_call_id", fields[0]).
788+ Str("tool_name", fields[1]).
789+ Msg("Invalid JSON in tool call arguments - using empty object")
790+ args = json.RawMessage("{}")
791+ }
792+ calls = append(calls, provider.ToolCall{
793+ ID: fields[0],
794+ Name: fields[1],
795+ Arguments: args,
796+ })
797+```
798+
799+**Step 4: Run tests**
800+
801+Run: `make test`
802+Expected: All tests pass
803+
804+**Step 5: Commit**
805+
806+```bash
807+git add internal/core/mysis.go
808+git commit -m "feat(core): add tool call and tool result validation
809+
810+- Validate tool result delimiter and tool_call_id presence
811+- Skip malformed tool result messages
812+- Validate assistant tool call parsing
813+- Keep original content if tool call parsing fails
814+- Add JSON validation for tool call arguments
815+- Ensures OpenAI Chat Completions API compliance"
816+```
817+
818+---
819+
820+## Phase 6: Update Documentation
821+
822+### Task 6.1: Document OpenAI compliance requirements
823+
824+**Files:**
825+- Create: `documentation/architecture/OPENAI_COMPATIBILITY.md`
826+
827+**Step 1: Create documentation file**
828+
829+```markdown
830+# OpenAI Chat Completions API Compatibility
831+
832+This document describes how Zoea Nova maintains compatibility with the OpenAI Chat Completions API specification for all OpenAI-compatible providers.
833+
834+## Architecture Principles
835+
836+1. **OpenAI Compliance First**: All OpenAI-compatible providers (OpenCode Zen, etc.) MUST follow strict OpenAI Chat Completions API spec
837+2. **Ollama Isolation**: Ollama-specific customizations stay in `ollama.go` and are NOT used by other providers
838+3. **Shared OpenAI Types**: Common OpenAI-compliant code lives in `openai_common.go`
839+
840+## Provider Types
841+
842+### OpenAI-Compatible Providers
843+- **OpenCode Zen**: Strict OpenAI compliance
844+- **Future providers**: Any provider following OpenAI Chat Completions API
845+
846+These providers use:
847+- `openai_common.go` types and functions
848+- `mergeSystemMessagesOpenAI()` for system message handling
849+- OpenAI SDK types (`openai.ChatCompletionRequest`, etc.)
850+
851+### Ollama Provider
852+- **Ollama**: Custom provider with flexible API
853+
854+Uses Ollama-specific code:
855+- Custom types (`ollamaReqMessage`, `chatCompletionResponse`, etc.)
856+- `mergeConsecutiveSystemMessagesOllama()` for flexible system handling
857+- Custom `reasoning()` method for Ollama extensions
858+
859+## OpenAI Chat Completions API Requirements
860+
861+### Message Ordering
862+1. System messages MUST be first
863+2. User and assistant messages should alternate
864+3. Tool result messages MUST follow assistant messages with tool calls
865+4. At least one non-system message MUST be present
866+
867+### Tool Calls
868+1. Tool calls must have unique IDs
869+2. Tool results must reference valid tool call IDs
870+3. Tool arguments must be valid JSON
871+4. Tool results must follow the corresponding tool call message
872+
873+### Validation Rules
874+- Empty tool_call_id → skip message
875+- Orphaned tool results (no matching tool call) → remove message
876+- Invalid JSON in tool arguments → use empty object `{}`
877+- Only system messages → add fallback user message "Begin."
878+
879+## Code Structure
880+
881+```
882+internal/provider/
883+├── openai_common.go # Shared OpenAI-compliant code
884+│ ├── toOpenAIMessages()
885+│ ├── mergeSystemMessagesOpenAI()
886+│ └── toOpenAITools()
887+├── opencode.go # OpenCode Zen (uses openai_common.go)
888+└── ollama.go # Ollama (isolated, custom types)
889+ ├── toOllamaMessages()
890+ ├── mergeConsecutiveSystemMessagesOllama()
891+ └── reasoning() method
892+```
893+
894+## Adding New OpenAI-Compatible Providers
895+
896+To add a new OpenAI-compatible provider:
897+
898+1. Create `internal/provider/<provider>.go`
899+2. Import and use `openai_common.go` functions:
900+ - `toOpenAIMessages()`
901+ - `mergeSystemMessagesOpenAI()`
902+ - `toOpenAITools()`
903+3. Use OpenAI SDK types for requests
904+4. Use `openaiChatResponse` types for responses
905+5. DO NOT use Ollama-specific code
906+6. Test against actual OpenAI API if possible
907+
908+## Testing OpenAI Compliance
909+
910+All OpenAI-compatible providers must pass:
911+- Message ordering validation tests
912+- Tool call/result association tests
913+- System message merging tests
914+- Edge case handling (orphaned tools, malformed data, etc.)
915+
916+See `internal/provider/provider_test.go` for test patterns.
917+
918+## References
919+
920+- [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat/create)
921+- `documentation/guides/OPENCODE_ZEN_MODELS.md`
922+```
923+
924+**Step 2: Commit**
925+
926+```bash
927+git add documentation/architecture/OPENAI_COMPATIBILITY.md
928+git commit -m "docs: add OpenAI Chat Completions API compatibility guide
929+
930+- Document architecture principles (OpenAI compliance first)
931+- Explain provider separation (OpenAI-compatible vs Ollama)
932+- List OpenAI API requirements (message ordering, tool calls)
933+- Document validation rules and code structure
934+- Provide guide for adding new OpenAI-compatible providers"
935+```
936+
937+---
938+
939+## Phase 7: Update AGENTS.md
940+
941+### Task 7.1: Add provider architecture notes
942+
943+**Files:**
944+- Modify: `AGENTS.md`
945+
946+**Step 1: Add Provider Architecture section**
947+
948+Find the `## Architecture` section and add after the diagram:
949+
950+```markdown
951+## Provider Architecture
952+
953+Zoea Nova supports two types of LLM providers:
954+
955+### OpenAI-Compatible Providers
956+Providers that follow the [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat/create) specification.
957+
958+**Examples:** OpenCode Zen, OpenAI, Azure OpenAI, Together AI, etc.
959+
960+**Implementation:**
961+- Use shared code in `internal/provider/openai_common.go`
962+- Strict message ordering (system first, alternating user/assistant)
963+- Tool call validation and orphaned message removal
964+- Fallback user message if only system messages exist
965+
966+**Location:** `internal/provider/opencode.go` (reference implementation)
967+
968+### Ollama Provider
969+Custom provider with flexible API that differs from OpenAI standard.
970+
971+**Ollama-Specific Behavior:**
972+- System messages allowed anywhere (not just first)
973+- Custom response types with `reasoning()` method
974+- Flexible message ordering
975+
976+**Implementation:**
977+- Isolated in `internal/provider/ollama.go`
978+- Uses custom types (`ollamaReqMessage`, `chatCompletionResponse`, etc.)
979+- Custom message merging (`mergeConsecutiveSystemMessagesOllama`)
980+- **DO NOT** use Ollama code for OpenAI-compatible providers
981+
982+**Location:** `internal/provider/ollama.go`
983+
984+### Key Files
985+- `internal/provider/openai_common.go` - Shared OpenAI-compliant code (use for new OpenAI-compatible providers)
986+- `internal/provider/opencode.go` - OpenCode Zen implementation (OpenAI-compatible reference)
987+- `internal/provider/ollama.go` - Ollama implementation (isolated, custom)
988+- `documentation/architecture/OPENAI_COMPATIBILITY.md` - Full compatibility guide
989+
990+### Adding New Providers
991+- **OpenAI-compatible:** Use `openai_common.go` functions, follow OpenCode pattern
992+- **Custom API:** Create isolated implementation like Ollama, document differences
993+```
994+
995+**Step 2: Commit**
996+
997+```bash
998+git add AGENTS.md
999+git commit -m "docs(agents): add provider architecture documentation
Cut short: this commit's diff is over 1000 lines.