Skip to content

Commit 5e0efb0

Browse files
wpfleger96npub1ng3jzsaqxdhrfq22dg85j3lpr0zsh3jp7g2h9jyxl59wraayapnsu6kvfg
andauthored
fix(desktop): disambiguate provider API key labels and annotate mint key (#4406)
Two different credentials were presented under the same name throughout the app. The top-level credential field for non-Anthropic providers (OpenAI, OpenAI-compatible, OpenRouter) was labeled "OpenAI API Key" via a hardcoded binary ternary repeated in three dialogs. The card-minting key (`OPENAI_API_KEY`) and the runtime credential (`OPENAI_COMPAT_API_KEY`) have independent endpoint namespaces and consumers (`OPENAI_COMPAT_BASE_URL`/`OPENAI_COMPAT_API_KEY` for runtime, `OPENAI_BASE_URL`/`OPENAI_API_KEY` for minting) and must remain separate — either may require a different credential. This PR makes them impossible to confuse in the UI. ## Changes **Provider-accurate labels from the credential table.** `PROVIDER_CREDENTIAL_CONFIG` entries now carry an `apiKeyLabel` paired with `secretEnvVar` as a discriminated union (both present or neither — a future provider cannot ship a secret field with no label). `getProviderApiKeyLabel(providerId)` is the single source of truth. The three hardcoded ternaries in `AgentConfigFields`, `AgentInstanceEditDialog`, and `AgentDefinitionDialog` are replaced by this helper. Labels: `openai` → "OpenAI Runtime API Key", `openai-compat` → "OpenAI-compatible Runtime API Key", `openrouter` → "OpenRouter API Key" (was incorrectly "OpenAI API Key"), `anthropic` → "Anthropic API Key" (unchanged). **Field names its backing env var.** `PersonaProviderApiKeyField` renders the env var name as a monospace hint beneath the label with `aria-describedby` wiring. All three call sites pass their `secretEnvVar`. A user who sees `OPENAI_API_KEY` in the mint dialog can now confirm at a glance that the credential field shows `OPENAI_COMPAT_API_KEY` — a different key. **Signpost visible at the decision point.** `CARD_MINT_KEY_ANNOTATIONS` is exported from `agentConfigOptions.tsx` (single source) and passed as `keyAnnotations` to all three generic env editors: both `EnvVarsEditor` branches in Agent Defaults, `EditAgentAdvancedFields`, and `PersonaAdvancedFields`. `CardMintKeyCue` — a new small component — renders an always-visible muted cue beneath the Advanced toggle when `OPENAI_API_KEY` is present in global env (Advanced is collapsed by default, so the per-row annotation is invisible until the cue guides the user to open it). **Model discovery error copy.** The `OPENAI_COMPAT_API_KEY required` message now reads "Enter an OpenAI runtime API key (OPENAI_COMPAT_API_KEY) to load OpenAI models." — naming the env var explicitly so it cannot be confused with the mint key. ## Tests - `getProviderApiKeyLabel` helper: pinned correct label per provider including the new distinct labels for `openai` and `openai-compat` - `PersonaProviderApiKeyField` render: semantic label present; env-var hint rendered when `envVarName` provided; `aria-describedby` wired to hint id; hint and describedby absent when prop omitted - `EnvVarsEditor` render: annotation appears exactly once on the matching row; absent for non-matching rows - `personaModelDiscoveryStatus`: pinned new copy naming `OPENAI_COMPAT_API_KEY` explicitly - Playwright: stale `"OpenAI API Key"` selectors updated; new `card-mint-key-cue-visible-and-annotation-in-advanced` test covers Will's exact path (databricks_v2 global provider + saved `OPENAI_API_KEY` → cue visible before opening Advanced → annotation present after opening) ## File sizes (post-format) | File | Lines | |------|-------| | `AgentConfigFields.tsx` | 994 (≤ 996) | | `AgentInstanceEditDialog.tsx` | 1228 (≤ 1228) | | `AgentDefinitionDialog.tsx` | 1045 (≤ 1047) | Related: [#4140](#4140) --------- Signed-off-by: Will Pfleger <[email protected]> Co-authored-by: npub1ng3jzsaqxdhrfq22dg85j3lpr0zsh3jp7g2h9jyxl59wraayapnsu6kvfg <9a232143a0336e34814a6a0f4947e11bc50bc641f21572c886fd0ae1f7a4e867@buzz.block.builderlab.xyz>
1 parent f810a2f commit 5e0efb0

16 files changed

Lines changed: 505 additions & 39 deletions

‎desktop/src/features/agents/ui/AgentConfigFields.tsx‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,11 @@ import {
3232
import {
3333
AUTO_PROVIDER_DROPDOWN_VALUE,
3434
BLOCK_BUILD_HIDDEN_PROVIDER_IDS,
35+
CARD_MINT_KEY_ANNOTATIONS,
3536
CUSTOM_PROVIDER_DROPDOWN_VALUE,
3637
getPersonaProviderOptions,
3738
getProviderApiKeyEnvVar,
39+
getProviderApiKeyLabel,
3840
runtimeSupportsLlmProviderSelection,
3941
} from "@/features/agents/ui/agentConfigOptions";
4042
import {
@@ -54,6 +56,7 @@ import {
5456
} from "@/features/agents/ui/buzzAgentModelTuningFields";
5557
import { SettingsOptionGroup } from "@/features/settings/ui/SettingsOptionGroup";
5658
import { AdvancedRequiredBadge } from "./AdvancedRequiredBadge";
59+
import { CardMintKeyCue } from "./CardMintKeyCue";
5760
import { getGlobalAgentCredentialState } from "./globalAgentCredentialState";
5861

5962
export const EMPTY_GLOBAL_CONFIG: GlobalAgentConfig = {
@@ -74,7 +77,6 @@ const PROGRESSIVE_FIELDS_TRANSITION = {
7477
duration: 0.22,
7578
ease: [0.23, 1, 0.32, 1],
7679
} as const;
77-
7880
type AgentConfigDisclosure =
7981
| "full"
8082
| "onboarding-essential"
@@ -85,13 +87,9 @@ type AgentConfigDisclosure =
8587
// - auto-select a valid model when the provider changes
8688
// - keep the model select usable during discovery
8789
// - preserve credential env vars across provider switches (the abandoned
88-
// provider's key stays in env_vars — visible/deletable under Advanced —
89-
// so flipping back never loses a typed key; spawned agents may therefore
90-
// see credentials for providers they don't use)
90+
// provider's key stays in env_vars — visible/deletable under Advanced)
9191
// - require a provider before model/effort are editable (no saveable
92-
// invalid state — design principle #4). Note: legacy configs saved with
93-
// a model but no provider are cleared by the pre-existing orphan-model
94-
// effect on next edit — deliberate data healing, documented in PR.
92+
// invalid state — design principle #4)
9593
const autoSelectModelOnProviderChange = true;
9694
const disableModelSelectDuringDiscovery = false;
9795
const preserveCredentialEnvVarsOnProviderChange = true;
@@ -747,18 +745,15 @@ export function AgentConfigFields({
747745
<div className={blockClassName}>
748746
<PersonaProviderApiKeyField
749747
disabled={false}
748+
envVarName={apiKeyEnvVar}
750749
inheritedLabel={
751750
apiKeyFileSatisfied
752751
? "Set in runtime config"
753752
: "Provided by this build"
754753
}
755754
isInherited={apiKeyInherited}
756755
isRequired={!apiKeyInherited && apiKeyValue.length === 0}
757-
label={
758-
effectiveProvider === "anthropic"
759-
? "Anthropic API Key"
760-
: "OpenAI API Key"
761-
}
756+
label={getProviderApiKeyLabel(effectiveProvider) ?? "API Key"}
762757
onValueChange={(value) =>
763758
onConfigChange({
764759
...config,
@@ -869,6 +864,7 @@ export function AgentConfigFields({
869864

870865
{showAdvancedFields ? (
871866
<div className={cn(blockClassName, "space-y-3")}>
867+
<CardMintKeyCue envVars={config.env_vars} />
872868
<button
873869
aria-expanded={advancedOpen}
874870
className={cn(
@@ -912,6 +908,7 @@ export function AgentConfigFields({
912908
hiddenKeys={apiKeyEnvVar ? [apiKeyEnvVar] : []}
913909
inheritedRows={bakedGenericRows}
914910
inheritedRowsLabel="build"
911+
keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
915912
label="Environment variables"
916913
onChange={handleEnvVarsChange}
917914
requiredKeys={advancedRequiredEnvKeys}
@@ -930,6 +927,7 @@ export function AgentConfigFields({
930927
hiddenKeys={apiKeyEnvVar ? [apiKeyEnvVar] : []}
931928
inheritedRows={bakedGenericRows}
932929
inheritedRowsLabel="build"
930+
keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
933931
label="Environment variables"
934932
onChange={handleEnvVarsChange}
935933
requiredKeys={advancedRequiredEnvKeys}

‎desktop/src/features/agents/ui/AgentDefinitionDialog.tsx‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ import {
4242
getDefaultPersonaRuntime,
4343
getPersonaModelOptions,
4444
getPersonaProviderOptions,
45+
getProviderApiKeyLabel,
4546
getRuntimePersonaModelOptions,
4647
NO_RUNTIME_DROPDOWN_VALUE,
4748
runtimeSupportsLlmProviderSelection,
@@ -907,14 +908,11 @@ export function AgentDefinitionDialog({
907908
topLevelSecretEnvVar ? (
908909
<PersonaProviderApiKeyField
909910
disabled={isPending}
911+
envVarName={topLevelSecretEnvVar}
910912
isInherited={apiKeyIsInherited}
911913
inheritedLabel={apiKeyInheritedLabel}
912914
isRequired={apiKeyIsRequired}
913-
label={
914-
effectiveProvider === "anthropic"
915-
? "Anthropic API key"
916-
: "OpenAI API key"
917-
}
915+
label={getProviderApiKeyLabel(effectiveProvider) ?? "API key"}
918916
onValueChange={(next) => {
919917
setEnvVars((prev) => ({
920918
...prev,

‎desktop/src/features/agents/ui/AgentInstanceEditDialog.tsx‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,10 @@ import {
7575
getBakedModelInheritLabel,
7676
getBakedProviderInheritLabel,
7777
} from "./bakedEnvHelpers";
78-
import { getProviderApiKeyEnvVar } from "./agentConfigOptions";
78+
import {
79+
getProviderApiKeyEnvVar,
80+
getProviderApiKeyLabel,
81+
} from "./agentConfigOptions";
7982
import { useAgentDialogDefaults } from "./useAgentDialogDefaults";
8083
import { AgentAiDefaultsNotice } from "./AgentAiDefaults";
8184
import { AgentDefaultsDialog } from "./AgentDefaultsDialog";
@@ -1061,14 +1064,11 @@ export function AgentInstanceEditDialog({
10611064
{llmProviderFieldVisible && topLevelSecretEnvVar ? (
10621065
<PersonaProviderApiKeyField
10631066
disabled={updateMutation.isPending}
1067+
envVarName={topLevelSecretEnvVar}
10641068
isInherited={apiKeyIsInherited}
10651069
inheritedLabel={apiKeyInheritedLabel}
10661070
isRequired={apiKeyIsRequired}
1067-
label={
1068-
effectiveProvider === "anthropic"
1069-
? "Anthropic API Key"
1070-
: "OpenAI API Key"
1071-
}
1071+
label={getProviderApiKeyLabel(effectiveProvider) ?? "API Key"}
10721072
onValueChange={(next) => {
10731073
setEnvVars((prev) => ({
10741074
...prev,
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/**
2+
* Always-visible cue shown in Agent Defaults when a global `OPENAI_API_KEY`
3+
* row exists (nonblank). The Advanced section is collapsed by default, so
4+
* the `keyAnnotations` hint on that row is invisible until the user opens it
5+
* — this cue bridges the gap by surfacing the information at the decision
6+
* point.
7+
*
8+
* Renders nothing when `OPENAI_API_KEY` is absent or blank.
9+
*/
10+
export function CardMintKeyCue({
11+
envVars,
12+
}: {
13+
envVars: Record<string, string>;
14+
}) {
15+
const isSet =
16+
"OPENAI_API_KEY" in envVars &&
17+
(envVars.OPENAI_API_KEY ?? "").trim().length > 0;
18+
if (!isSet) return null;
19+
20+
return (
21+
<p
22+
className="text-xs text-muted-foreground"
23+
data-testid="card-mint-key-cue"
24+
>
25+
Card-minting key <span className="font-mono">OPENAI_API_KEY</span> is set
26+
under Advanced → Environment variables.
27+
</p>
28+
);
29+
}

‎desktop/src/features/agents/ui/EditAgentAdvancedFields.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { Input } from "@/shared/ui/input";
33
import { Textarea } from "@/shared/ui/textarea";
44
import { EnvVarsEditor, type EnvVarsValue } from "./EnvVarsEditor";
55
import {
6+
CARD_MINT_KEY_ANNOTATIONS,
67
PERSONA_FIELD_CONTROL_CLASS,
78
PERSONA_FIELD_SHELL_CLASS,
89
PERSONA_LABEL_OPTIONAL_CLASS,
@@ -247,6 +248,7 @@ export function EditAgentAdvancedFields({
247248
helperText="Per-agent env vars. Override the template's vars on collision."
248249
inheritedFrom={inheritedEnvVars}
249250
inheritedLabel="template / global defaults"
251+
keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
250252
onChange={onEnvVarsChange}
251253
requiredKeys={requiredEnvKeys}
252254
value={envVars}

‎desktop/src/features/agents/ui/EnvVarsEditor.test.mjs‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -523,3 +523,97 @@ test("getBakedProviderInheritLabel_empty_options_falls_back_to_raw_id", () => {
523523
"empty options table must fall back to raw id",
524524
);
525525
});
526+
527+
// ── keyAnnotations — annotation lookup invariants ─────────────────────────────
528+
//
529+
// `keyAnnotations` is a pass-through prop: the renderer does `keyAnnotations?.[key]`.
530+
// The invariant worth pinning is that the prop contract is respected at the
531+
// data level — an annotation for one key does NOT bleed into another key.
532+
// (Rendering itself is trivially conditional; no logic to extract.)
533+
534+
test("keyAnnotations_present_key_has_annotation", () => {
535+
const annotations = {
536+
OPENAI_API_KEY: "Used for minting agent trading cards",
537+
};
538+
assert.equal(
539+
annotations.OPENAI_API_KEY,
540+
"Used for minting agent trading cards",
541+
);
542+
});
543+
544+
test("keyAnnotations_absent_key_is_undefined", () => {
545+
const annotations = {
546+
OPENAI_API_KEY: "Used for minting agent trading cards",
547+
};
548+
assert.equal(annotations.ANTHROPIC_API_KEY, undefined);
549+
});
550+
551+
test("keyAnnotations_empty_map_has_no_annotations", () => {
552+
const annotations = {};
553+
assert.equal(annotations.OPENAI_API_KEY, undefined);
554+
});
555+
556+
test("keyAnnotations_only_matching_key_gets_annotation", () => {
557+
// Verifies the per-key lookup is not accidentally global.
558+
const annotations = { OPENAI_API_KEY: "card minting" };
559+
const keys = ["OPENAI_API_KEY", "ANTHROPIC_API_KEY", "FOO"];
560+
const results = keys.map((k) => annotations[k] ?? null);
561+
assert.deepEqual(results, ["card minting", null, null]);
562+
});
563+
564+
// ── keyAnnotations render — annotation appears only on matching row ─────────
565+
//
566+
// renderToStaticMarkup exercises the real JSX path:
567+
// {keyAnnotations?.[row.key] ? <p ...>{annotation}</p> : null}
568+
// This confirms the prop is plumbed through to the DOM correctly and that
569+
// annotation text is scoped to its matching row.
570+
571+
import React from "react";
572+
import { renderToStaticMarkup } from "react-dom/server";
573+
import { EnvVarsEditor } from "./EnvVarsEditor.tsx";
574+
575+
test("keyAnnotations_annotation_present_only_on_matching_row", () => {
576+
const annotations = {
577+
OPENAI_API_KEY: "Used for minting agent trading cards",
578+
};
579+
const html = renderToStaticMarkup(
580+
React.createElement(EnvVarsEditor, {
581+
disabled: false,
582+
fileSatisfiedKeys: [],
583+
hiddenKeys: [],
584+
keyAnnotations: annotations,
585+
onChange: () => {},
586+
requiredKeys: [],
587+
value: { OPENAI_API_KEY: "sk-placeholder", ANTHROPIC_API_KEY: "sk-ant" },
588+
}),
589+
);
590+
assert.ok(
591+
html.includes("Used for minting agent trading cards"),
592+
"annotation must appear in rendered output for OPENAI_API_KEY row",
593+
);
594+
// The annotation must not bleed to other rows — check that it appears only once.
595+
const count = (html.match(/Used for minting agent trading cards/g) ?? [])
596+
.length;
597+
assert.equal(count, 1, "annotation must appear exactly once");
598+
});
599+
600+
test("keyAnnotations_annotation_absent_for_non_matching_rows", () => {
601+
const annotations = {
602+
OPENAI_API_KEY: "Used for minting agent trading cards",
603+
};
604+
const html = renderToStaticMarkup(
605+
React.createElement(EnvVarsEditor, {
606+
disabled: false,
607+
fileSatisfiedKeys: [],
608+
hiddenKeys: [],
609+
keyAnnotations: annotations,
610+
onChange: () => {},
611+
requiredKeys: [],
612+
value: { ANTHROPIC_API_KEY: "sk-ant", MY_VAR: "foo" },
613+
}),
614+
);
615+
assert.ok(
616+
!html.includes("Used for minting agent trading cards"),
617+
"annotation must not appear when its key is not in the env map",
618+
);
619+
});

‎desktop/src/features/agents/ui/EnvVarsEditor.tsx‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,14 @@ type EnvVarsEditorProps = {
165165
inheritedRows?: readonly InheritedEnvRow[];
166166
/** Label for the inherited-row tag (e.g. "build"). Defaults to "build". */
167167
inheritedRowsLabel?: string;
168+
/**
169+
* Optional muted one-line annotation for specific env var keys. Rendered
170+
* below any row whose key appears in this map — required rows, user rows,
171+
* and user rows whose key is typed mid-edit. Intended for contextual hints
172+
* like `{ OPENAI_API_KEY: "Used for minting agent trading cards" }` that
173+
* help users distinguish two keys with similar names.
174+
*/
175+
keyAnnotations?: Readonly<Record<string, string>>;
168176
};
169177

170178
type Row = { id: string; key: string; value: string };
@@ -191,6 +199,7 @@ export function EnvVarsEditor({
191199
focusKey,
192200
inheritedRows = [],
193201
inheritedRowsLabel = "build",
202+
keyAnnotations,
194203
}: EnvVarsEditorProps) {
195204
// Keys that render as their own special rows (required amber rows or
196205
// file-satisfied read-only rows). These must NEVER enter `rows` state —
@@ -406,6 +415,14 @@ export function EnvVarsEditor({
406415
</p>
407416
);
408417
})()}
418+
{keyAnnotations?.[key] ? (
419+
<p
420+
className="ml-1 text-xs text-muted-foreground"
421+
data-testid="env-vars-key-annotation"
422+
>
423+
{keyAnnotations[key]}
424+
</p>
425+
) : null}
409426
</div>
410427
);
411428
})}
@@ -596,6 +613,14 @@ export function EnvVarsEditor({
596613
</p>
597614
);
598615
})()}
616+
{row.key.length > 0 && keyAnnotations?.[row.key] ? (
617+
<p
618+
className="ml-1 text-xs text-muted-foreground"
619+
data-testid="env-vars-key-annotation"
620+
>
621+
{keyAnnotations[row.key]}
622+
</p>
623+
) : null}
599624
</div>
600625
);
601626
})}

‎desktop/src/features/agents/ui/PersonaAdvancedFields.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import type { PersonaBehaviorDraft } from "./personaBehaviorDraft";
66
import { isBuzzAgentRuntime } from "./buzzAgentConfig";
77
import { BuzzAgentModelTuningFields } from "./buzzAgentModelTuningFields";
88
import {
9+
CARD_MINT_KEY_ANNOTATIONS,
910
PERSONA_FIELD_CONTROL_CLASS,
1011
PERSONA_FIELD_SHELL_CLASS,
1112
PERSONA_LABEL_OPTIONAL_CLASS,
@@ -142,6 +143,7 @@ export function PersonaAdvancedFields({
142143
disabled={disabled}
143144
fileSatisfiedKeys={fileSatisfiedEnvKeys}
144145
hiddenKeys={hiddenEnvKeys}
146+
keyAnnotations={CARD_MINT_KEY_ANNOTATIONS}
145147
onChange={onEnvVarsChange}
146148
requiredKeys={requiredEnvKeys}
147149
value={envVars}

0 commit comments

Comments
 (0)