Support API key env for recall extraction endpoints (#1268)

## Summary
- add `api_key_env` to `[recall.extract.servers.<name>]` so authenticated OpenAI-compatible recall extraction endpoints can use bearer tokens without embedding credentials in URLs
- wire the resolved server key into the extraction client and keep endpoint-provided diagnostics withheld when a bearer credential is configured
- document an Atlas Cloud HTTPS example using `ATLASCLOUD_API_KEY` and `deepseek-ai/deepseek-v4-pro`

## Testing
- `git diff --check`
- Atlas Cloud live model catalog: `GET https://api.atlascloud.ai/v1/models` returned HTTP 200 with 121 models; confirmed `deepseek-ai/deepseek-v4-pro` and `qwen/qwen3.5-flash`
- Not run: `gofmt` / `go test ./internal/config ./internal/recall/extract ./cmd/agentsview` because this machine has no Go toolchain in PATH (`go` and `gofmt` command not found); Docker is installed but the daemon is not running


Co-authored-by: nb213 <binyangzhu000-sudo@users.noreply.github.com>

Author: binyangzhu000-sudo

cmd/agentsview/recall_extract.go

@@ -98,6 +98,7 @@ func resolveExtractDistillation(
 	return extractDistillation{
 		Client: &extract.Client{
 			BaseURL:    server.Endpoint,
+			APIKey:     server.APIKey(),
 			Model:      cfg.Model,
 			HTTPClient: httpClient,
 			Request:    request,

cmd/agentsview/recall_extract_test.go

@@ -315,6 +315,7 @@ func TestRecallExtractPreviewSubcommandBuildsChunks(t *testing.T) {
 
 func TestResolveExtractDistillationAppliesOverrides(t *testing.T) {
 	temp := 0.3
+	t.Setenv("AGENTSVIEW_TEST_RECALL_API_KEY", "atlas-secret")
 	cfg := config.RecallExtractConfig{
 		Enabled:          true,
 		Model:            "qwen3.5-27b",
@@ -325,7 +326,11 @@ func TestResolveExtractDistillationAppliesOverrides(t *testing.T) {
 		BackstopInterval: "1h",
 		FailureBackoff:   "2h",
 		Servers: map[string]config.RecallExtractServerConfig{
-			"local": {Endpoint: "http://127.0.0.1:30000/v1", Timeout: "120s"},
+			"local": {
+				Endpoint:  "http://127.0.0.1:30000/v1",
+				APIKeyEnv: "AGENTSVIEW_TEST_RECALL_API_KEY",
+				Timeout:   "120s",
+			},
 		},
 		Request: config.RecallExtractRequestConfig{
 			Temperature: &temp,
@@ -338,6 +343,7 @@ func TestResolveExtractDistillationAppliesOverrides(t *testing.T) {
 	assert.Equal(t, "qwen", dist.Profile,
 		"model prefix must select the qwen profile")
 	assert.Equal(t, "http://127.0.0.1:30000/v1", dist.Client.BaseURL)
+	assert.Equal(t, "atlas-secret", dist.Client.APIKey)
 	assert.Equal(t, 0.3, dist.Client.Request.Temperature)
 	assert.Equal(t, 512, dist.Client.Request.MaxTokens)
 	assert.Equal(t, map[string]any{"custom": true},

docs/recall.md

@@ -98,13 +98,28 @@ model = "your-model-name"
 endpoint = "http://127.0.0.1:30000/v1"
 ```
 
+For a remote OpenAI-compatible provider such as Atlas Cloud, keep the key in the
+environment and point the server entry at the provider's `/v1` base URL:
+
+```toml
+[recall.extract]
+enabled = true
+model = "deepseek-ai/deepseek-v4-pro"
+server = "atlascloud"
+
+[recall.extract.servers.atlascloud]
+endpoint = "https://api.atlascloud.ai/v1"
+api_key_env = "ATLASCLOUD_API_KEY"
+timeout = "120s"
+```
+
 Optional keys: `deployment` (labels which serving instance produced the corpus),
 `server` (selects among multiple named servers), `quiet_period` (default `"30m"`
 — how long a session must have been ended before extraction),
 `backstop_interval` (default `"1h"`), `failure_backoff` (default `"1h"`),
-`max_window_chars` (default 50000), `max_tokens`, a `[recall.extract.prompts]`
-table (`profile`, `dir`), and a `[recall.extract.request]` table (`temperature`,
-`extra_body`).
+`max_window_chars` (default 50000), `max_tokens`, per-server `api_key_env`, a
+`[recall.extract.prompts]` table (`profile`, `dir`), and a
+`[recall.extract.request]` table (`temperature`, `extra_body`).
 
 Non-loopback endpoints must use HTTPS: extraction sends transcript content to
 the endpoint, and plaintext HTTP off the machine could be intercepted. A server

internal/config/config_recall_test.go

@@ -214,6 +214,17 @@ func TestRecallExtractConfigValidate(t *testing.T) {
 	}
 }
 
+func TestRecallExtractServerConfigAPIKeyEnv(t *testing.T) {
+	var server RecallExtractServerConfig
+	assert.Equal(t, "", server.APIKey(), "no env var configured")
+
+	server.APIKeyEnv = "AGENTSVIEW_TEST_RECALL_API_KEY"
+	assert.Equal(t, "", server.APIKey(), "configured env var not set in environment")
+
+	t.Setenv("AGENTSVIEW_TEST_RECALL_API_KEY", "secret-123")
+	assert.Equal(t, "secret-123", server.APIKey())
+}
+
 // TestRecallExtractValidationRedactsEndpointCredentials pins that
 // validation errors never echo endpoint credentials: config errors land on
 // stderr and in CI logs, and endpoints may carry Basic-auth userinfo or

internal/config/recall.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"net"
 	"net/url"
+	"os"
 	"slices"
 	"sort"
 	"strings"
@@ -64,6 +65,9 @@ type RecallExtractServerConfig struct {
 	// Endpoint is the OpenAI-compatible base URL, e.g.
 	// "http://127.0.0.1:30000/v1".
 	Endpoint string `toml:"endpoint" json:"endpoint"`
+	// APIKeyEnv names the environment variable holding the API key.
+	// Empty means anonymous access.
+	APIKeyEnv string `toml:"api_key_env" json:"api_key_env,omitempty"`
 	// Timeout is a parseable duration string applied to each model call.
 	// Distillation calls on local models are slow; default "120s".
 	Timeout string `toml:"timeout" json:"timeout"`
@@ -73,6 +77,15 @@ type RecallExtractServerConfig struct {
 	AllowHTTP bool `toml:"allow_http" json:"allow_http,omitempty"`
 }
 
+// APIKey reads the API key from the environment variable named by
+// APIKeyEnv. Returns "" when APIKeyEnv is unset.
+func (s RecallExtractServerConfig) APIKey() string {
+	if s.APIKeyEnv == "" {
+		return ""
+	}
+	return os.Getenv(s.APIKeyEnv)
+}
+
 // RecallExtractPromptsConfig selects the prompt profile and optional
 // per-role override files.
 type RecallExtractPromptsConfig struct {

internal/recall/extract/client.go

@@ -245,7 +245,10 @@ var entrySchema = map[string]any{
 // fingerprint.
 type Client struct {
 	BaseURL string
-	Model   string
+	// APIKey is sent as a bearer token when non-empty. Keep credentials
+	// outside BaseURL so redacted endpoint logs stay useful.
+	APIKey string
+	Model  string
 	// RetryBackoff seeds the exponential wait between transient retries;
 	// zero means 500ms. It shapes latency, not output, so it stays outside
 	// RequestShape and the fingerprint.
@@ -408,6 +411,9 @@ func (c *Client) distill(
 		return nil, Usage{}, fmt.Errorf("building distill request: %w", err)
 	}
 	request.Header.Set("Content-Type", "application/json")
+	if c.APIKey != "" {
+		request.Header.Set("Authorization", "Bearer "+c.APIKey)
+	}
 
 	response, err := c.httpClient().Do(request)
 	if err != nil {
@@ -609,14 +615,17 @@ func (c *Client) distill(
 	return entries, parsed.Usage, nil
 }
 
-// credentialedEndpoint reports whether the configured endpoint URL
-// carries credential material: userinfo, or any raw query segment whose
-// key is not the api-version surface selector (mirroring the config
-// redactor's fail-closed allowlist). Raw wire segments, no parser:
+// credentialedEndpoint reports whether the configured request carries
+// credential material: a bearer token, URL userinfo, or any raw query
+// segment whose key is not the api-version surface selector (mirroring
+// the config redactor's fail-closed allowlist). Raw wire segments, no parser:
 // url.ParseQuery would reject exactly the malformed queries that still
 // travel verbatim, and a rejection must not fail open. An unparseable URL
 // counts as credentialed for the same reason.
 func (c *Client) credentialedEndpoint() bool {
+	if c.APIKey != "" {
+		return true
+	}
 	endpoint, err := url.Parse(c.BaseURL)
 	if err != nil {
 		return true

internal/recall/extract/client_test.go

@@ -146,6 +146,36 @@ func TestClientDistillParsesEntriesAndSendsShape(t *testing.T) {
 	}
 }
 
+func TestClientDistillSendsBearerToken(t *testing.T) {
+	var gotAuth string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotAuth = r.Header.Get("Authorization")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"choices": []map[string]any{{
+				"finish_reason": "stop",
+				"message": map[string]any{
+					"role":    "assistant",
+					"content": entriesJSON(t, "one"),
+				},
+			}},
+			"usage": map[string]any{
+				"prompt_tokens":     7,
+				"completion_tokens": 3,
+			},
+		})
+	}))
+	defer server.Close()
+
+	client := testClient(server.URL)
+	client.APIKey = "secret-key"
+	_, _, err := client.DistillWithRecovery(
+		context.Background(), "system prompt", "unit text", 1,
+	)
+	require.NoError(t, err)
+
+	assert.Equal(t, "Bearer secret-key", gotAuth)
+}
+
 func TestClientTrailingSlashBaseURL(t *testing.T) {
 	var requests []map[string]any
 	server := newScriptedServer(t, []scriptedResponse{