sprag-cli 3.46.1 → 3.47.0

package/src/commands/profile-map.js

@@ -0,0 +1,164 @@
+/**
+ * Subcommand: profile-map. LiteLLM 게이트웨이의 프로파일 ID → 모델 계열 매핑을
+ * 보여 주거나 갱신합니다.
+ *
+ *   sprag profile-map            # 캐시된 매핑을 사람이 읽을 수 있게 출력
+ *   sprag profile-map --json     # profile-map.json 원본을 그대로 출력
+ *   sprag profile-map --refresh  # LiteLLM GET /model/info 를 지금 호출해 캐시를 갱신
+ *   sprag profile-map --quiet    # 위 어느 모드든 출력을 억제 (스크립트/자식 프로세스용)
+ *
+ * 왜 이 명령이 필요한가: model-alias.js 의 학습 경로(투표)는 서브에이전트
+ * 실행이 MIN_VOTES 건 이상 쌓여야 판정이 서므로, 새 프로파일 ID 나 사용량이
+ * 적은 티어는 오랫동안(또는 영원히) role=null 로 남는다. 반면 LiteLLM
+ * `/model/info` 는 게이트웨이가 이미 알고 있는 배포 목록을 즉시 돌려주므로,
+ * 이 명령으로 그 매핑을 캐시해 두면 학습을 기다릴 필요가 없다. 실제 판정은
+ * model-alias.js 의 resolveModelAlias() 가 하고, 이 명령은 그 판정에 쓰이는
+ * 세 출처(override/gateway/learned)를 사람이 확인할 수 있게 보여 줄 뿐이다.
+ *
+ * 왜 --refresh 에서만 resolveKey() 를 부르는가: apiKeyHelper 가 인증 토큰의
+ * 수명(TTL)을 소유한다. 이 명령의 읽기 경로(플래그 없음/--json)는 캐시 파일만
+ * 보므로 키가 전혀 필요 없고, --refresh 는 사람이 터미널에서 직접 실행하는
+ * 경로라서 헬퍼가 Okta 로그인 창을 띄우더라도 괜찮다(사용자 지시). 얻은 키는
+ * fetch 요청 헤더에만 쓰고, 화면에 출력하거나 파일에 쓰지 않는다.
+ */
+
+export async function run({ args, hasFlag }) {
+  const { userLanguage } = await import('../config.js');
+  const { loadProfileMap, aliasForRole, MIN_VOTES } = await import('../model-alias.js');
+  const { gatewayBase, resolveKey } = await import('../gateway-auth.js');
+  const { readGatewayModelMap, refreshGatewayModelMap } = await import('../litellm-models.js');
+
+  const lang = userLanguage();
+  const ko = lang === 'ko';
+  const quiet = hasFlag('--quiet');
+  const say = (line) => { if (!quiet) console.log(line); };
+
+  const base = gatewayBase();
+  if (!base) {
+    // 오류가 아니다: 공식 API 를 직접 쓰는 사용자에게는 이 명령이 원래 할 일이
+    // 없다. --refresh 와 --json 도 base 없이는 의미가 없으므로 여기서 함께
+    // 걸러낸다.
+    say(ko
+      ? '게이트웨이가 감지되지 않았습니다 (ANTHROPIC_BASE_URL 필요). LiteLLM 등 게이트웨이 뒤에서 실행할 때만 쓰는 명령입니다.'
+      : 'No gateway detected (ANTHROPIC_BASE_URL required). This command only matters behind a gateway such as LiteLLM.');
+    return;
+  }
+
+  if (hasFlag('--refresh')) {
+    const key = resolveKey();
+    if (!key) {
+      say(ko
+        ? 'apiKeyHelper 가 토큰을 내주지 못했습니다. 인증을 마친 뒤 다시 실행하십시오.'
+        : 'apiKeyHelper did not return a token. Authenticate, then run this again.');
+      process.exitCode = 1;
+      return;
+    }
+    const result = await refreshGatewayModelMap({ base, key });
+    if (!result) {
+      say(ko
+        ? `LiteLLM 에서 모델 정보를 가져오지 못했습니다 (GET ${base}/model/info). CTS_DEBUG=1 로 다시 실행하면 원인이 보입니다.`
+        : `Could not fetch model info from LiteLLM (GET ${base}/model/info). Re-run with CTS_DEBUG=1 to see why.`);
+      process.exitCode = 1;
+      return;
+    }
+    const resolved = Object.keys(result.aliases).length;
+    say(ko
+      ? `배포 ${result.count}건 중 ${resolved}개 키를 해석했습니다${result.skipped.length ? ` (미해석 ${result.skipped.length}건)` : ''}.`
+      : `Resolved ${resolved} key(s) out of ${result.count} deployment(s)${result.skipped.length ? ` (${result.skipped.length} unresolved)` : ''}.`);
+    if (result.skipped.length) {
+      say(ko
+        ? `  미해석 model_name: ${result.skipped.join(', ')}`
+        : `  Unresolved model_name: ${result.skipped.join(', ')}`);
+    }
+    return;
+  }
+
+  const map = loadProfileMap();
+  const gatewayMap = readGatewayModelMap();
+
+  if (hasFlag('--json')) {
+    say(JSON.stringify(map, null, 2));
+    return;
+  }
+
+  say(ko ? `게이트웨이: ${base}` : `Gateway: ${base}`);
+
+  if (gatewayMap) {
+    const fetchedMs = Date.parse(gatewayMap.fetchedAt);
+    const ageMin = Number.isFinite(fetchedMs) ? Math.max(0, Math.round((Date.now() - fetchedMs) / 60000)) : null;
+    const resolved = Object.keys(gatewayMap.aliases || {}).length;
+    say(ko
+      ? `조회 ${ageMin === null ? '알 수 없음' : `${ageMin}분 전`} · 배포 ${gatewayMap.count}건 · 해석된 키 ${resolved}개`
+      : `checked ${ageMin === null ? 'unknown' : `${ageMin}m ago`} · ${gatewayMap.count} deployment(s) · ${resolved} key(s) resolved`);
+  } else {
+    say(ko
+      ? '게이트웨이 모델맵이 아직 없습니다. `sprag profile-map --refresh` 로 지금 가져오십시오.'
+      : 'No gateway model map cached yet. Fetch it now with `sprag profile-map --refresh`.');
+  }
+
+  const overrideEntries = Object.entries(map.modelAliases || {});
+  if (overrideEntries.length) {
+    say(ko ? '\n사용자 매핑 (modelAliases):' : '\nUser overrides (modelAliases):');
+    for (const [pattern, alias] of overrideEntries) {
+      say(`  ${pattern} → ${alias} (override)`);
+    }
+  }
+
+  const gwAliases = gatewayMap?.aliases || {};
+  const learned = map.learned || {};
+  // Set 으로 합치는 이유: 같은 프로파일 ID 가 두 출처 모두에 나타날 수 있고,
+  // 그때 서로 다른 답을 준다면 그 자체가 사용자에게 알려야 할 신호다(학습이
+  // 틀렸거나 게이트웨이 설정이 바뀌었다는 뜻).
+  const keys = [...new Set([...Object.keys(gwAliases), ...Object.keys(learned)])].sort();
+
+  if (keys.length) {
+    say(ko ? '\n게이트웨이 · 학습 매핑:' : '\nGateway & learned mappings:');
+    for (const key of keys) {
+      const gwAlias = gwAliases[key];
+      const entry = learned[key];
+
+      if (gwAlias) {
+        say(`  ${key} → ${gwAlias} (gateway)`);
+        if (entry?.role) {
+          const learnedAlias = aliasForRole(entry.role);
+          if (learnedAlias && learnedAlias !== gwAlias) {
+            say(ko
+              ? `    ⚠ 학습 결과는 ${learnedAlias} 였습니다. 학습이 틀렸거나 게이트웨이 설정이 바뀌었을 수 있습니다.`
+              : `    ⚠ the learned result was ${learnedAlias}. Either the learning was wrong, or the gateway config changed.`);
+          }
+        } else if (entry && !entry.role) {
+          say(ko
+            ? `    학습은 표 ${entry.total || 0}개로 판정 대기였지만, 게이트웨이가 이미 해석했으므로 더 이상 문제되지 않습니다.`
+            : `    Learning was still undecided at ${entry.total || 0} vote(s), but the gateway already resolves this, so it is no longer an issue.`);
+        }
+        continue;
+      }
+
+      if (entry?.role) {
+        const learnedAlias = aliasForRole(entry.role);
+        say(learnedAlias
+          ? `  ${key} → ${learnedAlias} (learned · ${entry.role})`
+          : (ko ? `  ${key} → ${entry.role} 역할 · 별칭 미확정 (learned)` : `  ${key} → ${entry.role} role · alias undecided (learned)`));
+      } else if (entry) {
+        say(ko
+          ? `  ${key} → 표 ${entry.total || 0}개 · 판정 대기 (기준 ${MIN_VOTES}개, learned)`
+          : `  ${key} → ${entry.total || 0} vote(s) · undecided (needs ${MIN_VOTES}, learned)`);
+      }
+    }
+  }
+
+  if (!overrideEntries.length && !keys.length) {
+    say(ko
+      ? '\n등록된 매핑이 없습니다.'
+      : '\nNo mappings recorded yet.');
+  }
+
+  if (gatewayMap?.skipped?.length) {
+    say(ko
+      ? `\n게이트웨이가 계열명을 알아내지 못한 배포: ${gatewayMap.skipped.join(', ')}.`
+      : `\nDeployments the gateway could not name a family for: ${gatewayMap.skipped.join(', ')}.`);
+    say(ko
+      ? '  profile-map.json 의 modelAliases 에 해당 이름을 직접 매핑하십시오.'
+      : '  Map those names directly under modelAliases in profile-map.json.');
+  }
+}

package/src/commands/route-scan.js

@@ -183,15 +183,19 @@ export async function run({ args, hasFlag, numArg }) {
         const { MIN_VOTES } = await import('../model-alias.js');
         const learning = scan.unresolvedRuns < MIN_VOTES;
         const remedyKo = learning
-          ? `\n  위임이 ${MIN_VOTES}건 이상 쌓이면 자동으로 해석될 수 있습니다. 그때까지 기다렸다가 다시 확인하고,`
-            + '\n  게이트웨이가 모델 이름을 아예 알려 주지 않는 환경이라면 profile-map.json 의 modelAliases 에'
-            + '\n  해당 ID 를 매핑한 뒤 route-scan --refresh 를 실행하십시오.'
-          : '\n  profile-map.json 의 modelAliases 에 해당 ID 를 매핑한 뒤 route-scan --refresh 를 실행하십시오.';
+          ? `\n  위임이 ${MIN_VOTES}건 이상 쌓이면 자동으로 해석될 수 있습니다. 그때까지 기다리는 동안`
+            + '\n  sprag profile-map --refresh 를 먼저 실행해 보십시오. LiteLLM 게이트웨이라면 배포 목록에서'
+            + '\n  매핑을 곧바로 가져옵니다. 그래도 남는 ID 는 profile-map.json 의 modelAliases 에 직접'
+            + '\n  매핑한 뒤 route-scan --refresh 를 실행하십시오.'
+          : '\n  sprag profile-map --refresh 를 먼저 실행해 보십시오. LiteLLM 게이트웨이라면 배포 목록에서 매핑을 곧바로 가져옵니다.'
+            + '\n  그래도 남는 ID 는 profile-map.json 의 modelAliases 에 직접 매핑한 뒤 route-scan --refresh 를 실행하십시오.';
         const remedyEn = learning
-          ? `\n  These may resolve on their own once ${MIN_VOTES} or more delegated runs accumulate — check again then.`
-            + '\n  If the gateway never reports a model name at all, map the id under modelAliases in'
+          ? `\n  These may resolve on their own once ${MIN_VOTES} or more delegated runs accumulate; check again then.`
+            + '\n  Meanwhile, try sprag profile-map --refresh first: on a LiteLLM gateway it pulls the mapping'
+            + '\n  straight from the deployment list. Anything still left over, map it under modelAliases in'
             + '\n  profile-map.json and run route-scan --refresh.'
-          : '\n  Map it under modelAliases in profile-map.json, then run route-scan --refresh.';
+          : '\n  Try sprag profile-map --refresh first: on a LiteLLM gateway it pulls the mapping straight from the deployment list.'
+            + '\n  Anything still left over, map it under modelAliases in profile-map.json and run route-scan --refresh.';
         console.log(lang === 'ko'
           ? `\n⚠ 해석되지 않은 모델 ID 때문에 위임 ${scan.unresolvedRuns}건이 집계에서 제외됐습니다${ids ? ` (${ids})` : ''}.` + remedyKo
           : `\n⚠ ${scan.unresolvedRuns} delegated run(s) were excluded — unpriceable model id${ids ? ` (${ids})` : ''}.` + remedyEn);

package/src/gateway-auth.js

@@ -0,0 +1,86 @@
+/**
+ * gateway-auth: gateway address detection + auth-token resolution, split out
+ * as a leaf module so other modules can read the LiteLLM gateway's address
+ * and key without risking a circular import.
+ *
+ * Why this file exists: src/formatters/statusline.js imports MIN_VOTES from
+ * src/model-alias.js, and src/litellm-budget.js imports from
+ * formatters/statusline.js. If model-alias.js also needed gatewayBase() from
+ * litellm-budget.js (to resolve gateway-supplied aliases), the import graph
+ * would close a cycle: model-alias.js → litellm-budget.js →
+ * formatters/statusline.js → model-alias.js. This module carries no
+ * dependency on either side of that cycle, so both litellm-budget.js and
+ * model-alias.js can import it safely.
+ *
+ * This module never persists the token it resolves. apiKeyHelper owns that
+ * token's lifecycle (short TTL, refreshed on its own schedule); a cached
+ * copy here would drift out of sync with that lifecycle. Callers receive the
+ * key as a return value only and are expected to pass it along as a plain
+ * argument, not to write it to disk, argv, logs, or error messages.
+ */
+
+import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { debug } from './debug.js';
+
+export const HELPER_TIMEOUT_MS = 10000;
+
+/**
+ * 게이트웨이 주소만 판정합니다. 캐시만 읽는 경로는 키가 필요하지 않으므로,
+ * 키 확보와 주소 판정을 분리해 둡니다. apiKeyHelper 로만 인증하는 환경에는
+ * 환경변수에 토큰이 없어서, 키를 함께 요구하면 렌더 경로가 통째로 탈락합니다.
+ */
+export function gatewayBase(env = process.env) {
+  const base = (env.ANTHROPIC_BASE_URL || '').trim().replace(/\/+$/, '');
+  if (!base) return null;
+  // 공식 엔드포인트를 그대로 가리키면 게이트웨이가 아닙니다.
+  if (/^https?:\/\/api\.anthropic\.com/i.test(base)) return null;
+  return base;
+}
+
+/**
+ * Claude Code 와 같은 방식으로 apiKeyHelper 를 실행해 토큰을 얻습니다.
+ * 환경변수에 토큰을 두지 않고 헬퍼 스크립트로 매번 발급받는 구성이 공식 인증
+ * 방식 가운데 하나이며, 그 구성에서는 statusline 자식 프로세스의 process.env
+ * 안에 토큰이 존재하지 않습니다.
+ *
+ * 헬퍼 실행은 비용이 있으므로 갱신 경로(5분에 한 번 뜨는 detached 자식)에서만
+ * 부릅니다. 수 초 간격으로 도는 렌더 경로에서 부르면 통계선이 그만큼 느려집니다.
+ */
+export function keyFromApiKeyHelper(cwd = process.cwd()) {
+  const candidates = [
+    join(cwd, '.claude', 'settings.local.json'),
+    join(cwd, '.claude', 'settings.json'),
+    join(homedir(), '.claude', 'settings.json'),
+  ];
+  for (const p of candidates) {
+    let helper;
+    try {
+      helper = JSON.parse(readFileSync(p, 'utf8'))?.apiKeyHelper;
+    } catch {
+      continue;
+    }
+    if (typeof helper !== 'string' || !helper.trim()) continue;
+    try {
+      const out = execSync(helper, {
+        encoding: 'utf8',
+        timeout: HELPER_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      // 진행 로그를 함께 출력하는 헬퍼가 있으므로 마지막 비어 있지 않은 줄을 취합니다.
+      const token = out.trim().split(/\r?\n/).filter(Boolean).pop();
+      if (token) return token.trim();
+    } catch (e) {
+      debug('gateway-auth:helper', e);
+    }
+  }
+  return null;
+}
+
+/** 환경변수 토큰을 먼저 보고, 없으면 apiKeyHelper 로 내려갑니다. */
+export function resolveKey(env = process.env) {
+  const direct = (env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || '').trim();
+  return direct || keyFromApiKeyHelper();
+}

package/src/litellm-budget.js

@@ -15,42 +15,39 @@
  * 엔드포인트는 LiteLLM의 `GET {base}/key/info` 이며, 호출한 키 자신의 정보를
  * 돌려줍니다. 응답의 info.max_budget / info.spend / info.budget_reset_at 을
  * 사용합니다. max_budget 이 null 이면(무제한 키) 게이지를 만들지 않습니다.
+ *
+ * 이 파일은 resolveKey() 가 돌려준 토큰을 캐시 파일에 쓰지 않습니다. 그 키는
+ * apiKeyHelper 가 소유한 TTL 을 그대로 따라야 하므로, 여기서 사본을 만들면
+ * 헬퍼의 만료·재발급 주기와 어긋납니다(사용자 지시).
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { spawn, execSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { userDataDir } from './paths.js';
 import { gaugeBar, formatMoney } from './formatters/statusline.js';
 import { labelForKey } from './window-labels.js';
 import { formatResetClock } from './format-time.js';
 import { cliEntryPath } from './update-check.js';
 import { debug } from './debug.js';
+// 게이트웨이 주소 판정과 키 확보는 leaf 모듈로 옮겼습니다: model-alias.js 가
+// 게이트웨이 별칭을 조회하려면 이 함수들이 필요한데, model-alias.js 가 이
+// 파일을 직접 import 하면 model-alias.js → litellm-budget.js →
+// formatters/statusline.js → model-alias.js 순환이 생깁니다. 이 파일은 기존
+// 호출부(예: bin/cli.js) 와의 호환을 위해 같은 이름으로 재수출만 합니다.
+import { HELPER_TIMEOUT_MS, gatewayBase, keyFromApiKeyHelper, resolveKey } from './gateway-auth.js';
+
+export { HELPER_TIMEOUT_MS, gatewayBase, keyFromApiKeyHelper, resolveKey };
 
 // 예산은 분 단위로 변하지 않습니다. 5분이면 게이지 용도로 충분히 신선하고,
 // 통계선 렌더(수 초 간격)가 프록시를 두들기지 않습니다.
 const CHECK_INTERVAL_MS = 5 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 5000;
-const HELPER_TIMEOUT_MS = 10000;
 
 export function budgetStatePath() {
   return join(userDataDir(), 'litellm-budget.json');
 }
 
-/**
- * 게이트웨이 주소만 판정합니다. 캐시만 읽는 경로는 키가 필요하지 않으므로,
- * 키 확보와 주소 판정을 분리해 둡니다. apiKeyHelper 로만 인증하는 환경에는
- * 환경변수에 토큰이 없어서, 키를 함께 요구하면 렌더 경로가 통째로 탈락합니다.
- */
-export function gatewayBase(env = process.env) {
-  const base = (env.ANTHROPIC_BASE_URL || '').trim().replace(/\/+$/, '');
-  if (!base) return null;
-  // 공식 엔드포인트를 그대로 가리키면 게이트웨이가 아닙니다.
-  if (/^https?:\/\/api\.anthropic\.com/i.test(base)) return null;
-  return base;
-}
-
 /** 게이트웨이 주소와 키를 함께 돌려줍니다. 둘 중 하나라도 없으면 null. */
 export function gatewayEnv(env = process.env) {
   const base = gatewayBase(env);
@@ -60,51 +57,6 @@ export function gatewayEnv(env = process.env) {
   return { base, key };
 }
 
-/**
- * Claude Code 와 같은 방식으로 apiKeyHelper 를 실행해 토큰을 얻습니다.
- * 환경변수에 토큰을 두지 않고 헬퍼 스크립트로 매번 발급받는 구성이 공식 인증
- * 방식 가운데 하나이며, 그 구성에서는 statusline 자식 프로세스의 process.env
- * 안에 토큰이 존재하지 않습니다.
- *
- * 헬퍼 실행은 비용이 있으므로 갱신 경로(5분에 한 번 뜨는 detached 자식)에서만
- * 부릅니다. 수 초 간격으로 도는 렌더 경로에서 부르면 통계선이 그만큼 느려집니다.
- */
-export function keyFromApiKeyHelper(cwd = process.cwd()) {
-  const candidates = [
-    join(cwd, '.claude', 'settings.local.json'),
-    join(cwd, '.claude', 'settings.json'),
-    join(homedir(), '.claude', 'settings.json'),
-  ];
-  for (const p of candidates) {
-    let helper;
-    try {
-      helper = JSON.parse(readFileSync(p, 'utf8'))?.apiKeyHelper;
-    } catch {
-      continue;
-    }
-    if (typeof helper !== 'string' || !helper.trim()) continue;
-    try {
-      const out = execSync(helper, {
-        encoding: 'utf8',
-        timeout: HELPER_TIMEOUT_MS,
-        stdio: ['ignore', 'pipe', 'ignore'],
-      });
-      // 진행 로그를 함께 출력하는 헬퍼가 있으므로 마지막 비어 있지 않은 줄을 취합니다.
-      const token = out.trim().split(/\r?\n/).filter(Boolean).pop();
-      if (token) return token.trim();
-    } catch (e) {
-      debug('litellm-budget:helper', e);
-    }
-  }
-  return null;
-}
-
-/** 환경변수 토큰을 먼저 보고, 없으면 apiKeyHelper 로 내려갑니다. */
-export function resolveKey(env = process.env) {
-  const direct = (env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || '').trim();
-  return direct || keyFromApiKeyHelper();
-}
-
 export function readBudgetState() {
   try {
     const s = JSON.parse(readFileSync(budgetStatePath(), 'utf8'));
@@ -306,17 +258,22 @@ export function pickBudgetSource(keyInfo, userInfo) {
  * 실제로 LiteLLM에 물어보고 캐시를 갱신합니다. detached 자식과
  * `litellm-budget --refresh` 명령만 호출합니다.
  * /key/info(키·소속 식별)와 /user/info(팀 멤버십 예산)를 함께 조회합니다.
+ *
+ * `key` 를 넘기면 resolveKey() 를 다시 부르지 않고 그 값을 그대로 씁니다.
+ * 호출자(bin/cli.js 의 --refresh 분기)가 apiKeyHelper 를 한 번만 불러 이
+ * 함수와 게이트웨이 모델맵 갱신 양쪽에 같은 키를 재사용할 수 있도록 하는
+ * 목적입니다. 어느 경로든 키는 이 함수의 상태 파일에 기록되지 않습니다.
  */
-export async function refreshBudgetState(env = process.env, fetchImpl = fetch) {
+export async function refreshBudgetState(env = process.env, fetchImpl = fetch, key = null) {
   const base = gatewayBase(env);
   if (!base) return null;
-  const key = resolveKey(env);
-  if (!key) return null;
+  const resolvedKey = key || resolveKey(env);
+  if (!resolvedKey) return null;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   const headers = {
     accept: 'application/json',
-    authorization: `Bearer ${key}`,
+    authorization: `Bearer ${resolvedKey}`,
   };
   try {
     // /key/info 는 커스텀 인증(JWT)을 쓰는 배포에서 404 가 정상입니다. 발급된