feat(ux): API-key guidance + save_api_key — no more silent "can't search"#98
Merged
Conversation
…rch"
The failure this removes: a user sets up models, asks for a web task, and Firecrawl/Tavily/Brave
are skipped for lack of a key — the task limps on the keyless fallback or fails, and the user
never learns why or what to do.
- key-guidance.ts (PURE): registry of web service keys (Firecrawl/Tavily/Brave — URL, free-tier,
what each unlocks) + keyGuidance(env) + missingWebKeysGuidance(env) — fires only when NO
content-grade key is set (one key set → no nagging).
- save_api_key tool: when the user pastes a key in chat ("set it for me"), stores it via the
existing setEnvKey (~/.qodex/.env, chmod 600, atomic) AND loads it into process.env so the
blocked task retries in the SAME session. Validates the var name/value; the value is never
echoed or logged.
- web_search failure paths + the three keyed backends now return that guidance: get a free key
at <url> → paste it in chat (agent saves + retries) or add to ~/.qodex/.env.
- Dashboard Health gains a "Web search" badge: green when any content-grade key is set; else
"keyless fallback only — get a free Firecrawl key at …" (input optional → old callers/tests
untouched).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User-friendliness fix for the "models are set up but web tools silently can't work" trap.
The flow it creates
~/.qodex/.env/exportit.save_api_keytool: stored via the existingsetEnvKey(~/.qodex/.env, chmod 600, atomic, same placeprovider adduses) and loaded intoprocess.envlive — the blocked step retries in the same session, no restart.Pieces
key-guidance.ts(PURE): service registry +keyGuidance/webKeyStatus/missingWebKeysGuidance(fires only when zero content-grade keys are set — one key set → no nagging)save_api_keytool: validates env-var name + value shape (rejects whitespace pastes); never echoes or logs the value; use-only-with-a-user-pasted-key in the descriptionweb_searchfailure summary + Firecrawl/Tavily/Brave key errors now carry the guidance+9 tests (guidance content, no-nag gate, health badge, tool validation incl. never-echo). Full suite green, tsc clean.