feat: add configurable AgentRouter AI provider

internal/aiprovider/agentrouter.go

@@ -0,0 +1,145 @@
+package aiprovider
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+const maxAgentRouterRequestTimeout = 90 * time.Second
+
+const agentRouterUserAgent = "claude-cli/1.0.0 (external, cli)"
+
+type AgentRouterClient struct {
+	config Config
+	client *http.Client
+}
+
+var _ Generator = (*AgentRouterClient)(nil)
+
+func NewAgentRouter(config Config, client *http.Client) *AgentRouterClient {
+	if config.BaseURL == "" {
+		config.BaseURL = "https://agentrouter.org/v1"
+	}
+	config.BaseURL = strings.TrimRight(config.BaseURL, "/")
+	if !strings.HasSuffix(config.BaseURL, "/v1") {
+		config.BaseURL += "/v1"
+	}
+	if config.Timeout <= 0 || config.Timeout > maxAgentRouterRequestTimeout {
+		config.Timeout = maxAgentRouterRequestTimeout
+	}
+	if client == nil {
+		client = &http.Client{}
+	}
+	return &AgentRouterClient{config: config, client: client}
+}
+
+func (c *AgentRouterClient) Model() string { return c.config.Model }
+
+func (c *AgentRouterClient) Generate(ctx context.Context, request Request) (json.RawMessage, Usage, error) {
+	if c.config.APIKey == "" || c.config.Model == "" {
+		return nil, Usage{}, errors.New("agentrouter: disabled")
+	}
+	if request.MaxOutputTokens <= 0 {
+		request.MaxOutputTokens = 1600
+	}
+	body := map[string]any{
+		"model":               c.config.Model,
+		"messages":            []map[string]any{{"role": "system", "content": request.Instructions}, {"role": "user", "content": string(request.Input)}},
+		"max_tokens":          request.MaxOutputTokens,
+		"reasoning_effort":    "medium",
+		"parallel_tool_calls": false,
+		"response_format": map[string]any{
+			"type":        "json_schema",
+			"json_schema": map[string]any{"name": request.SchemaName, "strict": true, "schema": request.Schema},
+		},
+	}
+	var total Usage
+	var last error
+	for attempt := 0; attempt < 2; attempt++ {
+		output, usage, transient, err := c.do(ctx, body)
+		total = mergeUsage(total, usage)
+		if err == nil {
+			return output, total, nil
+		}
+		last = err
+		if !transient || ctx.Err() != nil {
+			break
+		}
+	}
+	return nil, total, last
+}
+
+type agentRouterEnvelope struct {
+	ID      string `json:"id"`
+	Choices []struct {
+		FinishReason string `json:"finish_reason"`
+		Message      struct {
+			Content string `json:"content"`
+			Refusal string `json:"refusal"`
+		} `json:"message"`
+	} `json:"choices"`
+	Usage struct {
+		PromptTokens     int64 `json:"prompt_tokens"`
+		CompletionTokens int64 `json:"completion_tokens"`
+	} `json:"usage"`
+}
+
+func (c *AgentRouterClient) do(parent context.Context, value map[string]any) (json.RawMessage, Usage, bool, error) {
+	body, err := json.Marshal(value)
+	if err != nil {
+		return nil, Usage{}, false, fmt.Errorf("encoding agentrouter request: %w", err)
+	}
+	ctx, cancel := context.WithTimeout(parent, c.config.Timeout)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.config.BaseURL+"/chat/completions", bytes.NewReader(body))
+	if err != nil {
+		return nil, Usage{}, false, fmt.Errorf("creating agentrouter request: %w", err)
+	}
+	req.Header.Set("Authorization", "Bearer "+c.config.APIKey)
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("User-Agent", agentRouterUserAgent)
+	started := time.Now()
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, Usage{ProviderRequests: 1, LatencyMS: time.Since(started).Milliseconds()}, true, fmt.Errorf("calling agentrouter: %w", err)
+	}
+	defer resp.Body.Close()
+	responseBody, readErr := io.ReadAll(io.LimitReader(resp.Body, maxResponseBytes+1))
+	usage := Usage{ProviderRequests: 1, LatencyMS: time.Since(started).Milliseconds(), ProviderRequestID: resp.Header.Get("X-Request-ID")}
+	if readErr != nil {
+		return nil, usage, true, fmt.Errorf("reading agentrouter response: %w", readErr)
+	}
+	if len(responseBody) > maxResponseBytes {
+		return nil, usage, false, errors.New("agentrouter: response too large")
+	}
+	var result agentRouterEnvelope
+	decodeErr := json.Unmarshal(responseBody, &result)
+	usage.InputTokens, usage.OutputTokens = result.Usage.PromptTokens, result.Usage.CompletionTokens
+	if usage.ProviderRequestID == "" {
+		usage.ProviderRequestID = result.ID
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, usage, resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= 500, fmt.Errorf("agentrouter: http %d", resp.StatusCode)
+	}
+	if decodeErr != nil {
+		return nil, usage, false, fmt.Errorf("decoding agentrouter response: %w", decodeErr)
+	}
+	if len(result.Choices) != 1 || result.Choices[0].FinishReason != "stop" {
+		return nil, usage, false, errors.New("agentrouter: incomplete chat completion")
+	}
+	message := result.Choices[0].Message
+	if message.Refusal != "" {
+		return nil, usage, false, errors.New("agentrouter: refused")
+	}
+	if !json.Valid([]byte(message.Content)) {
+		return nil, usage, false, errors.New("agentrouter: invalid structured output")
+	}
+	return json.RawMessage(message.Content), usage, false, nil
+}

internal/aiprovider/agentrouter_smoke_test.go

@@ -0,0 +1,45 @@
+package aiprovider
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"os"
+	"testing"
+	"time"
+)
+
+func TestAgentRouterSmoke(t *testing.T) {
+	if os.Getenv("AGENTROUTER_SMOKE") != "1" {
+		t.Skip("set AGENTROUTER_SMOKE=1 to run the real provider contract")
+	}
+	client := NewAgentRouter(Config{
+		BaseURL: os.Getenv("AGENTROUTER_BASE_URL"),
+		APIKey:  os.Getenv("AGENTROUTER_API_KEY"),
+		Model:   os.Getenv("AGENTROUTER_MODEL"),
+		Timeout: 30 * time.Second,
+	}, &http.Client{})
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	result, _, err := client.Generate(ctx, Request{
+		SchemaName: "health",
+		Schema: map[string]any{
+			"type":                 "object",
+			"properties":           map[string]any{"ok": map[string]any{"type": "boolean"}},
+			"required":             []string{"ok"},
+			"additionalProperties": false,
+		},
+		Instructions:    "Return a structured health response.",
+		Input:           json.RawMessage(`{"healthCheck":true}`),
+		MaxOutputTokens: 64,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var response struct {
+		OK bool `json:"ok"`
+	}
+	if json.Unmarshal(result, &response) != nil || !response.OK {
+		t.Fatalf("unexpected provider response: %s", result)
+	}
+}

internal/aiprovider/agentrouter_test.go

@@ -0,0 +1,51 @@
+package aiprovider
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+func TestAgentRouterUsesChatCompletionsContract(t *testing.T) {
+	var received map[string]any
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/chat/completions" {
+			t.Fatalf("path = %q", r.URL.Path)
+		}
+		if r.Header.Get("Authorization") != "Bearer test-key" {
+			t.Fatal("authorization header missing")
+		}
+		if r.Header.Get("User-Agent") != agentRouterUserAgent {
+			t.Fatalf("user-agent = %q", r.Header.Get("User-Agent"))
+		}
+		if err := json.NewDecoder(r.Body).Decode(&received); err != nil {
+			t.Fatal(err)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"id":"chat-1","choices":[{"finish_reason":"stop","message":{"role":"assistant","content":"{\"answer\":\"ok\"}"}}],"usage":{"prompt_tokens":12,"completion_tokens":4}}`))
+	}))
+	defer server.Close()
+
+	client := NewAgentRouter(Config{BaseURL: server.URL, APIKey: "test-key", Model: "gpt-test", Timeout: time.Second}, server.Client())
+	var generator Generator = client
+	result, usage, err := generator.Generate(context.Background(), Request{
+		SchemaName: "answer", Schema: map[string]any{"type": "object", "additionalProperties": false},
+		Instructions: "system rules", Input: json.RawMessage(`{"safe":"aggregate"}`), MaxOutputTokens: 200,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(result) != `{"answer":"ok"}` || usage.ProviderRequestID != "chat-1" || usage.InputTokens != 12 || usage.OutputTokens != 4 {
+		t.Fatalf("result=%s usage=%+v", result, usage)
+	}
+	if received["model"] != "gpt-test" || received["reasoning_effort"] != "medium" || received["parallel_tool_calls"] != false || received["max_tokens"] != float64(200) {
+		t.Fatalf("request controls = %#v", received)
+	}
+	format := received["response_format"].(map[string]any)
+	if format["type"] != "json_schema" {
+		t.Fatalf("response_format = %#v", format)
+	}
+}

internal/aiprovider/client.go

@@ -38,11 +38,18 @@ type Usage struct {
 	EstimatedCost     string
 }
 
+type Generator interface {
+	Model() string
+	Generate(context.Context, Request) (json.RawMessage, Usage, error)
+}
+
 type Client struct {
 	config Config
 	client *http.Client
 }
 
+var _ Generator = (*Client)(nil)
+
 func New(config Config, client *http.Client) *Client {
 	if config.BaseURL == "" {
 		config.BaseURL = "https://api.avalai.ir"