elanous 0.2.23 → 0.2.25

package/src/llm/bedrock.ts

@@ -8,7 +8,18 @@
 //    📏 출처: https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock (2026-10-10 확인)
 //    — *"Unlike the InvokeModel-based integration, this endpoint uses standard SSE streaming and the same
 //    request body shape as Anthropic's first-party API."* ⇒ 몸(`cache_control` 포함)·SSE 파서를 «바이트 그대로» 재사용한다.
-//    (레거시 InvokeModel 은 AWS event-stream 이진 인코딩이라 별도 디코더가 필요하다 — 안 쓴다.)
+//    (레거시 InvokeModel 은 AWS event-stream 이진 인코딩이라 별도 디코더가 필요하다.)
+//
+// ⭐ BEDROCK-RUNTIME-PATH(2026-10-11) — «경로» 둘. 모델 표의 `route` 칸이 고른다.
+//    · `mantle`  = 위 메시지 엔드포인트. 📏 10-11 실측: mantle `GET /v1/models` 에 Sonnet/Haiku 5.5 가 «없다»
+//                 (ap-northeast-2 = sonnet-5 뿐 · us-east-1 = opus-5-5·sonnet-5·haiku-4-5) ⇒ `anthropic.claude-sonnet-5-5` 는 404.
+//    · `runtime` = `bedrock-runtime.{region}.amazonaws.com/model/{id}/invoke-with-response-stream` · SigV4 서비스 `bedrock`.
+//                 몸은 같은 Anthropic Messages 꼴(`anthropic_version: bedrock-2023-05-31` · `model`·`stream` 은 빼고 URL 로) —
+//                 `cache_control` 자리가 mantle 과 «같다». 응답은 eventstream 이진 프레임(`./bedrock-eventstream.ts`).
+//                 📏 전역 추론 프로필 `global.anthropic.claude-{sonnet,haiku}-5-5` 가 ap-northeast-2 에서 200.
+//    · `mantle-openai` = 같은 mantle 호스트의 OpenAI chat.completions 호환 엔드포인트(BEDROCK-MODELS-ALL · 비-Anthropic 모델).
+//                 경로 `/openai/v1/chat/completions`(OpenAI 계열) · `/v1/chat/completions`(그 밖) · SigV4 서비스 `bedrock-mantle`
+//                 · 고정 리전 us-east-1(📏 MK 실측 6/6 200) · 응답은 OpenAI SSE.
 //
 // ⛔ 자격 «값»은 이 모듈 밖으로 나가지 않는다 — 로그·에러·반환값 어디에도 싣지 않는다(값 미열람 원칙).
 //    가용 판정은 «신호가 있나»(이름·파일 존재)만 보고, 실제 해석은 SDK 기본 자격 체인이 한다.
@@ -20,31 +31,81 @@ import { join } from 'node:path';
 /** 사람용 별칭 접두. `bedrock/claude-sonnet-5-5` → `anthropic.claude-sonnet-5-5`. */
 const BEDROCK_ALIAS_PREFIX = 'bedrock/';
 
+/** runtime(InvokeModel*) 몸의 `anthropic_version` 값 — Bedrock 의 Anthropic Messages 고정값. */
+const BEDROCK_RUNTIME_ANTHROPIC_VERSION = 'bedrock-2023-05-31';
+
+/** runtime 경로의 SigV4 서명 서비스 이름(`bedrock-runtime` 호스트도 서명 스코프는 `bedrock`). */
+const BEDROCK_RUNTIME_SIGV4_SERVICE = 'bedrock';
+
 /** Bedrock 메시지 엔드포인트의 `anthropic-version` 헤더값(출처 문서의 cURL 예시 그대로). */
 const BEDROCK_ANTHROPIC_VERSION = '2023-06-01';
 
 /** SigV4 서명 서비스 이름(출처 문서 cURL `--aws-sigv4 "aws:amz:us-east-1:bedrock-mantle"`). */
 const BEDROCK_SIGV4_SERVICE = 'bedrock-mantle';
 
+/** 어느 엔드포인트로 보내나 — `mantle`(Anthropic 메시지 엔드포인트) · `runtime`(InvokeModelWithResponseStream) ·
+ *  `mantle-openai`(같은 mantle 호스트의 OpenAI chat.completions 호환 엔드포인트 — 비-Anthropic 모델). */
+export type BedrockRoute = 'mantle' | 'runtime' | 'mantle-openai';
+
+/** mantle-openai 경로 조각 — OpenAI 계열(`openai.gpt-6-*`)만 `/openai` 접두, 나머지는 `/v1`. */
+export type BedrockOpenAIPath = '/openai/v1/chat/completions' | '/v1/chat/completions';
+
 export interface BedrockModelEntry {
-  /** 와이어 id(`model` 필드). */
+  /** 와이어 id(mantle = `model` 필드 · runtime = URL 의 모델/추론 프로필 id). */
   readonly id: string;
   /** 같은 모델의 1st-party id — 계열 판정(adaptive thinking·vision·temperature)에 쓴다. */
   readonly canonical: string;
   readonly tier: 'cheap' | 'balanced' | 'flagship';
   readonly supportsThinking: boolean;
+  /** ⭐ 경로 칸 — 이 id 를 «실제로 내는» 엔드포인트. mantle 에 없는 id 를 mantle 로 보내지 않는다. */
+  readonly route: BedrockRoute;
+  /** `route: 'mantle-openai'` 행만 — chat.completions 경로. */
+  readonly openaiPath?: BedrockOpenAIPath;
+  /** `route: 'mantle-openai'` 행만 — 이 모델을 내는 고정 리전(📏 MK 실측 us-east-1 mantle 6/6 200). 사용자 리전과 무관하다. */
+  readonly region?: string;
 }
 
-/** 📏 id 출처: https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock «Supported models» 표
- *  (2026-10-10 확인 · `anthropic.` 접두). ⚠️ 접근 조건은 계정마다 다르다(Opus/Sonnet/Haiku 5.5 = «See Access»).
- *  표 밖 id(지역 추론 프로필 `us.anthropic.…` 등)는 `anthropic.` 꼴이면 그대로 통과한다 — 설정으로 덮을 수 있다. */
+const MANTLE_OPENAI_REGION = 'us-east-1';
+
+function openaiRow(id: string, tier: BedrockModelEntry['tier'], openaiPath: BedrockOpenAIPath): BedrockModelEntry {
+  return { id, canonical: id, tier, supportsThinking: false, route: 'mantle-openai', openaiPath, region: MANTLE_OPENAI_REGION };
+}
+
+/** ⭐ 모델 표 = «경로» 결정표(BEDROCK-RUNTIME-PATH · 2026-10-11).
+ *  · 5.5 계열 = 전역 추론 프로필(`global.anthropic.…`) ⊕ runtime — 📏 `aws bedrock list-inference-profiles`(ap-northeast-2)에
+ *    셋 다 있고, sonnet/haiku 는 `converse` 200 실측. opus-5-5 는 «목록에 있음»까지만 쟀다(호출 0).
+ *  · mantle 이 «실제로 내는» 모델(`GET /v1/models` 실측: sonnet-5)은 mantle 그대로.
+ *  사람 별칭(`claude-sonnet-5-5`·`bedrock/claude-sonnet-5-5`·접두 없는 `anthropic.claude-sonnet-5-5`)은 canonical 로 이 표를 찾아 `id` 로 푼다.
+ *  표 밖 id: 지역/전역 접두(`us.`·`apac.`·`global.`…)가 붙었으면 runtime, 아니면 종전대로 mantle(엔드포인트가 판정). */
 export const BEDROCK_MODELS: readonly BedrockModelEntry[] = [
-  { id: 'anthropic.claude-sonnet-5-5', canonical: 'claude-sonnet-5-5', tier: 'balanced', supportsThinking: true },
-  { id: 'anthropic.claude-haiku-5-5', canonical: 'claude-haiku-5-5', tier: 'cheap', supportsThinking: true },
-  { id: 'anthropic.claude-opus-5-5', canonical: 'claude-opus-5-5', tier: 'flagship', supportsThinking: true },
+  { id: 'global.anthropic.claude-sonnet-5-5', canonical: 'claude-sonnet-5-5', tier: 'balanced', supportsThinking: true, route: 'runtime' },
+  { id: 'global.anthropic.claude-haiku-5-5', canonical: 'claude-haiku-5-5', tier: 'cheap', supportsThinking: true, route: 'runtime' },
+  { id: 'global.anthropic.claude-opus-5-5', canonical: 'claude-opus-5-5', tier: 'flagship', supportsThinking: true, route: 'runtime' },
+  { id: 'anthropic.claude-sonnet-5', canonical: 'claude-sonnet-5', tier: 'balanced', supportsThinking: true, route: 'mantle' },
+  // 비-Anthropic = mantle OpenAI 호환 경로(IAM 변경 없이 가능). runtime Converse 모델(GLM 5.3·Kimi K3·Grok 4.7)은 IAM 결정 뒤라 «아직 없다».
+  openaiRow('openai.gpt-6-sol', 'flagship', '/openai/v1/chat/completions'),
+  openaiRow('openai.gpt-6-luna', 'balanced', '/openai/v1/chat/completions'),
+  openaiRow('zai.glm-5', 'flagship', '/v1/chat/completions'),
+  openaiRow('zai.glm-4.7-flash', 'cheap', '/v1/chat/completions'),
+  openaiRow('deepseek.v3.2', 'balanced', '/v1/chat/completions'),
+  openaiRow('moonshotai.kimi-k2.5', 'balanced', '/v1/chat/completions'),
+  openaiRow('qwen.qwen3-coder-next', 'balanced', '/v1/chat/completions'),
+  openaiRow('minimax.minimax-m2.5', 'cheap', '/v1/chat/completions'),
+  openaiRow('mistral.devstral-2-123b', 'balanced', '/v1/chat/completions'),
 ];
 
-export const BEDROCK_DEFAULT_MODEL = 'anthropic.claude-sonnet-5-5';
+export const BEDROCK_DEFAULT_MODEL = 'global.anthropic.claude-sonnet-5-5';
+
+/** 지역/전역 추론 프로필 접두(`global.`·`us.`·`eu.`·`apac.`·`jp.`·`au.` …) — 이 꼴은 runtime 만 받는다. */
+const BEDROCK_INFERENCE_PROFILE_PREFIX = /^[a-z]{2,6}\.anthropic\./i;
+
+/** 와이어 id → 경로. 표에 있으면 표의 칸, 추론 프로필 접두면 runtime, 그 밖은 종전대로 mantle. */
+export function bedrockRouteFor(wireId: string): BedrockRoute {
+  const id = wireId.trim();
+  const entry = BEDROCK_MODELS.find((m) => m.id === id);
+  if (entry) return entry.route;
+  return BEDROCK_INFERENCE_PROFILE_PREFIX.test(id) ? 'runtime' : 'mantle';
+}
 
 /** 지역/전역 추론 프로필 접두(`us.`·`eu.`·`jp.`·`au.`·`apac.`·`global.`)를 허용한다. */
 const BEDROCK_CLAUDE_ID = /^(?:[a-z]{2,6}\.)?anthropic\.claude-[a-z0-9.\-:]+$/i;
@@ -54,19 +115,28 @@ export function isBedrockModelId(model: string | undefined): boolean {
   const m = (model ?? '').trim();
   if (!m) return false;
   if (m.toLowerCase().startsWith(BEDROCK_ALIAS_PREFIX)) return true;
-  return BEDROCK_CLAUDE_ID.test(m);
+  return BEDROCK_CLAUDE_ID.test(m) || BEDROCK_MODELS.some((e) => e.route === 'mantle-openai' && e.id === m);
+}
+
+/** 와이어 id → 고정 리전(mantle-openai 행만). 그 밖은 `fallback`(사용자 리전). */
+export function bedrockRegionFor(wireId: string, fallback: string): string {
+  const entry = BEDROCK_MODELS.find((m) => m.id === wireId.trim());
+  return entry?.route === 'mantle-openai' && entry.region ? entry.region : fallback;
 }
 
-/** 입력 → 와이어 id. `bedrock/claude-x` · `claude-x`(provider=bedrock 일 때) → `anthropic.claude-x`.
- *  이미 `anthropic.`(접두 포함) 꼴이면 그대로. 그 밖은 그대로 돌려준다(엔드포인트가 판정한다). */
+/** 입력 → 와이어 id. `bedrock/claude-x` · `claude-x`(provider=bedrock 일 때) · 접두 없는 `anthropic.claude-x`
+ *  는 표(canonical)에 있으면 표의 `id`(예 5.5 → `global.anthropic.…` runtime), 없으면 `anthropic.claude-x`.
+ *  지역/전역 접두가 «이미» 붙은 id 는 그대로(데이터 거주 선택 보존). 그 밖은 그대로 돌려준다(엔드포인트가 판정한다). */
 export function resolveBedrockModelId(model: string | undefined): string {
   const raw = (model ?? '').trim();
   if (!raw) return BEDROCK_DEFAULT_MODEL;
   let m = raw;
   if (m.toLowerCase().startsWith(BEDROCK_ALIAS_PREFIX)) m = m.slice(BEDROCK_ALIAS_PREFIX.length);
-  if (BEDROCK_CLAUDE_ID.test(m)) return m;
-  if (/^claude-/i.test(m)) return `anthropic.${m}`;
-  return m;
+  if (BEDROCK_INFERENCE_PROFILE_PREFIX.test(m) && BEDROCK_CLAUDE_ID.test(m)) return m;
+  const bare = /^anthropic\.claude-/i.test(m) ? m.slice('anthropic.'.length) : /^claude-/i.test(m) ? m : undefined;
+  if (bare === undefined) return m;
+  const entry = BEDROCK_MODELS.find((e) => e.canonical === bare.toLowerCase());
+  return entry ? entry.id : `anthropic.${bare}`;
 }
 
 /** 와이어 id → 1st-party 꼴(`claude-…`). 계열 판정 헬퍼(adaptive·vision·temperature)가 이 꼴을 안다. */
@@ -77,7 +147,7 @@ export function bedrockCanonicalClaudeId(model: string | undefined): string {
 
 /** 표의 모델을 찾는다 — 지역/전역 추론 프로필 접두(`us.anthropic.…`)도 같은 모델로 본다(계열은 접두를 뗀 꼴로). */
 export function findBedrockModel(id: string): BedrockModelEntry | undefined {
-  const canonical = bedrockCanonicalClaudeId(id.trim());
+  const canonical = bedrockCanonicalClaudeId(id.trim()).toLowerCase();
   return BEDROCK_MODELS.find((m) => m.canonical === canonical);
 }
 
@@ -217,6 +287,14 @@ export function bedrockAvailable(deps: BedrockEnvDeps = {}): boolean {
   return resolveBedrockRegion(deps) !== undefined;
 }
 
+/** 응답 본문의 AWS 식별자(ARN · 12자리 계정 번호)를 가린다 — 403 `permission_error` 본문이 IAM 주체 ARN 을 그대로 싣는다
+ *  (📏 BEDROCK-CHECK 10-11 실호출). `redactSecrets` 는 ARN 을 모른다 ⇒ 에러 문면·로그로 계정이 새지 않게 여기서 한 번 더 지운다. */
+export function redactAwsIdentifiers(text: string): string {
+  return text
+    .replace(/arn:aws[a-z-]*:[^\s"',;]*/gi, 'arn:<redacted>')
+    .replace(/(?<![0-9])[0-9]{12}(?![0-9])/g, '<account>');
+}
+
 /** SDK 자격 체인이 내는 «고정» 에러 이름 — 이것만 메시지·로그에 싣는다. 그 밖은 `CredentialResolutionError`. */
 const KNOWN_CREDENTIAL_ERROR_NAMES: ReadonlySet<string> = new Set([
   'CredentialsProviderError', 'ProviderError', 'TokenProviderError', 'TimeoutError',
@@ -252,6 +330,49 @@ export function bedrockMessagesUrl(region: string): string {
   return url;
 }
 
+/** ⭐ mantle OpenAI 호환 URL — 경로는 모델 표의 `openaiPath` 칸이 정한다(표 밖 id 는 거부 · 호스트는 메시지 엔드포인트와 같다). */
+export function bedrockMantleOpenAIUrl(region: string, modelId: string): string {
+  const valid = validBedrockRegion(region);
+  if (!valid) throw new Error('Bedrock: 리전 값이 AWS 리전 꼴이 아니다 — 요청을 만들지 않는다');
+  const entry = BEDROCK_MODELS.find((m) => m.id === modelId.trim());
+  if (entry?.route !== 'mantle-openai' || !entry.openaiPath) throw new Error('Bedrock: 모델이 mantle OpenAI 경로 표에 없다 — 요청을 만들지 않는다');
+  const host = `bedrock-mantle.${valid}.api.aws`;
+  const url = `https://${host}${entry.openaiPath}`;
+  const u = new URL(url);
+  if (u.protocol !== 'https:' || u.hostname !== host || u.username || u.password || u.search || u.hash) {
+    throw new Error('Bedrock: 요청 호스트가 Bedrock 엔드포인트가 아니다 — 요청을 만들지 않는다');
+  }
+  return url;
+}
+
+/** ⭐ runtime 경로 URL — 리전 꼴 검증 ⊕ 모델 id 꼴 검증 ⊕ 호스트 이중 확인(자격을 붙이기 «전»).
+ *  모델 id 는 경로 조각이라 `/`·`?`·`#`·`@` 등을 받지 않는다(추론 프로필 id 꼴 `[A-Za-z0-9._:-]` 만). */
+const BEDROCK_RUNTIME_MODEL_ID_SHAPE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
+
+export function bedrockRuntimeInvokeUrl(region: string, modelId: string): string {
+  const valid = validBedrockRegion(region);
+  if (!valid) throw new Error('Bedrock: 리전 값이 AWS 리전 꼴이 아니다 — 요청을 만들지 않는다');
+  const id = modelId.trim();
+  if (!BEDROCK_RUNTIME_MODEL_ID_SHAPE.test(id)) throw new Error('Bedrock: 모델 id 가 추론 프로필 id 꼴이 아니다 — 요청을 만들지 않는다');
+  const host = `bedrock-runtime.${valid}.amazonaws.com`;
+  const url = `https://${host}/model/${encodeURIComponent(id)}/invoke-with-response-stream`;
+  const u = new URL(url);
+  if (u.protocol !== 'https:' || u.hostname !== host || u.username || u.password || u.search || u.hash) {
+    throw new Error('Bedrock: 요청 호스트가 Bedrock runtime 엔드포인트가 아니다 — 요청을 만들지 않는다');
+  }
+  return url;
+}
+
+/** 서명 «직전» 호스트 확인 — 경로별로 허용 호스트는 «하나»다. 아니면 자격을 붙이지 않는다. */
+export function assertBedrockHost(url: string, region: string, route: BedrockRoute): void {
+  const valid = validBedrockRegion(region);
+  const u = new URL(url);
+  const want = route === 'runtime' ? `bedrock-runtime.${valid}.amazonaws.com` : `bedrock-mantle.${valid}.api.aws`;
+  if (!valid || u.protocol !== 'https:' || u.hostname !== want || u.username || u.password) {
+    throw new Error('Bedrock: 요청 호스트가 Bedrock 엔드포인트가 아니다 — 자격을 붙이지 않는다');
+  }
+}
+
 export interface SignedBedrockRequest {
   url: string;
   headers: Record<string, string>;
@@ -265,16 +386,18 @@ export type BedrockSigner = (input: {
   headers: Record<string, string>;
   body: string;
   credentials: BedrockCredentials;
+  /** SigV4 서비스 — mantle `bedrock-mantle` · runtime `bedrock`. 없으면 mantle. */
+  service?: string;
 }) => Promise<Record<string, string>>;
 
-export const defaultBedrockSigner: BedrockSigner = async ({ url, region, headers, body, credentials }) => {
+export const defaultBedrockSigner: BedrockSigner = async ({ url, region, headers, body, credentials, service }) => {
   const [{ SignatureV4 }, { Hash }] = await Promise.all([
     import('@smithy/signature-v4'),
     import('@smithy/hash-node'),
   ]);
   const u = new URL(url);
   const signer = new SignatureV4({
-    service: BEDROCK_SIGV4_SERVICE,
+    service: service ?? BEDROCK_SIGV4_SERVICE,
     region,
     credentials,
     sha256: Hash.bind(null, 'sha256'),
@@ -292,32 +415,55 @@ export const defaultBedrockSigner: BedrockSigner = async ({ url, region, headers
   return out;
 };
 
-/** 요청 한 건을 조립·서명한다. 베어러 토큰(`AWS_BEARER_TOKEN_BEDROCK`)이 있으면 `x-api-key` 로(출처 문서 «Bearer tokens»). */
+/** runtime 몸 — mantle 몸에서 `model`(URL 로 간다)·`stream`(엔드포인트가 정한다)을 빼고 `anthropic_version` 을 앞에 둔다.
+ *  나머지 칸(`messages`·`system`·`tools`·`cache_control` 자리)은 «바이트 그대로» 같다. */
+export function bedrockRuntimeBody(body: Record<string, unknown>): Record<string, unknown> {
+  const { model: _model, stream: _stream, ...rest } = body;
+  return { anthropic_version: BEDROCK_RUNTIME_ANTHROPIC_VERSION, ...rest };
+}
+
+/** 요청 한 건을 조립·서명한다. 베어러 토큰(`AWS_BEARER_TOKEN_BEDROCK`)이 있으면 mantle 은 `x-api-key`(출처 문서 «Bearer tokens»),
+ *  runtime 은 `authorization: Bearer`(Bedrock API 키 규약).
+ *  mantle-openai 는 OpenAI 호환 엔드포인트 규약대로 베어러를 `authorization: Bearer` 로 보낸다(몸은 mantle 과 같은 `{...body, stream:true}`).
+ *  `route` 가 없으면 몸의 `model` 로 표를 본다(`bedrockRouteFor`). */
 export async function buildSignedBedrockRequest(input: {
   region: string;
   body: Record<string, unknown>;
   env?: Env;
   resolveCredentials?: BedrockCredentialResolver;
   sign?: BedrockSigner;
+  route?: BedrockRoute;
 }): Promise<SignedBedrockRequest> {
   const env = input.env ?? process.env;
-  const url = bedrockMessagesUrl(input.region);
-  // URL 과 서명 스코프가 «같은» 정규화 리전을 쓴다(bedrockMessagesUrl 이 무효면 이미 던졌다).
+  const route = input.route ?? bedrockRouteFor(String(input.body.model ?? ''));
+  const url = route === 'runtime'
+    ? bedrockRuntimeInvokeUrl(input.region, String(input.body.model ?? ''))
+    : route === 'mantle-openai'
+      ? bedrockMantleOpenAIUrl(input.region, String(input.body.model ?? ''))
+      : bedrockMessagesUrl(input.region);
+  // URL 과 서명 스코프가 «같은» 정규화 리전을 쓴다(URL 빌더가 무효면 이미 던졌다).
   const region = validBedrockRegion(input.region)!;
-  const body = JSON.stringify({ ...input.body, stream: true });
-  const base: Record<string, string> = {
-    'content-type': 'application/json',
-    'anthropic-version': BEDROCK_ANTHROPIC_VERSION,
-  };
+  assertBedrockHost(url, region, route);
+  const body = route === 'runtime'
+    ? JSON.stringify(bedrockRuntimeBody(input.body))
+    : JSON.stringify({ ...input.body, stream: true });
+  const base: Record<string, string> = route === 'runtime'
+    ? { 'content-type': 'application/json', accept: 'application/vnd.amazon.eventstream' }
+    : route === 'mantle-openai'
+      ? { 'content-type': 'application/json', accept: 'text/event-stream' }
+      : { 'content-type': 'application/json', 'anthropic-version': BEDROCK_ANTHROPIC_VERSION };
   const bearer = env.AWS_BEARER_TOKEN_BEDROCK?.trim();
-  if (bearer) return { url, headers: { ...base, 'x-api-key': bearer }, body };
+  if (bearer) {
+    return { url, headers: route === 'mantle' ? { ...base, 'x-api-key': bearer } : { ...base, authorization: `Bearer ${bearer}` }, body };
+  }
   let credentials: BedrockCredentials;
   try {
     credentials = await (input.resolveCredentials ?? defaultBedrockCredentialResolver)();
   } catch (err) {
     throw new BedrockCredentialsUnresolvedError(sanitizeCredentialErrorName(err));
   }
-  const headers = await (input.sign ?? defaultBedrockSigner)({ url, region, headers: base, body, credentials });
+  const service = route === 'runtime' ? BEDROCK_RUNTIME_SIGV4_SERVICE : BEDROCK_SIGV4_SERVICE;
+  const headers = await (input.sign ?? defaultBedrockSigner)({ url, region, headers: base, body, credentials, service });
   return { url, headers, body };
 }
 

package/src/llm/open-weight-discipline.ts

@@ -0,0 +1,21 @@
+/** OpenRouter(`openrouter/…`) GLM·Kimi·Qwen 전용 도구 호출 규율 — 다른 군 상수와 합성하지 않는 독립 상수.
+ *
+ *  2026-10-11 GLM-PROMPT-TUNE 첫 조각: `llm.ts` 동결(RFC #25983)을 위해 상수를 이 파일로 옮겼다.
+ *  줄 둘을 추가했다 — 실측 약점 둘을 겨냥한다:
+ *    ⑴ 그라운딩 비교 8회 중 GLM 3회 전부 «Grep 으로만 확인하고 Read 는 안 했다»고 스스로 적고
+ *       그 경로를 증거로 써 grounding-evidence 기각
+ *    ⑵ 상 칸에서 PR 없이 라운드만 도는 no-progress(부검반 ×26)
+ *  다른 군(codex·grok·local·claude·gemini·gpt·other)의 요청 바이트는 불변 — 이 상수는
+ *  open-weight 계열에만 주입된다(`TOOL_DISCIPLINE_BY_FAMILY`).
+ *
+ *  ⛔ `llm.ts` 의 `selectIntentClassificationMessages` 가 이 상수와 «정확 일치»로 분류기를
+ *     걸러 내므로, 주입부는 상수를 그대로 싣는다(합성 금지). */
+export const OPEN_WEIGHT_TOOL_DISCIPLINE = [
+  '[open-weight tool-use discipline]',
+  '- 도구로 할 수 있는 일은 이번 응답에서 바로 도구를 호출하라. "먼저 읽겠다" 또는 "확인하겠다" 같은 계획만 말하고 응답을 끝내지 마라.',
+  '- 작업을 시작하는 첫 응답에는 도구 호출이 하나 이상 있어야 한다.',
+  '- 도구 호출 인자는 해당 도구의 스키마에 맞는 JSON 으로 내라.',
+  '- 충분한 근거가 모이면 도구 호출 없이 최종 답을 평문으로 써서 끝내라.',
+  '- 증거·근거로 적는 파일은 이번 작업에서 Read 로 연 파일만 — Grep·Glob 결과만으로 내용을 단정하지 마라.',
+  '- 구현을 끝냈다고 말하기 전에 바꾼 파일과 돌린 시험 명령·결과를 적어라.',
+].join('\n');

package/src/llm/openrouter-byok-cost.ts

@@ -0,0 +1,96 @@
+// OR-BYOK-COST (2026-10-11) — OpenRouter BYOK(Bring Your Own Key) 호출의 «실비용»을 원장에 싣는다.
+//
+// S: OpenRouter 계정에 상류 키(예: OpenAI)가 붙어 있으면 그 호출은 BYOK 로 라우팅된다. 응답 `usage` 는
+//    `is_byok: true` · `cost: 0`(OR 청구) · `cost_details.upstream_inference_cost: <USD>`(상류 키로 실제 청구)로 온다
+//    (UX 실측 10-11 · `openai/gpt-6-luna` · provider=OpenAI).
+// C: elanous 는 `usage.cost` 만 읽었다 ⇒ BYOK 실비용이 원장(`usdKnown`)에서 사라지고 벤치·롤업 $ 가 0 으로 낮게 잡혔다.
+// A: 파서가 `is_byok` ⊕ `upstream_inference_cost` 를 읽고(이 모듈), 비용 판정이 «OR 청구 + 상류 청구»를
+//    `kind:'actual'` 로 낸다(출처 `costSource:'byok-upstream'` 와 두 몫을 곁에 남긴다).
+//    ⛔ 상류 칸이 없거나 숫자가 아니면 «미상» — 0 으로 가정하지 않는다(`kind:'partial'` · 롤업이 unknownCostCalls 로 센다).
+
+import { debug } from '../debug/log.js';
+
+/** 파서가 `LLMUsage` 에 더하는 BYOK 칸. 비-BYOK 응답이면 «빈 객체»(종전 바이트 그대로). */
+export interface OpenRouterByokUsageFields {
+  /** OpenRouter `usage.is_byok === true` — 상류 키로 청구된 호출. */
+  byok?: true;
+  /** OpenRouter `usage.cost_details.upstream_inference_cost` — 상류 키로 실제 청구된 USD. 칸이 없거나 숫자가 아니면 없다(=미상). */
+  upstreamCostUsd?: number;
+}
+
+function finiteNonNegative(v: unknown): v is number {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0;
+}
+
+/** OpenAI 호환 응답(스트림 마지막 청크 · 비스트림 본문 모두 `usage` 가 최상위에 있다)에서 BYOK 칸을 읽는다.
+ *  ⛔ 관측에 키 값을 넣지 않는다 — 모델·상류 provider·금액만. */
+export function readOpenRouterByokUsage(event: unknown): OpenRouterByokUsageFields {
+  if (!event || typeof event !== 'object') return {};
+  const e = event as { usage?: unknown; model?: unknown; provider?: unknown };
+  const u = e.usage;
+  if (!u || typeof u !== 'object') return {};
+  const r = u as { is_byok?: unknown; cost_details?: unknown };
+  if (r.is_byok !== true) return {};
+  const details = r.cost_details && typeof r.cost_details === 'object' ? r.cost_details as { upstream_inference_cost?: unknown } : undefined;
+  const upstream = details?.upstream_inference_cost;
+  const out: OpenRouterByokUsageFields = { byok: true };
+  if (finiteNonNegative(upstream)) out.upstreamCostUsd = upstream;
+  try {
+    debug.log('llm.openrouter', 'byok-cost', {
+      model: typeof e.model === 'string' ? e.model : null,
+      provider: typeof e.provider === 'string' ? e.provider : null,
+      upstreamCostUsd: out.upstreamCostUsd ?? null,
+    });
+  } catch { /* 관측 실패가 파싱을 바꾸지 않는다 */ }
+  return out;
+}
+
+/** 스트림 합산(`accumulateUsage`)용 — BYOK 표지는 «한 번이라도» 참이면 참, 상류 금액은 더한다. */
+export function accumulateByokUsage<T extends OpenRouterByokUsageFields>(total: T, received: OpenRouterByokUsageFields): T {
+  if (received.byok === true) total.byok = true;
+  if (received.upstreamCostUsd !== undefined) total.upstreamCostUsd = (total.upstreamCostUsd ?? 0) + received.upstreamCostUsd;
+  return total;
+}
+
+/** BYOK 호출의 비용 칸. 두 몫(OR 청구 · 상류 청구)을 모두 알면 `actual`, 하나라도 모르면 `partial`(알려진 몫만 usd). */
+export interface ByokActualCost {
+  kind: 'actual';
+  model: string;
+  /** OR 청구 + 상류 청구. */
+  usd: number;
+  source: 'provider-reported';
+  costSource: 'byok-upstream';
+  byok: true;
+  orChargeUsd: number;
+  upstreamUsd: number;
+  estimateUsd?: number;
+}
+
+export interface ByokPartialCost {
+  kind: 'partial';
+  model: string;
+  /** 알려진 몫만(대개 OR 청구 0). 모르는 몫은 null 칸으로 표시한다 — 롤업은 이 호출을 unknownCostCalls 로 센다. */
+  usd: number;
+  source: 'provider-reported';
+  costSource: 'byok-upstream';
+  byok: true;
+  orChargeUsd: number | null;
+  upstreamUsd: number | null;
+  estimateUsd?: number;
+}
+
+/** BYOK 이면 비용 칸을 낸다 — 비-BYOK 이면 null(호출부가 종전 경로로 간다). */
+export function byokCostFor(
+  model: string,
+  usage: { byok?: unknown; upstreamCostUsd?: unknown; reportedCostUsd?: unknown },
+  estimateUsd: number | undefined,
+): ByokActualCost | ByokPartialCost | null {
+  if (usage.byok !== true) return null;
+  const or = finiteNonNegative(usage.reportedCostUsd) ? usage.reportedCostUsd : null;
+  const up = finiteNonNegative(usage.upstreamCostUsd) ? usage.upstreamCostUsd : null;
+  const est = estimateUsd !== undefined ? { estimateUsd } : {};
+  if (or !== null && up !== null) {
+    return { kind: 'actual', model, usd: or + up, source: 'provider-reported', costSource: 'byok-upstream', byok: true, orChargeUsd: or, upstreamUsd: up, ...est };
+  }
+  return { kind: 'partial', model, usd: (or ?? 0) + (up ?? 0), source: 'provider-reported', costSource: 'byok-upstream', byok: true, orChargeUsd: or, upstreamUsd: up, ...est };
+}

package/src/llm/openrouter-deepseek.ts

@@ -0,0 +1,151 @@
+// OR-DEEPSEEK-TUNE (2026-10-11) — OpenRouter `deepseek/*` 전용 요청 조정.
+//
+// 왜 따로 두나: llm.ts 는 동결(RFC #25983)이라 새 판단은 여기 두고 llm.ts 엔 배선만 남긴다.
+// ⛔ 불변식: 여기 함수들은 «DeepSeek 가 아닌» 모델에 대해 항상 «아무것도 안 바꾼다» 는 값을 돌려준다
+//    (빈 객체 · 원래 값 · false) — OpenRouter 의 다른 모델 요청 바이트는 이 모듈 때문에 바뀌지 않는다.
+//
+// 근거(MIT · 패턴만 참고):
+//   - openclaw extensions/openrouter/models.ts:56-60 `isOpenRouterDeepSeekV4ModelId` — V4 판정 정규식.
+//   - openclaw extensions/openrouter/thinking-policy.ts:8-11 — OpenRouter 의 DeepSeek V4 effort 단계는 off..xhigh
+//     (OpenRouter 통일 effort 에 `max` 는 없다 → 이 저장소 실측: `max` 를 보내면 400).
+//   - openclaw packages/ai/src/transports/openai-completions-replay.ts:101-127 — «빈» 추론 조각은
+//     OpenRouter/DeepSeek 재전송에서 거부된다 ⇒ 빈 placeholder 를 만들지 않고 빈 조각을 걷는다.
+//   - opencode packages/opencode/src/provider/transform.ts:303-319 — DeepSeek 는 «모든» assistant 턴에 추론을 요구.
+//     (opencode 는 빈 placeholder 를 넣지만 위 openclaw 근거로 여기선 넣지 않는다.)
+//   - 상류 고정: 대상 이름은 설정 기본값 `./openrouter-upstream-pins.config.ts` ⊕ 사용자 `llm.openrouter.upstreamPins`.
+//   - hermes-agent agent/reasoning_effort.py:130-133 — DeepSeek V4 의 최상위 단계(직결 API 는 `max`) ↔ xhigh.
+
+import { debug } from '../debug/log.js';
+import { getCatalog } from '../registry/loader.js';
+import { DEFAULT_OPENROUTER_UPSTREAM_PINS } from './openrouter-upstream-pins.config.js';
+
+/** OpenRouter wire 모델(`openrouter/` 를 뗀 id)이 DeepSeek 인가. */
+export function isOpenRouterDeepSeekWireModel(wireModel: string): boolean {
+  return wireModel.toLowerCase().startsWith('deepseek/');
+}
+
+/** DeepSeek V4 계열(v4-flash · v4.1-flash · v4-pro · 날짜 고정판 · `:variant`)인가. */
+export function isOpenRouterDeepSeekV4WireModel(wireModel: string): boolean {
+  return /^deepseek\/deepseek-v4(?:\.\d+)?-/.test(wireModel.toLowerCase());
+}
+
+export type OpenRouterEffort = 'low' | 'medium' | 'high' | 'xhigh';
+
+/** DeepSeek V4 effort 표. `xhigh`·`max` → `xhigh`(OpenRouter 가 `max` 를 400 으로 거부) · `off`/모르는 값 → 칸 없음. */
+const DEEPSEEK_V4_EFFORT: Record<string, OpenRouterEffort> = {
+  minimal: 'low', low: 'low', medium: 'medium', high: 'high', xhigh: 'xhigh', max: 'xhigh',
+};
+
+/** DeepSeek V4 이면 그 표의 값(없으면 `null` = 칸 없음), V4 가 아니면 `undefined`(호출자가 기존 표를 쓴다). */
+export function openRouterDeepSeekEffort(wireModel: string, effort: string | undefined): OpenRouterEffort | null | undefined {
+  if (!isOpenRouterDeepSeekV4WireModel(wireModel)) return undefined;
+  if (effort === undefined || !Object.hasOwn(DEEPSEEK_V4_EFFORT, effort)) return null;
+  return DEEPSEEK_V4_EFFORT[effort];
+}
+
+/** 카탈로그(YAML · `catalog/models/openrouter/<id>.yaml` 의 `reasoning`)가 정한 DeepSeek 기본 effort.
+ *  ⛔ 코드에 기본값을 박지 않는다 — 카탈로그(손 레코드)가 정본이다(MK #26055). 없으면 `undefined` → 호출자의 기존 폴백.
+ *  ⚠️ 발견 폴드가 자동으로 채운 레코드(`discoveryMeta.autoFilled`)는 «능력 추정»(reasoning 칸이 있으면 'high')이라 기본값으로 쓰지 않는다.
+ *  `lookup` 은 시험용 주입점(미지정 = 실제 카탈로그). */
+export function openRouterDeepSeekCatalogEffort(
+  catalogId: string,
+  lookup: (id: string) => { reasoning?: string | null; discoveryMeta?: { autoFilled?: boolean } } | undefined
+    = (id) => getCatalog().models.get(id),
+): 'low' | 'medium' | 'high' | undefined {
+  if (!catalogId.startsWith('openrouter/') || !isOpenRouterDeepSeekWireModel(catalogId.slice('openrouter/'.length))) return undefined;
+  let spec: ReturnType<typeof lookup>;
+  try { spec = lookup(catalogId); } catch { return undefined; }
+  if (!spec || spec.discoveryMeta?.autoFilled === true) return undefined;
+  const r = spec.reasoning;
+  return r === 'low' || r === 'medium' || r === 'high' ? r : undefined;
+}
+
+/** 사용자가 라우팅을 «명시»했는가 — `order`·`only`·`allow_fallbacks` 중 하나라도 있으면 그대로 둔다. */
+function hasExplicitRouting(explicit: unknown): boolean {
+  if (!explicit || typeof explicit !== 'object' || Array.isArray(explicit)) return false;
+  const e = explicit as Record<string, unknown>;
+  return 'order' in e || 'only' in e || 'allow_fallbacks' in e;
+}
+
+/** 이 모델의 상류 고정 목록 — 사용자 `llm.openrouter.upstreamPins` 가 기본값(설정 표)을 모델별로 덮는다.
+ *  빈 배열·문자열 아닌 값·표에 없음 = 고정 안 함(`undefined`). ⛔ 상류 이름은 여기(코드)가 아니라 설정 기본값에 있다. */
+export function resolveOpenRouterUpstreamPin(
+  wireModel: string,
+  userPins: unknown,
+  defaults: Readonly<Record<string, readonly string[]>> = DEFAULT_OPENROUTER_UPSTREAM_PINS,
+): string[] | undefined {
+  const user = userPins && typeof userPins === 'object' && !Array.isArray(userPins) ? userPins as Record<string, unknown> : {};
+  const raw = Object.hasOwn(user, wireModel) ? user[wireModel]
+    : Object.hasOwn(defaults, wireModel) ? defaults[wireModel] : undefined;
+  if (!Array.isArray(raw)) return undefined;
+  const order = raw.filter((x): x is string => typeof x === 'string' && x.length > 0);
+  return order.length > 0 ? order : undefined;
+}
+
+/** 본문 `provider` 칸 덮어쓰기 — `order=<고정 목록>` ⊕ `allow_fallbacks:false`.
+ *  DeepSeek 가 아니거나 · 사용자가 라우팅을 명시했거나 · 고정 목록이 없으면 `{}`(아무것도 안 싣는다 = OR 기본 라우팅).
+ *  `base` 는 이미 실린 provider 칸(require_parameters 등 ⊕ 사용자 설정) — 키 순서를 지키려고 그 위에 덮는다. */
+export function openRouterDeepSeekProviderField(
+  wireModel: string,
+  base: unknown,
+  explicit: unknown,
+  userPins?: unknown,
+  defaults?: Readonly<Record<string, readonly string[]>>,
+): { provider?: Record<string, unknown> } {
+  if (!isOpenRouterDeepSeekWireModel(wireModel) || hasExplicitRouting(explicit)) return {};
+  const order = resolveOpenRouterUpstreamPin(wireModel, userPins, defaults);
+  if (!order) return {};
+  const b = base && typeof base === 'object' && !Array.isArray(base) ? base as Record<string, unknown> : {};
+  return { provider: { ...b, order, allow_fallbacks: false } };
+}
+
+/** 도구 스키마에 Kimi sanitizer(`$ref` 단독 · 단일 items)를 씌울 모델인가 — moonshotai/* ⊕ deepseek/*. */
+export function openRouterNeedsKimiToolSchema(wireModel: string): boolean {
+  return wireModel.startsWith('moonshotai/') || isOpenRouterDeepSeekWireModel(wireModel);
+}
+
+/** 재전송용 `reasoning_details` 에서 «빈» 조각을 걷는다(text·summary·data 가 모두 비었으면 버림).
+ *  다 걷히면 `undefined` — 빈 배열·빈 문자열 placeholder 를 절대 싣지 않는다. */
+export function nonEmptyReasoningDetails(
+  details: ReadonlyArray<Record<string, unknown>> | undefined,
+): Array<Record<string, unknown>> | undefined {
+  if (!Array.isArray(details) || details.length === 0) return undefined;
+  const kept = details.filter((d) => ['text', 'summary', 'data'].some((k) => typeof d?.[k] === 'string' && (d[k] as string).length > 0));
+  return kept.length > 0 ? kept : undefined;
+}
+
+/** 관측 `llm.openrouter deepseek-replay` 의 재료 — 보낼 wire 메시지에서 assistant 턴과 추론 재전송 수를 센다. */
+export function summarizeDeepSeekReplay(wireMessages: ReadonlyArray<Record<string, unknown>>): {
+  assistantTurns: number; withReasoning: number; toolTurns: number; textTurnsWithReasoning: number;
+} {
+  let assistantTurns = 0; let withReasoning = 0; let toolTurns = 0; let textTurnsWithReasoning = 0;
+  for (const m of wireMessages) {
+    if (m.role !== 'assistant') continue;
+    assistantTurns++;
+    const hasTools = Array.isArray(m.tool_calls) && m.tool_calls.length > 0;
+    if (hasTools) toolTurns++;
+    if (Array.isArray(m.reasoning_details) && m.reasoning_details.length > 0) {
+      withReasoning++;
+      if (!hasTools) textTurnsWithReasoning++;
+    }
+  }
+  return { assistantTurns, withReasoning, toolTurns, textTurnsWithReasoning };
+}
+
+/** 요청 한 번의 DeepSeek 부가물 — 본문 `provider` 칸(상류 고정) ⊕ 관측 `llm.openrouter deepseek-replay` 한 줄.
+ *  ⛔ DeepSeek 가 아니면 `{}` 이고 아무것도 남기지 않는다. */
+export function openRouterDeepSeekRequestExtras(
+  wireModel: string,
+  wireMessages: ReadonlyArray<Record<string, unknown>>,
+  baseProvider: unknown,
+  explicitPreferences: unknown,
+  userPins?: unknown,
+): { provider?: Record<string, unknown> } {
+  if (!isOpenRouterDeepSeekWireModel(wireModel)) return {};
+  const field = openRouterDeepSeekProviderField(wireModel, baseProvider, explicitPreferences, userPins);
+  debug.log('llm.openrouter', 'deepseek-replay', {
+    model: wireModel, ...summarizeDeepSeekReplay(wireMessages),
+    upstreamPin: (field.provider?.order as string[] | undefined) ?? null,
+  });
+  return field;
+}

package/src/llm/openrouter-upstream-pins.config.ts

@@ -0,0 +1,25 @@
+// OR-DEEPSEEK-TUNE — OpenRouter 상류 고정 «설정 기본값»(데이터만 · 로직 없음).
+//
+// 키 = OpenRouter wire 모델 id(`openrouter/` 를 뗀 것) · 값 = 본문 `provider.order` 로 실을 상류 slug(⊕ allow_fallbacks:false).
+// ⛔ 이 표는 코드가 아니라 «설정 기본값»이다 — 사용자 설정 `llm.openrouter.upstreamPins` 가 모델별로 덮는다
+//    (빈 배열 `[]` = 그 모델은 고정하지 않음 · OpenRouter 기본 라우팅). `llm.openrouter.providerPreferences` 에
+//    `order`·`only`·`allow_fallbacks` 중 하나라도 있으면 그것이 이기고 이 표는 쓰이지 않는다.
+// ⛔ 표에 없는 모델은 고정하지 않는다.
+//
+// 📏 선정(2026-10-11 · OP 결정 ⓑ) — 공개 `GET /api/v1/models/deepseek/<slug>/endpoints`(인증 없음) 실측:
+//   기준 = 데이터 학습 안 함 ⊕ max_completion_tokens ≥ 131072 ⊕ uptime_last_1d ≥ 99.
+//   ⚠️ 공개 endpoint 데이터엔 학습 정책 칸이 «없다» → 학습 여부는 우리 계정 Guardrails(학습 금지) 실측으로 갈랐다:
+//      라우팅 퍼널에서 «Paid model training violation» 으로 걸러진 것은 `deepseek`(공식) 하나뿐이었고, 아래 고른 상류는
+//      실호출 200 으로 통과를 확인했다.
+//   동률(uptime 100 다수) → fp4 제외 · tool_choice=required 지원 · 입출력 단가 합이 가장 낮은 곳.
+//   ⊕ 4번째 기준(OP 2026-10-11) «2턴째 캐시 적중 > 0.5»(2턴 도구 교환 실호출) · 판촉 할인가 엔드포인트(baidu)는 제외.
+//   - deepseek-v4-pro-0813 → streamlake · out 384000 · uptime 1d 99.86 · $0.66 / $1.98 per MTok (cache read $0.022)
+//       실측 2턴째 캐시: baidu/fp8 0(제외) → streamlake 0.94(선정) · alibaba 0.94(통과 · 차순위)
+//   - deepseek-v4.1-flash  → deepinfra/fp8 · out 131072 · uptime 1d 100 · $0.14 / $0.42 per MTok (cache read $0.0042)
+//       실측 2턴째 캐시 0.98
+//   ⚠️ endpoint 의 `supports_implicit_caching` 은 위 상류 모두 false 였다 — 캐시는 이 칸이 아니라 실호출로 가른다.
+//   값이 늙는다 — 다시 재려면 위 endpoint 를 같은 기준으로 다시 정렬한다.
+export const DEFAULT_OPENROUTER_UPSTREAM_PINS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  'deepseek/deepseek-v4-pro-0813': Object.freeze(['streamlake']),
+  'deepseek/deepseek-v4.1-flash': Object.freeze(['deepinfra/fp8']),
+});