From 13e23e0fc5b55c10af16e00a82535ca8c71a161f Mon Sep 17 00:00:00 2001 From: Tam Nhu Tran Date: Sat, 27 Jun 2026 10:55:11 -0400 Subject: [PATCH] docs(cliproxy): document strip-vs-overlay launch-settings siblings and model-key superset Cross-reference the two helpers that solve the persisted-settings-env override (overlay in launch-settings.ts, strip in openai-compat-launch-settings.ts) and mark shell-executor's ANTHROPIC_MODEL_ENV_KEYS as the intentional superset distinct from the 4-key list in extended-context-utils. See issue #1609. --- src/cliproxy/executor/launch-settings.ts | 7 +++++++ src/utils/openai-compat-launch-settings.ts | 6 ++++++ src/utils/shell-executor.ts | 4 ++++ 3 files changed, 17 insertions(+) diff --git a/src/cliproxy/executor/launch-settings.ts b/src/cliproxy/executor/launch-settings.ts index c834e1ae..5e33bf7e 100644 --- a/src/cliproxy/executor/launch-settings.ts +++ b/src/cliproxy/executor/launch-settings.ts @@ -27,6 +27,13 @@ import * as path from 'path'; import { ANTHROPIC_MODEL_ENV_KEYS, ANTHROPIC_ROUTING_ENV_KEYS } from '../../utils/shell-executor'; +// SIBLING HELPER: src/utils/openai-compat-launch-settings.ts solves the same +// "persisted --settings env clobbers runtime routing env" problem by STRIPPING +// routing keys (process env wins by absence). This module instead OVERLAYS the +// resolved values (settings wins by overwrite). The two differ intentionally: +// strip vs overlay diverge when a key is present on disk but absent from the +// process env. Unifying them needs an explicit force-absent API — see issue #1609. + /** * Environment keys that control provider routing/model selection and are read * by Claude from the settings `env` block. These must reflect the resolved diff --git a/src/utils/openai-compat-launch-settings.ts b/src/utils/openai-compat-launch-settings.ts index bfb0887d..1f305419 100644 --- a/src/utils/openai-compat-launch-settings.ts +++ b/src/utils/openai-compat-launch-settings.ts @@ -10,6 +10,12 @@ export interface OpenAICompatLaunchSettings { cleanup: () => void; } +// SIBLING HELPER: src/cliproxy/executor/launch-settings.ts (prepareLaunchSettings) +// solves the same problem by OVERLAYING resolved routing values instead of +// stripping them. This strip-based variant is required where callers deliberately +// delete a routing key (e.g. ANTHROPIC_API_KEY in settings-flow) and need it +// ABSENT from the launch settings. Do not unify without an explicit force-absent +// key list — see issue #1609. export function createOpenAICompatLaunchSettings( settingsPath: string, settings: Settings diff --git a/src/utils/shell-executor.ts b/src/utils/shell-executor.ts index 58d459f6..68a9f1f6 100644 --- a/src/utils/shell-executor.ts +++ b/src/utils/shell-executor.ts @@ -40,6 +40,10 @@ export const ANTHROPIC_ROUTING_ENV_KEYS = [ 'ANTHROPIC_API_KEY', ]; const ANTHROPIC_ROUTING_ENV_KEY_SET = new Set(ANTHROPIC_ROUTING_ENV_KEYS); +// NOTE: This is the intentional routing-overlay SUPERSET of model env keys +// (includes ANTHROPIC_SMALL_FAST_MODEL). A separate 4-key `ANTHROPIC_MODEL_ENV_KEYS` +// exists in src/shared/extended-context-utils.ts (re-exported as MODEL_ENV_VAR_KEYS). +// The two are NOT interchangeable — import deliberately by purpose. See issue #1609. export const ANTHROPIC_MODEL_ENV_KEYS = [ 'ANTHROPIC_MODEL', 'ANTHROPIC_DEFAULT_OPUS_MODEL',