@pi-in-go/pigpen-pi-typesafe 0.1.0

package/libs/pi-typesafe-api/credentials.go

@@ -0,0 +1,252 @@
+package pitypesafe
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+// KeySource says where the key in effect comes from.
+type KeySource string
+
+// The key sources.
+const (
+	SourceEnvironment KeySource = "environment"
+	SourceStored      KeySource = "stored"
+)
+
+// KeyKind is the kind of a KeySituation.
+type KeyKind string
+
+// The key situations.
+const (
+	KeyEnvironment KeyKind = "environment"
+	KeyStored      KeyKind = "stored"
+	KeyMissing     KeyKind = "missing"
+	KeyUnusable    KeyKind = "unusable"
+	// KeyNotRequired is the own-model backend: it authenticates through PiG's model access, not a key of this package.
+	KeyNotRequired KeyKind = "notrequired"
+)
+
+// KeySituation is the complete answer to "which key is in effect".
+type KeySituation struct {
+	Kind KeyKind
+	// Key is set for environment and stored.
+	Key string
+	// KeyEnv names the variable that was read (environment only).
+	KeyEnv string
+	// Path is the store path (stored and unusable).
+	Path string
+	// Reason says why a stored key cannot be used (unusable only).
+	Reason string
+}
+
+// AgentDir is PiG's writable agent directory: PIG_CODING_AGENT_DIR, else <PIG_HOME or ~/.pig>/agent. With
+// PIG_USE_PI_DIRS=1 it is Pi's: PI_CODING_AGENT_DIR, else ~/.pi/agent. This is PiG's own rule (divergence D2),
+// not the fixed Pi directory of the original.
+func AgentDir() string {
+	if os.Getenv("PIG_USE_PI_DIRS") == "1" {
+		if v := os.Getenv("PI_CODING_AGENT_DIR"); v != "" {
+			return expandTilde(v)
+		}
+		home, _ := os.UserHomeDir()
+		return filepath.Join(home, ".pi", "agent")
+	}
+	if v := os.Getenv("PIG_CODING_AGENT_DIR"); v != "" {
+		return expandTilde(v)
+	}
+	if v := os.Getenv("PIG_HOME"); v != "" {
+		return filepath.Join(expandTilde(v), "agent")
+	}
+	if v := os.Getenv("XDG_CONFIG_HOME"); v != "" {
+		return filepath.Join(expandTilde(v), "pig", "agent")
+	}
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, ".pig", "agent")
+}
+
+func expandTilde(p string) string {
+	if p == "~" || strings.HasPrefix(p, "~/") {
+		home, _ := os.UserHomeDir()
+		return filepath.Join(home, p[1:])
+	}
+	return p
+}
+
+// TypeSafeDir is the directory every file of this package lives in.
+func TypeSafeDir() string { return filepath.Join(AgentDir(), "pi-typesafe") }
+
+// CredentialsPath is where the key lives, next to PiG's own auth.json.
+func CredentialsPath() string { return filepath.Join(TypeSafeDir(), "auth.json") }
+
+// NormalizeAPIKey accepts the key only when it is a plausible token; it never logs or echoes the value.
+func NormalizeAPIKey(value any) (string, error) {
+	key, _ := value.(string)
+	key = strings.TrimSpace(key)
+	ok := len(key) >= 16 && len(key) <= 512
+	for _, r := range key {
+		if r < 0x21 || r > 0x7e {
+			ok = false
+		}
+	}
+	if !ok {
+		return "", newError(CodeValidation, "That does not look like a TypeSafe API key. Copy the complete key from console.typesafe.ai and try again; nothing was saved.")
+	}
+	return key, nil
+}
+
+// ReadStoredAPIKey returns the stored key, or "" when the file is missing, unreadable, or holds no usable
+// value. It returns a configuration error when the file is readable by other users; KeySituationFor reports
+// that case as unusable instead.
+func ReadStoredAPIKey() (string, error) {
+	path := CredentialsPath()
+	info, err := os.Stat(path)
+	if err != nil {
+		return "", nil
+	}
+	if runtime.GOOS != "windows" && info.Mode().Perm()&0o077 != 0 {
+		// Refuse to use a key other local users can read; the user must fix permissions or log in again.
+		return "", errorf(CodeConfiguration, "Refusing to read %s: it is readable by other users. Run chmod 600 on it, or run /typesafe logout and /typesafe login.", path)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return "", nil
+	}
+	var parsed map[string]any
+	if json.Unmarshal(data, &parsed) != nil {
+		return "", nil
+	}
+	if key, ok := parsed["apiKey"].(string); ok {
+		return strings.TrimSpace(key), nil
+	}
+	return "", nil
+}
+
+// KeySituationFor says what the environment, the login store, and file permissions add up to right now for
+// one judgment backend (nil means the default). A valid backend never gets an error: the Unusable kind carries
+// the user-facing reason. An invalid backend returns the same configuration error as ResolveBackend. The
+// TypeSafe backend reads TYPESAFE_API_KEY, then the login store; every other backend reads only its own
+// environment variable, because the store holds a TypeSafe key.
+func KeySituationFor(backend any) (KeySituation, error) {
+	config, err := ResolveBackend(backend)
+	if err != nil {
+		return KeySituation{}, err
+	}
+	if config.Local {
+		return KeySituation{Kind: KeyNotRequired}, nil
+	}
+	if v := strings.TrimSpace(os.Getenv(config.KeyEnv)); v != "" {
+		return KeySituation{Kind: KeyEnvironment, Key: v, KeyEnv: config.KeyEnv}, nil
+	}
+	if !UsesTypeSafeKey(config.BackendConfig) {
+		return KeySituation{Kind: KeyMissing}, nil
+	}
+	path := CredentialsPath()
+	key, err := ReadStoredAPIKey()
+	if err != nil {
+		if ie, ok := err.(*IntegrationError); ok && ie.Code == CodeConfiguration {
+			return KeySituation{Kind: KeyUnusable, Path: path, Reason: ie.Message}, nil
+		}
+		return KeySituation{}, err
+	}
+	if key != "" {
+		return KeySituation{Kind: KeyStored, Key: key, Path: path}, nil
+	}
+	return KeySituation{Kind: KeyMissing}, nil
+}
+
+// KeySourceLabel is a short phrase naming the source.
+func KeySourceLabel(s KeySituation) string {
+	switch s.Kind {
+	case KeyEnvironment:
+		if s.KeyEnv == "" {
+			return typesafeKeyEnv
+		}
+		return s.KeyEnv
+	case KeyStored:
+		return "/typesafe login"
+	case KeyMissing:
+		return "no key"
+	case KeyUnusable:
+		return "unusable key"
+	case KeyNotRequired:
+		return "no key needed"
+	}
+	return ""
+}
+
+// ResolvedKey is a key and where it came from.
+type ResolvedKey struct {
+	Key    string
+	Source KeySource
+}
+
+// ResolveAPIKey is the pre-0.4.0 key interface of the original: environment first so CI and scripts stay
+// explicit, the stored key as the interactive default, nil when no key is configured, and a configuration
+// error when a store must not be read. New code should call KeySituationFor.
+func ResolveAPIKey(backend any) (*ResolvedKey, error) {
+	s, err := KeySituationFor(backend)
+	if err != nil {
+		return nil, err
+	}
+	switch s.Kind {
+	case KeyUnusable:
+		return nil, newError(CodeConfiguration, s.Reason)
+	case KeyEnvironment:
+		return &ResolvedKey{Key: s.Key, Source: SourceEnvironment}, nil
+	case KeyStored:
+		return &ResolvedKey{Key: s.Key, Source: SourceStored}, nil
+	}
+	return nil, nil
+}
+
+// StoreAPIKey validates and saves a key with owner-only permissions and returns the path.
+func StoreAPIKey(value any) (string, error) {
+	key, err := NormalizeAPIKey(value)
+	if err != nil {
+		return "", err
+	}
+	path := CredentialsPath()
+	body, _ := json.MarshalIndent(map[string]string{"apiKey": key}, "", "  ")
+	if err := writeOwnerOnly(path, append(body, '\n')); err != nil {
+		return "", errorf(CodeConfiguration, "Could not write %s. Check directory permissions, or set TYPESAFE_API_KEY in the environment instead.", path)
+	}
+	return path, nil
+}
+
+// writeOwnerOnly writes atomically with mode 0600 in a 0700 directory.
+func writeOwnerOnly(path string, data []byte) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return err
+	}
+	tmp := fmt.Sprintf("%s.%d.tmp", path, os.Getpid())
+	if err := os.WriteFile(tmp, data, 0o600); err != nil {
+		os.Remove(tmp)
+		return err
+	}
+	if err := os.Chmod(tmp, 0o600); err != nil {
+		os.Remove(tmp)
+		return err
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		os.Remove(tmp)
+		return err
+	}
+	return nil
+}
+
+// ClearStoredAPIKey removes the stored key and reports whether there was one.
+func ClearStoredAPIKey() bool {
+	path := CredentialsPath()
+	if _, err := os.Stat(path); err != nil {
+		return false
+	}
+	os.Remove(path)
+	return true
+}
+
+// EnvKeySet reports whether TYPESAFE_API_KEY is set (non-blank) in the environment.
+func EnvKeySet() bool { return strings.TrimSpace(os.Getenv(typesafeKeyEnv)) != "" }

package/libs/pi-typesafe-api/credentials_test.go

@@ -0,0 +1,216 @@
+package pitypesafe
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+)
+
+const validKey = "ts_test_key_0123456789abcdef"
+
+func isConfigError(err error, pattern string) bool {
+	return hasCode(err, CodeConfiguration) && regexpMatch(pattern, err.Error())
+}
+
+func TestCredentials(t *testing.T) {
+	tw(t, "credentials", "credentials live under Pi's agent directory", func(t *testing.T) {
+		dir := isolate(t)
+		// PiG's agent directory (PIG_CODING_AGENT_DIR), not Pi's fixed one: divergence D2, see port/PORT.md.
+		if CredentialsPath() != filepath.Join(dir, "pi-typesafe", "auth.json") {
+			t.Fatalf("path = %s", CredentialsPath())
+		}
+		t.Setenv("PIG_USE_PI_DIRS", "1")
+		if want := filepath.Join(os.Getenv("PI_CODING_AGENT_DIR"), "pi-typesafe", "auth.json"); CredentialsPath() != want {
+			t.Fatalf("with PIG_USE_PI_DIRS=1 the path is %s, got %s", want, CredentialsPath())
+		}
+	})
+	tw(t, "credentials", "store, read, and clear with owner-only permissions", func(t *testing.T) {
+		dir := isolate(t)
+		if got, err := ResolveAPIKey(nil); got != nil || err != nil {
+			t.Fatalf("empty store = %v, %v", got, err)
+		}
+		path, err := StoreAPIKey("  " + validKey + "\n")
+		if err != nil || path != CredentialsPath() {
+			t.Fatalf("store = %q, %v", path, err)
+		}
+		if info, _ := os.Stat(path); info.Mode().Perm() != 0o600 {
+			t.Errorf("file mode = %v", info.Mode().Perm())
+		}
+		if info, _ := os.Stat(filepath.Join(dir, "pi-typesafe")); info.Mode().Perm() != 0o700 {
+			t.Errorf("dir mode = %v", info.Mode().Perm())
+		}
+		var stored map[string]string
+		data, _ := os.ReadFile(path)
+		_ = json.Unmarshal(data, &stored)
+		if len(stored) != 1 || stored["apiKey"] != validKey {
+			t.Errorf("stored = %s", data)
+		}
+		if got, _ := ResolveAPIKey(nil); got == nil || *got != (ResolvedKey{Key: validKey, Source: SourceStored}) {
+			t.Errorf("resolved = %+v", got)
+		}
+		if !ClearStoredAPIKey() || ClearStoredAPIKey() {
+			t.Error("clear must report true once, then false")
+		}
+		if k, _ := ReadStoredAPIKey(); k != "" {
+			t.Error("cleared key is still readable")
+		}
+	})
+	tw(t, "credentials", "environment variable takes precedence over the stored key", func(t *testing.T) {
+		isolate(t)
+		_, _ = StoreAPIKey(validKey)
+		t.Setenv("TYPESAFE_API_KEY", "env_key_0123456789abcdef")
+		if got, _ := ResolveAPIKey(nil); got == nil || *got != (ResolvedKey{Key: "env_key_0123456789abcdef", Source: SourceEnvironment}) {
+			t.Fatalf("resolved = %+v", got)
+		}
+	})
+	tw(t, "credentials", "implausible keys are rejected without saving", func(t *testing.T) {
+		isolate(t)
+		for _, value := range []any{"", "short", "has space in it 0123456789", "tab\tseparated0123456789", "ключ-with-non-ascii-0123456789", strings.Repeat("x", 513), 42, nil} {
+			_, err := StoreAPIKey(value)
+			text, _ := value.(string)
+			if !hasCode(err, CodeValidation) || (len(text) >= 4 && strings.Contains(err.Error(), text)) {
+				t.Errorf("StoreAPIKey(%v) = %v", value, err)
+			}
+		}
+		if k, _ := ReadStoredAPIKey(); k != "" {
+			t.Error("nothing may be saved")
+		}
+		if got, err := NormalizeAPIKey(" " + validKey + " "); err != nil || got != validKey {
+			t.Errorf("normalize = %q, %v", got, err)
+		}
+	})
+	tw(t, "credentials", "group- or world-readable credential files are refused", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("POSIX permission bits")
+		}
+		isolate(t)
+		_, _ = StoreAPIKey(validKey)
+		_ = os.Chmod(CredentialsPath(), 0o644)
+		if _, err := ResolveAPIKey(nil); !isConfigError(err, `chmod 600`) {
+			t.Fatalf("err = %v", err)
+		}
+	})
+	tw(t, "credentials", "corrupt or unexpected files are treated as no key", func(t *testing.T) {
+		isolate(t)
+		for _, content := range []string{"not json", "[]", `{"apiKey": 5}`, "{}"} {
+			writeFile(t, CredentialsPath(), content, 0o600)
+			if k, err := ReadStoredAPIKey(); k != "" || err != nil {
+				t.Errorf("%q -> %q, %v", content, k, err)
+			}
+		}
+	})
+	tw(t, "credentials", "createTypeSafe uses the stored key and listModels verifies it without spending the request budget", func(t *testing.T) {
+		isolate(t)
+		_, _ = StoreAPIKey(validKey)
+		authorized := false
+		client, err := New(Options{MaxRequests: 1, HTTPClient: doerFunc(func(r *http.Request) (*http.Response, error) {
+			if r.URL.String() != "https://api.typesafe.ai/v1/models" {
+				t.Errorf("url = %s", r.URL)
+			}
+			authorized = strings.Contains(r.Header.Get("Authorization"), validKey)
+			return jsonResponse(200, map[string]any{"models": []any{map[string]any{"name": "jev-latest", "description": "", "release_date": "2026-01-01"}, map[string]any{"name": 7}}}, nil), nil
+		})})
+		if err != nil {
+			t.Fatal(err)
+		}
+		names, err := client.ListModels(context.Background())
+		if err != nil || len(names) != 1 || names[0] != "jev-latest" || !authorized || client.GetUsage().RequestsStarted != 0 {
+			t.Fatalf("models = %v, %v, authorized=%v", names, err, authorized)
+		}
+		ClearStoredAPIKey()
+		if _, err := New(Options{}); !isConfigError(err, `/typesafe login`) {
+			t.Fatalf("err = %v", err)
+		}
+	})
+	tw(t, "credentials", "invalid keys fail verification with a safe message", func(t *testing.T) {
+		isolate(t)
+		client, err := New(Options{APIKey: validKey, HTTPClient: doerFunc(func(*http.Request) (*http.Response, error) {
+			return jsonResponse(401, map[string]any{"detail": "secret-body"}, nil), nil
+		})})
+		if err != nil {
+			t.Fatal(err)
+		}
+		_, err = client.ListModels(context.Background())
+		ie, ok := err.(*IntegrationError)
+		if !ok || ie.Status != 401 || strings.Contains(ie.Message, "secret-body") {
+			t.Fatalf("err = %v", err)
+		}
+	})
+	tw(t, "credentials", "keySituation is total and names every kind", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("POSIX permission bits")
+		}
+		isolate(t)
+		if s, _ := KeySituationFor(nil); s != (KeySituation{Kind: KeyMissing}) {
+			t.Fatalf("missing = %+v", s)
+		}
+		_, _ = StoreAPIKey(validKey)
+		if s, _ := KeySituationFor(nil); s != (KeySituation{Kind: KeyStored, Key: validKey, Path: CredentialsPath()}) {
+			t.Fatalf("stored = %+v", s)
+		}
+		_ = os.Chmod(CredentialsPath(), 0o644)
+		s, _ := KeySituationFor(nil)
+		if s.Kind != KeyUnusable || s.Path != CredentialsPath() || !strings.Contains(s.Reason, "chmod 600") {
+			t.Fatalf("unusable = %+v", s)
+		}
+		if _, err := ResolveAPIKey(nil); err == nil || err.Error() != s.Reason {
+			t.Fatalf("resolve error = %v", err)
+		}
+		t.Setenv("TYPESAFE_API_KEY", "  "+validKey+"  ")
+		if s, _ := KeySituationFor(nil); s != (KeySituation{Kind: KeyEnvironment, Key: validKey, KeyEnv: "TYPESAFE_API_KEY"}) {
+			t.Fatalf("environment = %+v", s)
+		}
+		// Environment values are trusted as-is; a wrong key fails at the API with its own advice.
+		t.Setenv("TYPESAFE_API_KEY", "short")
+		if s, _ := KeySituationFor(nil); s != (KeySituation{Kind: KeyEnvironment, Key: "short", KeyEnv: "TYPESAFE_API_KEY"}) {
+			t.Fatalf("short = %+v", s)
+		}
+	})
+	tw(t, "credentials", "keySituation for another backend reads only that backend's variable, never the TypeSafe store", func(t *testing.T) {
+		isolate(t)
+		_, _ = StoreAPIKey(validKey)
+		t.Setenv("TYPESAFE_API_KEY", validKey)
+		// A stored or TypeSafe-environment key is not an OpenRouter key.
+		if s, _ := KeySituationFor("openrouter"); s != (KeySituation{Kind: KeyMissing}) {
+			t.Fatalf("openrouter = %+v", s)
+		}
+		if got, _ := ResolveAPIKey("openrouter"); got != nil {
+			t.Fatalf("resolved = %+v", got)
+		}
+		t.Setenv("OPENROUTER_API_KEY", "  sk-or-test-0123456789abcdef  ")
+		s, _ := KeySituationFor("openrouter")
+		if s != (KeySituation{Kind: KeyEnvironment, Key: "sk-or-test-0123456789abcdef", KeyEnv: "OPENROUTER_API_KEY"}) || KeySourceLabel(s) != "OPENROUTER_API_KEY" {
+			t.Fatalf("openrouter env = %+v", s)
+		}
+		if got, _ := ResolveAPIKey("openrouter"); got == nil || *got != (ResolvedKey{Key: "sk-or-test-0123456789abcdef", Source: SourceEnvironment}) {
+			t.Fatalf("resolved = %+v", got)
+		}
+		// The OpenRouter variable does not leak into the TypeSafe resolution either.
+		t.Setenv("TYPESAFE_API_KEY", "")
+		if s, _ := KeySituationFor(nil); s.Kind != KeyStored {
+			t.Fatalf("typesafe = %+v", s)
+		}
+		if _, err := KeySituationFor("bogus"); !isConfigError(err, `Unknown judgment backend`) {
+			t.Fatalf("err = %v", err)
+		}
+	})
+	tw(t, "credentials", "keySourceLabel names each source", func(t *testing.T) {
+		cases := map[KeySituation]string{
+			{Kind: KeyEnvironment, Key: "k"}:                               "TYPESAFE_API_KEY",
+			{Kind: KeyEnvironment, Key: "k", KeyEnv: "OPENROUTER_API_KEY"}: "OPENROUTER_API_KEY",
+			{Kind: KeyStored, Key: "k", Path: "/tmp/auth.json"}:            "/typesafe login",
+			{Kind: KeyMissing}: "no key",
+			{Kind: KeyUnusable, Path: "/tmp/auth.json", Reason: "r"}: "unusable key",
+		}
+		for s, want := range cases {
+			if got := KeySourceLabel(s); got != want {
+				t.Errorf("%+v -> %q, want %q", s, got, want)
+			}
+		}
+	})
+}

package/libs/pi-typesafe-api/doc.go

@@ -0,0 +1,14 @@
+// Package pitypesafe is the typed API of Pigpen's TypeSafe integration: a Go port of the
+// library half of pi-typesafe (https://github.com/DevMortimer/pi-typesafe, MIT, Ryan
+// Gapac). It wraps the shared client (components/typesafe) with what an extension needs
+// around it: one admission rule for requests, request and spend caps that survive
+// restarts, a key store and an auth state that says whether judgments are really
+// happening, judgment backends (TypeSafe, OpenRouter, Command Code, a caller-supplied
+// endpoint, and the model PiG is configured with), a never-throwing Ask, batching, and
+// a calibration kit.
+//
+// Content sent through a TypeSafe, OpenRouter, Command Code or custom endpoint backend
+// leaves the machine for that host; content sent through the own-model backend goes to
+// the provider of the model PiG is configured with. ResolveBackend and BackendHost name
+// the destination for consent text.
+package pitypesafe

package/libs/pi-typesafe-api/errors.go

@@ -0,0 +1,143 @@
+package pitypesafe
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/MichaelKinsy/pigpen/components/typesafe/libraries/typesafe"
+)
+
+// ErrorCode classifies an IntegrationError.
+type ErrorCode string
+
+// The error codes.
+const (
+	CodeConfiguration ErrorCode = "configuration"
+	CodeValidation    ErrorCode = "validation"
+	CodeBudget        ErrorCode = "budget"
+	CodeAborted       ErrorCode = "aborted"
+	CodeTimeout       ErrorCode = "timeout"
+	CodeHTTP          ErrorCode = "http"
+	CodeConnection    ErrorCode = "connection"
+	CodeResponse      ErrorCode = "response"
+)
+
+// IntegrationError is safe to display: it never contains upstream bodies, keys, or submitted
+// state. The only header value a message can quote is a numeric Retry-After count in seconds,
+// which cannot carry a secret.
+type IntegrationError struct {
+	Code    ErrorCode
+	Message string
+	// Status is the HTTP status for CodeHTTP errors, else 0.
+	Status int
+}
+
+// Error returns the safe message.
+func (e *IntegrationError) Error() string { return e.Message }
+
+func newError(code ErrorCode, message string) *IntegrationError {
+	return &IntegrationError{Code: code, Message: message}
+}
+
+func errorf(code ErrorCode, format string, args ...any) *IntegrationError {
+	return newError(code, fmt.Sprintf(format, args...))
+}
+
+// SafeError classifies any error into a message safe to display. backend names the key variable
+// the 401 advice tells the user to check and selects the 402 wording; nil assumes the default
+// TypeSafe key. An error that is already an *IntegrationError is returned as is.
+func SafeError(err error, backend any) *IntegrationError {
+	var own *IntegrationError
+	if errors.As(err, &own) {
+		return own
+	}
+	config := errorBackend(backend)
+	var abort *typesafe.APIUserAbortError
+	if errors.As(err, &abort) || errors.Is(err, context.Canceled) {
+		return newError(CodeAborted, config.subject()+" request cancelled; an already submitted request may still be billed.")
+	}
+	var timeout *typesafe.APITimeoutError
+	if errors.As(err, &timeout) || errors.Is(err, context.DeadlineExceeded) {
+		return newError(CodeTimeout, config.subject()+" request timed out; it was not retried and may still be billed.")
+	}
+	var api *typesafe.APIError
+	if errors.As(err, &api) {
+		advice := httpAdvice(api.Status, api.Header, config)
+		e := errorf(CodeHTTP, "%s returned HTTP %d. %s No automatic retry was made.", config.subject(), api.Status, advice)
+		e.Status = api.Status
+		return e
+	}
+	var conn *typesafe.APIConnectionError
+	if errors.As(err, &conn) {
+		return newError(CodeConnection, "Could not complete the "+config.subject()+" connection. No automatic retry was made.")
+	}
+	return newError(CodeResponse, config.subject()+" returned an unreadable or unexpected response.")
+}
+
+// errorConfig is what error wording needs from a backend.
+type errorConfig struct {
+	keyEnv     string
+	openrouter bool
+	local      bool
+}
+
+func (c errorConfig) subject() string {
+	if c.local {
+		return "The configured model"
+	}
+	return "TypeSafe"
+}
+
+func errorBackend(backend any) errorConfig {
+	if backend == nil {
+		return errorConfig{keyEnv: typesafeKeyEnv}
+	}
+	resolved, err := ResolveBackend(backend)
+	if err != nil {
+		return errorConfig{keyEnv: typesafeKeyEnv}
+	}
+	return errorConfig{keyEnv: resolved.KeyEnv, openrouter: resolved.Host == DecisionsBackends[BackendOpenRouter].Host, local: resolved.Local}
+}
+
+// retryAfterSeconds is a numeric Retry-After delay in seconds; dates, blanks, and anything else stay out of the message.
+func retryAfterSeconds(h http.Header) (int, bool) {
+	raw := strings.TrimSpace(h.Get("Retry-After"))
+	if raw == "" {
+		return 0, false
+	}
+	n, err := strconv.ParseInt(raw, 10, 64)
+	if err != nil || n < 0 || n > 1<<53-1 {
+		return 0, false
+	}
+	return int(n), true
+}
+
+func httpAdvice(status int, h http.Header, c errorConfig) string {
+	switch status {
+	case 401:
+		if c.local {
+			return "Check the credentials of the configured model."
+		}
+		return "Check " + c.keyEnv + "."
+	case 402:
+		if c.openrouter {
+			return "Insufficient credits. Add credits at https://openrouter.ai/credits."
+		}
+		return "Check your account balance."
+	case 403:
+		return "Check your account access and model permissions."
+	case 429:
+		advice := "Check your account quota and try again later."
+		if secs, ok := retryAfterSeconds(h); ok {
+			advice += " Retry after " + strconv.Itoa(secs) + " seconds."
+		}
+		return advice
+	case 400, 422:
+		return "Check the question format and model limits."
+	}
+	return "Try again later or check the service status."
+}