refactor: restructure project layout — main.go to root, llm+config to pkg/

- Move cmd/agentu/main.go → main.go (project root)
- Move internal/llm/ → pkg/llm/ (leaf package, no internal deps)
- Move internal/config/ → pkg/config/ (leaf package, no internal deps)
- Update all import paths: agentu/internal/llm → agentu/pkg/llm (14 files)
- Update all import paths: agentu/internal/config → agentu/pkg/config (3 files)
- Update README: build/run commands, CLI flags section
- agent/session/tools/tui stay in internal/ (app-specific business logic)

Build: go build . | Test: go test ./... | Vet: go vet ./...

pkg/config/config.go

@@ -0,0 +1,285 @@
+package config
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"gopkg.in/yaml.v3"
+)
+
+const DefaultPath = "~/.agentu/config.yaml"
+
+type Config struct {
+	Providers map[string]ProviderConfig `yaml:"providers"`
+	Agent     AgentConfig               `yaml:"agent"`
+}
+
+type ProviderConfig struct {
+	Name               string
+	BaseURL            string
+	Model              string
+	Models             []string
+	ModelConfigs       map[string]ModelConfig
+	ContextTokens      int
+	APIKey             string
+	Thinking           string
+	ThinkingParam      string
+	ThinkingConfigured bool
+}
+
+type ModelConfig struct {
+	ID            string `yaml:"id"`
+	Thinking      string `yaml:"thinking"`
+	ContextTokens int    `yaml:"context"`
+}
+
+type AgentConfig struct {
+	SystemPrompt     string        `yaml:"system_prompt"`
+	WorkingDir       string        `yaml:"working_dir"`
+	ToolTimeout      time.Duration `yaml:"tool_timeout"`
+	MaxContextTokens int           `yaml:"max_context_tokens"`
+}
+
+type rawConfig struct {
+	Providers map[string]rawProviderConfig `yaml:"providers"`
+	Agent     struct {
+		SystemPrompt     string `yaml:"system_prompt"`
+		WorkingDir       string `yaml:"working_dir"`
+		ToolTimeout      string `yaml:"tool_timeout"`
+		MaxContextTokens int    `yaml:"max_context_tokens"`
+	} `yaml:"agent"`
+}
+
+type rawProviderConfig struct {
+	BaseURL string           `yaml:"base_url"`
+	Models  []rawModelConfig `yaml:"models"`
+	APIKey  string           `yaml:"api_key"`
+}
+
+type rawModelConfig struct {
+	ID            string `yaml:"id"`
+	Thinking      string `yaml:"thinking"`
+	ContextTokens int    `yaml:"context"`
+}
+
+func Load(path string) (*Config, error) {
+	path, err := ResolvePath(path)
+	if err != nil {
+		return nil, err
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read config: %w", err)
+	}
+
+	expanded := os.ExpandEnv(string(data))
+	var raw rawConfig
+	decoder := yaml.NewDecoder(strings.NewReader(expanded))
+	decoder.KnownFields(true)
+	if err := decoder.Decode(&raw); err != nil {
+		return nil, fmt.Errorf("parse config: %w", err)
+	}
+
+	cfg := &Config{
+		Providers: normalizeProviders(raw),
+		Agent: AgentConfig{
+			SystemPrompt:     raw.Agent.SystemPrompt,
+			WorkingDir:       raw.Agent.WorkingDir,
+			MaxContextTokens: raw.Agent.MaxContextTokens,
+		},
+	}
+
+	if cfg.Agent.WorkingDir == "" {
+		cfg.Agent.WorkingDir = "."
+	}
+	absWorkingDir, err := filepath.Abs(cfg.Agent.WorkingDir)
+	if err != nil {
+		return nil, fmt.Errorf("resolve working_dir: %w", err)
+	}
+	cfg.Agent.WorkingDir = absWorkingDir
+
+	if raw.Agent.ToolTimeout == "" {
+		cfg.Agent.ToolTimeout = 30 * time.Second
+	} else {
+		timeout, err := time.ParseDuration(raw.Agent.ToolTimeout)
+		if err != nil {
+			return nil, fmt.Errorf("parse agent.tool_timeout: %w", err)
+		}
+		cfg.Agent.ToolTimeout = timeout
+	}
+
+	if cfg.Agent.SystemPrompt == "" {
+		cfg.Agent.SystemPrompt = "You are agentu, a concise local agent. Answer simple conversation directly. Use tools only when the user's request needs local project context or local command execution."
+	}
+
+	if err := cfg.Validate(); err != nil {
+		return nil, err
+	}
+
+	return cfg, nil
+}
+
+func ResolvePath(path string) (string, error) {
+	if strings.TrimSpace(path) == "" {
+		path = DefaultPath
+	}
+	if path == "~" {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("resolve home dir: %w", err)
+		}
+		return home, nil
+	}
+	if strings.HasPrefix(path, "~/") {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("resolve home dir: %w", err)
+		}
+		return filepath.Join(home, strings.TrimPrefix(path, "~/")), nil
+	}
+	return path, nil
+}
+
+func (c *Config) Validate() error {
+	if len(c.Providers) == 0 {
+		return errors.New("missing required config: providers")
+	}
+	for name, provider := range c.Providers {
+		var missing []string
+		prefix := "providers." + name
+		if strings.TrimSpace(provider.BaseURL) == "" {
+			missing = append(missing, prefix+".base_url")
+		}
+		if len(provider.Models) == 0 {
+			missing = append(missing, prefix+".models")
+		}
+		if strings.TrimSpace(provider.APIKey) == "" {
+			missing = append(missing, prefix+".api_key")
+		}
+		if len(missing) > 0 {
+			return fmt.Errorf("missing required config: %s", strings.Join(missing, ", "))
+		}
+		for _, model := range provider.Models {
+			if strings.TrimSpace(model) == "" {
+				return fmt.Errorf("%s.models.id is required", prefix)
+			}
+		}
+		for _, model := range provider.ModelConfigs {
+			if model.ContextTokens < 0 {
+				return fmt.Errorf("%s.models.context must be greater than or equal to zero", prefix)
+			}
+			if model.Thinking != "" && !IsThinkingLevel(model.Thinking) {
+				return fmt.Errorf("%s.models.thinking must be one of: %s", prefix, strings.Join(ThinkingLevels(), ", "))
+			}
+		}
+		if provider.ThinkingConfigured && !IsThinkingLevel(provider.Thinking) {
+			return fmt.Errorf("%s.thinking must be one of: %s", prefix, strings.Join(ThinkingLevels(), ", "))
+		}
+	}
+	if c.Agent.ToolTimeout <= 0 {
+		return errors.New("agent.tool_timeout must be greater than zero")
+	}
+	if c.Agent.MaxContextTokens < 0 {
+		return errors.New("agent.max_context_tokens must be greater than or equal to zero")
+	}
+	return nil
+}
+
+func (c *Config) DefaultProviderName() string {
+	names := c.ProviderNames()
+	if len(names) == 0 {
+		return ""
+	}
+	return names[0]
+}
+
+func (c *Config) ProviderNames() []string {
+	names := make([]string, 0, len(c.Providers))
+	for name := range c.Providers {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+func normalizeProviders(raw rawConfig) map[string]ProviderConfig {
+	providers := make(map[string]ProviderConfig)
+	for name, provider := range raw.Providers {
+		providers[name] = normalizeProvider(name, provider)
+	}
+	return providers
+}
+
+func normalizeProvider(name string, raw rawProviderConfig) ProviderConfig {
+	models, modelConfigs := normalizeModelConfigs(raw.Models)
+	provider := ProviderConfig{
+		Name:         name,
+		BaseURL:      raw.BaseURL,
+		Models:       models,
+		ModelConfigs: modelConfigs,
+		APIKey:       raw.APIKey,
+	}
+	if len(provider.Models) > 0 {
+		provider.Model = provider.Models[0]
+	}
+	applyModelDefaults(&provider)
+	if provider.ThinkingConfigured && provider.ThinkingParam == "" {
+		provider.ThinkingParam = "thinking"
+	}
+	return provider
+}
+
+func normalizeModelConfigs(rawModels []rawModelConfig) ([]string, map[string]ModelConfig) {
+	models := make([]string, 0, len(rawModels))
+	configs := make(map[string]ModelConfig, len(rawModels))
+	for _, raw := range rawModels {
+		model := ModelConfig{
+			ID:            strings.TrimSpace(raw.ID),
+			Thinking:      strings.ToLower(strings.TrimSpace(raw.Thinking)),
+			ContextTokens: raw.ContextTokens,
+		}
+		models = append(models, model.ID)
+		if model.ID != "" {
+			configs[model.ID] = model
+		}
+	}
+	return models, configs
+}
+
+func applyModelDefaults(provider *ProviderConfig) {
+	model, ok := provider.ModelConfigs[provider.Model]
+	if !ok {
+		return
+	}
+	provider.ContextTokens = model.ContextTokens
+	if model.Thinking != "" {
+		provider.Thinking = model.Thinking
+		provider.ThinkingConfigured = true
+	}
+}
+
+func (p ProviderConfig) WithModel(model string) ProviderConfig {
+	p.Model = strings.TrimSpace(model)
+	applyModelDefaults(&p)
+	return p
+}
+
+func ThinkingLevels() []string {
+	return []string{"none", "middle", "high", "xhigh", "max"}
+}
+
+func IsThinkingLevel(value string) bool {
+	value = strings.ToLower(strings.TrimSpace(value))
+	for _, level := range ThinkingLevels() {
+		if value == level {
+			return true
+		}
+	}
+	return false
+}

pkg/config/config_test.go

@@ -0,0 +1,372 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestLoadExpandsEnvAndDefaults(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("AGENTU_TEST_KEY", "sk-test")
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  test:
+    base_url: https://example.com
+    api_key: ${AGENTU_TEST_KEY}
+    models:
+      - id: test-model
+agent:
+  working_dir: .
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	provider := cfg.Providers[cfg.DefaultProviderName()]
+	if provider.APIKey != "sk-test" {
+		t.Fatalf("api key = %q", provider.APIKey)
+	}
+	if providerName := cfg.DefaultProviderName(); providerName != "test" {
+		t.Fatalf("default provider = %q", providerName)
+	}
+	if cfg.Agent.ToolTimeout != 30*time.Second {
+		t.Fatalf("tool timeout = %s", cfg.Agent.ToolTimeout)
+	}
+	if !filepath.IsAbs(cfg.Agent.WorkingDir) {
+		t.Fatalf("working dir is not absolute: %s", cfg.Agent.WorkingDir)
+	}
+}
+
+func TestLoadMinimalModelObjectConfig(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("AGENTU_TEST_KEY", "sk-test")
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  test:
+    base_url: https://example.com
+    api_key: ${AGENTU_TEST_KEY}
+    models:
+      - id: model-a
+        thinking: none
+        context: 256000
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	provider := cfg.Providers["test"]
+	if provider.Model != "model-a" {
+		t.Fatalf("model = %q", provider.Model)
+	}
+	if len(provider.Models) != 1 || provider.Models[0] != "model-a" {
+		t.Fatalf("models = %#v", provider.Models)
+	}
+	if provider.ContextTokens != 256000 {
+		t.Fatalf("context tokens = %d", provider.ContextTokens)
+	}
+	if !provider.ThinkingConfigured || provider.Thinking != "none" || provider.ThinkingParam != "thinking" {
+		t.Fatalf("thinking config = %#v", provider)
+	}
+	if cfg.Agent.ToolTimeout != 30*time.Second {
+		t.Fatalf("tool timeout = %s", cfg.Agent.ToolTimeout)
+	}
+	if cfg.Agent.SystemPrompt == "" {
+		t.Fatal("system prompt default was not applied")
+	}
+}
+
+func TestLoadRejectsStringModelEntries(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  test:
+    base_url: https://example.com
+    api_key: sk-test
+    models:
+      - test-model
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := Load(path)
+	if err == nil || !strings.Contains(err.Error(), "cannot unmarshal") {
+		t.Fatalf("err = %v", err)
+	}
+}
+
+func TestLoadMaxContextTokens(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  test:
+    base_url: https://example.com
+    api_key: sk-test
+    models:
+      - id: test-model
+agent:
+  max_context_tokens: 120000
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if cfg.Agent.MaxContextTokens != 120000 {
+		t.Fatalf("max context tokens = %d", cfg.Agent.MaxContextTokens)
+	}
+}
+
+func TestLoadRejectsNegativeMaxContextTokens(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  test:
+    base_url: https://example.com
+    api_key: sk-test
+    models:
+      - id: test-model
+agent:
+  max_context_tokens: -1
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := Load(path)
+	if err == nil || !strings.Contains(err.Error(), "agent.max_context_tokens") {
+		t.Fatalf("err = %v", err)
+	}
+}
+
+func TestLoadUsesDefaultConfigPath(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("HOME", dir)
+	t.Setenv("AGENTU_TEST_KEY", "sk-test")
+	configDir := filepath.Join(dir, ".agentu")
+	if err := os.MkdirAll(configDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(configDir, "config.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  test:
+    base_url: https://example.com
+    api_key: ${AGENTU_TEST_KEY}
+    models:
+      - id: test-model
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := Load("")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := cfg.DefaultProviderName(); got != "test" {
+		t.Fatalf("default provider = %q", got)
+	}
+}
+
+func TestResolvePathExpandsHome(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("HOME", dir)
+
+	got, err := ResolvePath("~/.agentu/config.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := filepath.Join(dir, ".agentu", "config.yaml")
+	if got != want {
+		t.Fatalf("path = %q, want %q", got, want)
+	}
+}
+
+func TestLoadDefaultSystemPromptDiscouragesEagerTools(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("AGENTU_TEST_KEY", "sk-test")
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  test:
+    base_url: https://example.com
+    api_key: ${AGENTU_TEST_KEY}
+    models:
+      - id: test-model
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"Answer simple conversation directly", "Use tools only when"} {
+		if !strings.Contains(cfg.Agent.SystemPrompt, want) {
+			t.Fatalf("system prompt missing %q: %s", want, cfg.Agent.SystemPrompt)
+		}
+	}
+}
+
+func TestLoadMultiProviderConfig(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("AGENTU_TEST_KEY", "sk-test")
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  loveuer:
+    base_url: https://example.com
+    api_key: ${AGENTU_TEST_KEY}
+    models:
+      - id: model-a
+        thinking: xhigh
+      - id: model-b
+  backup:
+    base_url: https://backup.example.com
+    api_key: ${AGENTU_TEST_KEY}
+    models:
+      - id: model-c
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := cfg.DefaultProviderName(); got != "backup" {
+		t.Fatalf("default provider = %q", got)
+	}
+	provider := cfg.Providers["loveuer"]
+	if got := provider.Model; got != "model-a" {
+		t.Fatalf("active model = %q", got)
+	}
+	if got := cfg.Providers["backup"].Model; got != "model-c" {
+		t.Fatalf("backup default model = %q", got)
+	}
+	if !provider.ThinkingConfigured || provider.Thinking != "xhigh" || provider.ThinkingParam != "thinking" {
+		t.Fatalf("thinking config = %#v", provider)
+	}
+}
+
+func TestLoadDefaultProviderNameIsDeterministic(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("AGENTU_TEST_KEY", "sk-test")
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  two:
+    base_url: https://two.example.com
+    api_key: ${AGENTU_TEST_KEY}
+    models:
+      - id: model-b
+  one:
+    base_url: https://one.example.com
+    api_key: ${AGENTU_TEST_KEY}
+    models:
+      - id: model-a
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := Load(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := cfg.DefaultProviderName(); got != "one" {
+		t.Fatalf("default provider = %q", got)
+	}
+}
+
+func TestLoadRejectsInvalidThinking(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("AGENTU_TEST_KEY", "sk-test")
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  test:
+    base_url: https://example.com
+    api_key: ${AGENTU_TEST_KEY}
+    models:
+      - id: test-model
+        thinking: huge
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := Load(path)
+	if err == nil || !strings.Contains(err.Error(), "thinking") {
+		t.Fatalf("err = %v", err)
+	}
+}
+
+func TestLoadRequiresProviderFields(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+providers:
+  test:
+    base_url: https://example.com
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := Load(path)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+}
+
+func TestLoadRejectsLegacyProviderConfig(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+provider:
+  base_url: https://example.com
+  api_key: sk-test
+  models:
+    - id: test-model
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := Load(path)
+	if err == nil || !strings.Contains(err.Error(), "field provider not found") {
+		t.Fatalf("err = %v", err)
+	}
+}
+
+func TestLoadRejectsActiveProviderConfig(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "agentu.yaml")
+	if err := os.WriteFile(path, []byte(`
+active_provider: loveuer
+providers:
+  loveuer:
+    base_url: https://example.com
+    api_key: sk-test
+    models:
+      - id: test-model
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	_, err := Load(path)
+	if err == nil || !strings.Contains(err.Error(), "field active_provider not found") {
+		t.Fatalf("err = %v", err)
+	}
+}

pkg/llm/openai.go

@@ -0,0 +1,202 @@
+package llm
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+const maxChatAttempts = 3
+
+const retryDelay = 100 * time.Millisecond
+
+type OpenAICompatibleClient struct {
+	baseURL    string
+	apiKey     string
+	httpClient *http.Client
+}
+
+func NewOpenAICompatibleClient(baseURL, apiKey string, httpClient *http.Client) *OpenAICompatibleClient {
+	if httpClient == nil {
+		httpClient = http.DefaultClient
+	}
+	return &OpenAICompatibleClient{
+		baseURL:    strings.TrimRight(baseURL, "/"),
+		apiKey:     apiKey,
+		httpClient: httpClient,
+	}
+}
+
+func (c *OpenAICompatibleClient) ChatStream(ctx context.Context, req ChatRequest, emit func(StreamEvent) error) error {
+	req.Stream = true
+	extra := make(map[string]any, len(req.Extra)+1)
+	for key, value := range req.Extra {
+		extra[key] = value
+	}
+	if _, exists := extra["stream_options"]; !exists {
+		extra["stream_options"] = map[string]any{"include_usage": true}
+	}
+	req.Extra = extra
+	body, err := json.Marshal(req)
+	if err != nil {
+		return fmt.Errorf("marshal chat request: %w", err)
+	}
+
+	var lastErr error
+	for attempt := 1; attempt <= maxChatAttempts; attempt++ {
+		httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+"/v1/chat/completions", bytes.NewReader(body))
+		if err != nil {
+			return fmt.Errorf("create chat request: %w", err)
+		}
+		httpReq.Header.Set("Content-Type", "application/json")
+		httpReq.Header.Set("Accept", "text/event-stream")
+		if c.apiKey != "" {
+			httpReq.Header.Set("Authorization", "Bearer "+c.apiKey)
+		}
+
+		resp, err := c.httpClient.Do(httpReq)
+		if err != nil {
+			lastErr = fmt.Errorf("send chat request: %w", err)
+			if !shouldRetryRequest(ctx, attempt, 0) {
+				return lastErr
+			}
+			if waitErr := waitBeforeRetry(ctx); waitErr != nil {
+				return waitErr
+			}
+			continue
+		}
+
+		if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+			limit := io.LimitReader(resp.Body, 4096)
+			data, _ := io.ReadAll(limit)
+			_ = resp.Body.Close()
+			lastErr = fmt.Errorf("chat request failed: status=%d body=%s", resp.StatusCode, strings.TrimSpace(string(data)))
+			if !shouldRetryRequest(ctx, attempt, resp.StatusCode) {
+				return lastErr
+			}
+			if waitErr := waitBeforeRetry(ctx); waitErr != nil {
+				return waitErr
+			}
+			continue
+		}
+
+		defer resp.Body.Close()
+		return readSSE(resp.Body, emit)
+	}
+	return lastErr
+}
+
+func shouldRetryRequest(ctx context.Context, attempt int, status int) bool {
+	if ctx.Err() != nil || attempt >= maxChatAttempts {
+		return false
+	}
+	if status == 0 {
+		return true
+	}
+	return status == http.StatusRequestTimeout || status == http.StatusTooManyRequests || status >= 500
+}
+
+func waitBeforeRetry(ctx context.Context) error {
+	timer := time.NewTimer(retryDelay)
+	defer timer.Stop()
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func readSSE(r io.Reader, emit func(StreamEvent) error) error {
+	reader := bufio.NewReader(r)
+	for {
+		line, err := reader.ReadString('\n')
+		if err != nil && !errors.Is(err, io.EOF) {
+			return fmt.Errorf("read stream: %w", err)
+		}
+
+		line = strings.TrimSpace(line)
+		if strings.HasPrefix(line, "data:") {
+			payload := strings.TrimSpace(strings.TrimPrefix(line, "data:"))
+			if payload == "[DONE]" {
+				return nil
+			}
+			event, parseErr := parseStreamPayload(payload)
+			if parseErr != nil {
+				return parseErr
+			}
+			if event.Content != "" || len(event.ToolCalls) > 0 || event.FinishReason != "" || event.Usage != nil {
+				if emitErr := emit(event); emitErr != nil {
+					return emitErr
+				}
+			}
+		}
+
+		if errors.Is(err, io.EOF) {
+			return nil
+		}
+	}
+}
+
+type streamPayload struct {
+	Choices []struct {
+		Delta struct {
+			Content   string              `json:"content"`
+			ToolCalls []toolCallDeltaJSON `json:"tool_calls"`
+		} `json:"delta"`
+		FinishReason string `json:"finish_reason"`
+	} `json:"choices"`
+	Usage *Usage `json:"usage,omitempty"`
+	Error *struct {
+		Message string `json:"message"`
+		Type    string `json:"type"`
+	} `json:"error,omitempty"`
+}
+
+type toolCallDeltaJSON struct {
+	Index    int    `json:"index"`
+	ID       string `json:"id"`
+	Type     string `json:"type"`
+	Function struct {
+		Name      string `json:"name"`
+		Arguments string `json:"arguments"`
+	} `json:"function"`
+}
+
+func parseStreamPayload(payload string) (StreamEvent, error) {
+	var decoded streamPayload
+	if err := json.Unmarshal([]byte(payload), &decoded); err != nil {
+		return StreamEvent{}, fmt.Errorf("parse stream payload: %w", err)
+	}
+	if decoded.Error != nil {
+		if decoded.Error.Type != "" {
+			return StreamEvent{}, fmt.Errorf("provider error: %s: %s", decoded.Error.Type, decoded.Error.Message)
+		}
+		return StreamEvent{}, fmt.Errorf("provider error: %s", decoded.Error.Message)
+	}
+	event := StreamEvent{Usage: decoded.Usage}
+	if len(decoded.Choices) == 0 {
+		return event, nil
+	}
+
+	choice := decoded.Choices[0]
+	event.Content = choice.Delta.Content
+	event.FinishReason = choice.FinishReason
+	for _, tc := range choice.Delta.ToolCalls {
+		event.ToolCalls = append(event.ToolCalls, ToolCallDelta{
+			Index:     tc.Index,
+			ID:        tc.ID,
+			Type:      tc.Type,
+			Name:      tc.Function.Name,
+			Arguments: tc.Function.Arguments,
+		})
+	}
+	return event, nil
+}

pkg/llm/openai_test.go

@@ -0,0 +1,164 @@
+package llm
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestOpenAICompatibleClientStreamsContentAndToolCalls(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/chat/completions" {
+			t.Fatalf("path = %s", r.URL.Path)
+		}
+		if got := r.Header.Get("Authorization"); got != "Bearer sk-test" {
+			t.Fatalf("authorization = %q", got)
+		}
+		body := mustReadBody(t, r)
+		var raw map[string]any
+		if err := json.NewDecoder(strings.NewReader(body)).Decode(&raw); err != nil {
+			t.Fatal(err)
+		}
+		var req ChatRequest
+		if err := json.NewDecoder(strings.NewReader(body)).Decode(&req); err != nil {
+			t.Fatal(err)
+		}
+		if raw["thinking"] != "high" {
+			t.Fatalf("thinking = %#v", raw["thinking"])
+		}
+		streamOptions, ok := raw["stream_options"].(map[string]any)
+		if !ok || streamOptions["include_usage"] != true {
+			t.Fatalf("stream_options = %#v", raw["stream_options"])
+		}
+		if !req.Stream {
+			t.Fatal("request did not enable stream")
+		}
+		if req.ToolChoice != "auto" && len(req.Tools) > 0 {
+			t.Fatalf("tool_choice = %q", req.ToolChoice)
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		_, _ = w.Write([]byte(`data: {"choices":[{"delta":{"content":"hi "},"finish_reason":""}]}` + "\n\n"))
+		_, _ = w.Write([]byte(`data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_1","type":"function","function":{"name":"file_read","arguments":"{\"path\""}}]},"finish_reason":""}]}` + "\n\n"))
+		_, _ = w.Write([]byte(`data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":":\"README.md\"}"}}]},"finish_reason":"tool_calls"}]}` + "\n\n"))
+		_, _ = w.Write([]byte("data: [DONE]\n\n"))
+	}))
+	defer server.Close()
+
+	client := NewOpenAICompatibleClient(server.URL, "sk-test", server.Client())
+	var content strings.Builder
+	var calls []ToolCallDelta
+	err := client.ChatStream(context.Background(), ChatRequest{Model: "test", Extra: map[string]any{"thinking": "high"}}, func(event StreamEvent) error {
+		content.WriteString(event.Content)
+		calls = append(calls, event.ToolCalls...)
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if content.String() != "hi " {
+		t.Fatalf("content = %q", content.String())
+	}
+	if len(calls) != 2 {
+		t.Fatalf("calls = %#v", calls)
+	}
+	if calls[0].Name != "file_read" || calls[1].Arguments != ":\"README.md\"}" {
+		t.Fatalf("unexpected calls: %#v", calls)
+	}
+}
+
+func TestChatStreamCapturesUsage(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body := mustReadBody(t, r)
+		var raw map[string]any
+		if err := json.NewDecoder(strings.NewReader(body)).Decode(&raw); err != nil {
+			t.Fatal(err)
+		}
+		streamOptions, ok := raw["stream_options"].(map[string]any)
+		if !ok || streamOptions["include_usage"] != true {
+			t.Fatalf("stream_options = %#v", raw["stream_options"])
+		}
+
+		w.Header().Set("Content-Type", "text/event-stream")
+		_, _ = w.Write([]byte(`data: {"choices":[{"delta":{"content":"ok"},"finish_reason":""}]}` + "\n\n"))
+		_, _ = w.Write([]byte(`data: {"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":3,"total_tokens":15}}` + "\n\n"))
+		_, _ = w.Write([]byte("data: [DONE]\n\n"))
+	}))
+	defer server.Close()
+
+	client := NewOpenAICompatibleClient(server.URL, "sk-test", server.Client())
+	var usage *Usage
+	err := client.ChatStream(context.Background(), ChatRequest{Model: "test"}, func(event StreamEvent) error {
+		if event.Usage != nil {
+			usage = event.Usage
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if usage == nil {
+		t.Fatal("usage was not emitted")
+	}
+	if usage.PromptTokens != 12 || usage.CompletionTokens != 3 || usage.TotalTokens != 15 {
+		t.Fatalf("usage = %#v", usage)
+	}
+}
+
+func TestOpenAICompatibleClientRetriesTransientHTTPError(t *testing.T) {
+	attempts := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts == 1 {
+			http.Error(w, "temporary", http.StatusBadGateway)
+			return
+		}
+		w.Header().Set("Content-Type", "text/event-stream")
+		_, _ = w.Write([]byte(`data: {"choices":[{"delta":{"content":"ok"},"finish_reason":""}]}` + "\n\n"))
+		_, _ = w.Write([]byte("data: [DONE]\n\n"))
+	}))
+	defer server.Close()
+
+	client := NewOpenAICompatibleClient(server.URL, "sk-test", server.Client())
+	var content strings.Builder
+	err := client.ChatStream(context.Background(), ChatRequest{Model: "test"}, func(event StreamEvent) error {
+		content.WriteString(event.Content)
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if attempts != 2 {
+		t.Fatalf("attempts = %d, want 2", attempts)
+	}
+	if content.String() != "ok" {
+		t.Fatalf("content = %q", content.String())
+	}
+}
+
+func mustReadBody(t *testing.T, r *http.Request) string {
+	t.Helper()
+	data, err := io.ReadAll(r.Body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(data)
+}
+
+func TestOpenAICompatibleClientHTTPError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, "bad key", http.StatusUnauthorized)
+	}))
+	defer server.Close()
+
+	client := NewOpenAICompatibleClient(server.URL, "sk-test", server.Client())
+	err := client.ChatStream(context.Background(), ChatRequest{Model: "test"}, func(StreamEvent) error {
+		return nil
+	})
+	if err == nil || !strings.Contains(err.Error(), "status=401") {
+		t.Fatalf("err = %v", err)
+	}
+}

pkg/llm/token_estimate.go

@@ -0,0 +1,43 @@
+package llm
+
+import "encoding/json"
+
+const tokenEstimateCharRatio = 4
+
+// EstimateTokens estimates the token cost of messages and tool definitions in a
+// chat completion request. It intentionally uses a simple JSON-size heuristic:
+// roughly four UTF-8 bytes per token plus a small per-message framing overhead.
+func EstimateTokens(messages []Message, tools []Tool) int {
+	if len(messages) == 0 && len(tools) == 0 {
+		return 0
+	}
+
+	payload := struct {
+		Messages []Message `json:"messages,omitempty"`
+		Tools    []Tool    `json:"tools,omitempty"`
+	}{
+		Messages: messages,
+		Tools:    tools,
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return 0
+	}
+
+	return estimateBytesAsTokens(len(data)) + len(messages)*4
+}
+
+func estimateMessageTokens(msg Message) int {
+	data, err := json.Marshal(msg)
+	if err != nil {
+		return 0
+	}
+	return estimateBytesAsTokens(len(data)) + 4
+}
+
+func estimateBytesAsTokens(n int) int {
+	if n <= 0 {
+		return 0
+	}
+	return (n + tokenEstimateCharRatio - 1) / tokenEstimateCharRatio
+}

pkg/llm/token_estimate_test.go

@@ -0,0 +1,45 @@
+package llm
+
+import "testing"
+
+func TestEstimateTokensEmpty(t *testing.T) {
+	if got := EstimateTokens(nil, nil); got != 0 {
+		t.Fatalf("EstimateTokens(nil, nil) = %d, want 0", got)
+	}
+}
+
+func TestEstimateTokens(t *testing.T) {
+	shortMessages := []Message{{Role: RoleUser, Content: "hello"}}
+	short := EstimateTokens(shortMessages, nil)
+	if short <= 4 {
+		t.Fatalf("short estimate = %d, want message framing plus content", short)
+	}
+	if short > 50 {
+		t.Fatalf("short estimate = %d, looks too high for one short message", short)
+	}
+
+	longMessages := []Message{
+		{Role: RoleUser, Content: "hello"},
+		{Role: RoleAssistant, Content: "This is a longer response with enough content to exceed the short estimate."},
+	}
+	long := EstimateTokens(longMessages, nil)
+	if long <= short {
+		t.Fatalf("long estimate = %d, want > short estimate %d", long, short)
+	}
+
+	withTools := EstimateTokens(shortMessages, []Tool{{
+		Type: "function",
+		Function: ToolFunction{
+			Name:        "file_read",
+			Description: "Read a file",
+			Parameters:  []byte(`{"type":"object"}`),
+		},
+	}})
+	if withTools <= short {
+		t.Fatalf("withTools estimate = %d, want > short estimate %d", withTools, short)
+	}
+
+	if msgTokens := estimateMessageTokens(shortMessages[0]); msgTokens <= 4 {
+		t.Fatalf("estimateMessageTokens = %d, want message framing plus content", msgTokens)
+	}
+}

pkg/llm/types.go

@@ -0,0 +1,97 @@
+package llm
+
+import (
+	"context"
+	"encoding/json"
+)
+
+const (
+	RoleSystem    = "system"
+	RoleUser      = "user"
+	RoleAssistant = "assistant"
+	RoleTool      = "tool"
+)
+
+type Provider interface {
+	ChatStream(ctx context.Context, req ChatRequest, emit func(StreamEvent) error) error
+}
+
+type ChatRequest struct {
+	Model      string         `json:"model"`
+	Messages   []Message      `json:"messages"`
+	Tools      []Tool         `json:"tools,omitempty"`
+	ToolChoice string         `json:"tool_choice,omitempty"`
+	Stream     bool           `json:"stream"`
+	Extra      map[string]any `json:"-"`
+}
+
+func (r ChatRequest) MarshalJSON() ([]byte, error) {
+	payload := map[string]any{
+		"model":    r.Model,
+		"messages": r.Messages,
+		"stream":   r.Stream,
+	}
+	if len(r.Tools) > 0 {
+		payload["tools"] = r.Tools
+	}
+	if r.ToolChoice != "" {
+		payload["tool_choice"] = r.ToolChoice
+	}
+	for key, value := range r.Extra {
+		if _, exists := payload[key]; exists {
+			continue
+		}
+		payload[key] = value
+	}
+	return json.Marshal(payload)
+}
+
+type Message struct {
+	Role       string     `json:"role"`
+	Content    string     `json:"content,omitempty"`
+	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
+	ToolCallID string     `json:"tool_call_id,omitempty"`
+}
+
+type ToolCall struct {
+	ID       string       `json:"id,omitempty"`
+	Type     string       `json:"type,omitempty"`
+	Function FunctionCall `json:"function,omitempty"`
+}
+
+type FunctionCall struct {
+	Name      string `json:"name,omitempty"`
+	Arguments string `json:"arguments,omitempty"`
+}
+
+type Tool struct {
+	Type     string       `json:"type"`
+	Function ToolFunction `json:"function"`
+}
+
+type ToolFunction struct {
+	Name        string          `json:"name"`
+	Description string          `json:"description"`
+	Parameters  json.RawMessage `json:"parameters"`
+}
+
+type StreamEvent struct {
+	Content      string
+	ToolCalls    []ToolCallDelta
+	FinishReason string
+	Usage        *Usage
+}
+
+type Usage struct {
+	PromptTokens     int `json:"prompt_tokens"`
+	CompletionTokens int `json:"completion_tokens"`
+	TotalTokens      int `json:"total_tokens"`
+}
+
+type ToolCallDelta struct {
+	Index     int
+	ID        string
+	Type      string
+	Name      string
+	Arguments string
+}