aimakeall-mcp 0.12.0 → 0.14.0

package/README.md

@@ -7,22 +7,41 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
 
 ## 설정
 
+macOS·Windows에서 **Node.js 20 이상**이 필요합니다.
+
 1. [aimakeall.com](https://aimakeall.com) 로그인 → **API 키 설정 → MCP 토큰**에서 토큰 발급 (발급 직후 1회만 표시)
 2. AImakeAll 컴패니언 앱 설치·실행 (렌더용)
-3. MCP 클라이언트 설정 — 버전을 고정해 주세요:
+3. MCP 클라이언트 설정 — **부트스트랩은 `aimakeall-mcp@0.14.0`에 고정**해 주세요. 이후 실제 런타임 버전이 올라가도 이 설치 인자는 그대로 유지합니다:
 
 ```json
 {
   "mcpServers": {
     "aimakeall": {
       "command": "npx",
-      "args": ["-y", "aimakeall-mcp@0.12.0"],
+      "args": ["-y", "aimakeall-mcp@0.14.0"],
       "env": { "AIMAKEALL_PAT": "aio_pat_..." }
     }
   }
 }
 ```
 
+Windows에서 MCP 클라이언트가 `npx`를 직접 실행하지 못한다면 해당 클라이언트의 `cmd /c npx` 실행 래퍼를 사용하세요. 기존 Windows 설정에 래퍼가 있으면 패키지 인자만 바꾸고 래퍼는 유지합니다.
+
+## 시작 시 안전한 자동 업데이트 (0.14.0)
+
+- 부트스트랩은 **MCP 프로세스를 시작할 때** 공식 `https://aimakeall.com/api/mcp/release`에서 승인 릴리스를 확인하고, 배포 파일의 해시를 검증한 뒤 해당 런타임을 사용합니다. npm의 최신 태그를 무조건 실행하는 방식이 아니므로 설치 명령을 `@latest`로 바꾸지 마세요.
+- 업데이트 확인·다운로드·검증에 실패하면 마지막 정상 런타임 또는 동봉 런타임으로 시작합니다. 실행 중인 MCP·제작·렌더 프로세스를 교체하거나 종료하지 않습니다. 새 런타임은 다음 MCP 시작/재연결에 적용됩니다.
+- 자동 업데이트는 기본으로 켜져 있습니다. MCP 설정의 기존 `env`에 `"AIMAKEALL_MCP_AUTO_UPDATE": "0"`을 추가하면 끌 수 있습니다. 나머지 환경변수와 PAT는 유지하세요.
+- **이미 연결한 사용자**는 API 키 설정 → MCP 토큰의 **자동 업데이트 전환 안내**를 복사해 AI에게 전달하세요. 최초 1회 기존 `aimakeall` 실행 항목만 위 부트스트랩으로 바꿉니다. 기존 PAT·다른 MCP·관련 없는 파일은 보존하며 **토큰 재발급은 필요 없습니다.** 설정 백업은 로컬에 보관하고 토큰을 로그나 대화에 출력하지 마세요.
+- 진행 중인 작업이 끝난 뒤 유휴 상태에서만 `aimakeall`을 다시 연결하세요. 이후 런타임 업데이트마다 설정 파일의 버전을 바꿀 필요는 없습니다. 이 업데이트는 MCP용이며 **로컬 렌더용 컴패니언 설치·업데이트는 별도**입니다.
+
+버전과 업데이트 상태를 확인하는 명령(기존 MCP 연결을 종료하지 않음):
+
+```sh
+npx -y aimakeall-mcp@0.14.0 --version
+npx -y aimakeall-mcp@0.14.0 --update-status
+```
+
 ## 환경변수
 
 | 변수 | 기본값 | 설명 |
@@ -31,6 +50,7 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
 | `AIMAKEALL_API_BASE` | `https://aimakeall.com` | API 서버 |
 | `AIMAKEALL_COMPANION_URL` | `http://127.0.0.1:9876` | 로컬 컴패니언 (SSH 터널 시 변경) |
 | `AIMAKEALL_OUTPUT_DIR` | `~/Downloads/AImakeAll` | 렌더 결과 mp4 저장 위치 |
+| `AIMAKEALL_MCP_AUTO_UPDATE` | 사용 | `0`이면 시작 시 자동 업데이트를 끔 |
 
 ## 기본 플로우 (쇼츠)
 
@@ -55,20 +75,29 @@ plan_shorts_video → (씬마다) generate_scene_image → get_generation_job(co
 
 ## 제작 스타일 유지와 컷컴포저 편집 (0.12.0)
 
-아래의 이미지 소스·영상 표현 선택과 TTS 자동 우선순위는 MCP 0.12.0과 대응 서버·컴패니언 런타임이 필요합니다. 기존 MCP 설정의 버전을 `aimakeall-mcp@0.12.0`으로 바꾸고 클라이언트를 다시 연결하세요. 토큰은 그대로 사용할 수 있습니다. 컴패니언에서 렌더 기능 업데이트를 요청하면 최신 설치 프로그램으로 업데이트하세요.
+아래의 이미지 소스·영상 표현 선택과 TTS 자동 우선순위는 MCP 0.12.0부터 지원합니다. 기존 설치는 위의 `aimakeall-mcp@0.14.0` 부트스트랩으로 한 번 전환하고 유휴 상태에서 다시 연결하세요. 토큰은 그대로 사용할 수 있습니다. 대응 서버와 컴패니언 런타임도 필요하며, 컴패니언에서 렌더 기능 업데이트를 요청하면 최신 설치 프로그램으로 업데이트하세요.
 
 - `plan_shorts_video({categoryId:"viral-shorts",durationTargetSec:40,...})`는 `productionProfile`과 `productionPath`를 반환합니다. 이후 추천·TTS·스티치에 **가장 최근 반환된 `productionPath`**를 전달하세요. 제작별 불변 파일이라 동시에 만든 다른 영상의 스타일과 섞이지 않습니다.
 - 바이럴·커뮤니티 프로필은 `casual-social`을 사용합니다. 사건 소재라도 뉴스 브리핑형으로 자동 변경하지 않습니다. TTS의 `text`를 생략하면 저장된 기획 대본을 사용하며, 분명한 뉴스체 회귀는 과금 전 `422 NARRATION_STYLE_DRIFT`로 중단합니다. 자막은 실제 발화와 일치시켜야 하며 자극성을 위해 사실·인용·피해 내용을 꾸미면 안 됩니다.
-- 보이스 공급자 자동 선택은 Typecast → ElevenLabs → Supertone → Edge TTS → Supertonic2 순서입니다. 키/실행 가능 상태를 먼저 확인하며 유료 합성 오류 뒤 다른 공급자로 몰래 재합성하지 않습니다. 대화형/소셜 목소리를 우선하되 실제 청취 결과라고 주장하지 않습니다. ElevenLabs 외의 공급자 자막은 실제 오디오 길이 기반 추정 타이밍임을 표시하므로 최종 동기화를 확인하세요.
+- 보이스 공급자 자동 선택은 Typecast → ElevenLabs → Supertone → Edge TTS → Supertonic2 순서입니다. 키/실행 가능 상태를 먼저 확인하며, 0.13.0부터 확정된 일시 실패에 한해 아래의 안전한 폴백 규칙을 적용합니다. 명시한 목소리는 승인된 대체 보이스 없이 바꾸지 않습니다. 대화형/소셜 목소리를 우선하되 실제 청취 결과라고 주장하지 않습니다. ElevenLabs 외의 공급자 자막은 실제 오디오 길이 기반 추정 타이밍임을 표시하므로 최종 동기화를 확인하세요.
 - `list_composer_presets`에서 실제 편집기의 프리셋과 모션을 조회하세요. `titleStylePresetId`, `subtitleStylePresetId`, `subtitleLines[].stylePresetId`, `titleStyle`, `subtitleStyle`, `subtitleLines[].style`로 서로 다른 제목/본문 계층과 장면별 강조를 설정합니다. 명시 스타일 > 선택 프리셋 > 프로필 기본값 순서입니다.
 - `search_composer_assets` 또는 무료 `recommend_composer_overlays`로 관련 소재를 검토하고 선택한 `assetId`에 `startSec/endSec`, `xPct/yPct`, `widthPct`를 붙여 `stitch_timeline.overlays`로 전달하세요. 좌표는 화면의 백분율 중심점이며 `opacity`는 0~100입니다. SVG 아이콘·이모지, GIF/비디오, 효과음을 타임라인 레이어로 처리합니다. 사건·피해자에 조롱 밈을 강제로 붙이지 않으며, 출처·라이선스 확인이 필요한 소재는 공개 전에 검토해야 합니다.
 - 목표 길이는 실제 TTS 길이로 덮어쓰지 않습니다. 허용 오차 `max(2초, 목표의 10%)`를 벗어나면 경고하고 렌더 전에 차단합니다. 자동 유료 재합성을 하지 않으며, 무음이나 억지 영상 늘이기로 통과시키지 마세요.
 - 커뮤니티/바이럴 제작은 라이브러리 검토 없이 기본 자막만으로 끝내지 않습니다. 오버레이가 없으면 `decorationRationale`에 적합한 소재를 생략한 이유를 기록해야 렌더할 수 있습니다. 관련 없는 장식이나 부적절한 밈을 억지로 넣는 것은 해결이 아닙니다.
 - `review_production`은 구조만 점검합니다. `render_result`의 `qualityStatus`가 `needs-visual-and-listening-review`이면 아직 시각·청취 검증 전입니다. 최종 영상에서 강조색/글자 크기/모션/소재 겹침과 목소리를 직접 확인한 뒤에만 완성 품질을 보고하세요.
 
+## 공급자 폴백과 비용 기록 (0.13.0)
+
+- `tts_narration`과 `tts_narration_with_captions`는 일반 합성에서 확정된 일시 거절(429/503 등)에 한해 다음 사용 가능한 공급자를 고려합니다. `allowProviderFallback:false`로 끌 수 있습니다. 자동 선택 전 사용자 키로 보이스 목록을 확인하며, 비용 견적만 요청할 때는 이 추가 검증을 하지 않습니다.
+- 보이스를 명시했거나 제작 핸들에 캐스팅이 저장되어 있으면 공급자별 대체 보이스를 사용자가 허용해야 합니다. 예: `fallbackVoices:{elevenlabs:{voiceId:"사용자가-승인한-ID"}}`. 다른 공급자의 보이스/모델/스타일 ID를 그대로 재사용하지 않습니다. 커뮤니티형 제작은 기존처럼 먼저 `recommend_voice`를 사용하세요.
+- 성공 응답의 `provider`, `primaryProvider`, `providerFallback`, `accountCostEvents`로 실제 합성 공급자와 비용을 확인합니다. 폴백 후 새 `productionPath`에 실제 보이스를 저장하며 이전 제작 핸들은 바꾸지 않습니다. 항상 최신 핸들을 다음 단계에 넘기세요.
+- 제출 시간 초과·네트워크 단절·접수 후 결과 불명, 인증·입력·안전정책 오류에는 다른 유료 생성을 자동 실행하지 않습니다. 오류의 `fallbackStatus`, `fallbackReason`, `fallbackAvailable`, 접수된 비용을 확인하고 기존 작업부터 조회하세요. 실패했다고 비용이 없거나 환불되었다는 뜻은 아닙니다.
+- ElevenLabs의 정확한 문자별 타임스탬프를 선택한 요청은 추정 자막으로 대체하지 않습니다. 다른 공급자 일반 합성이 ElevenLabs로 전환되더라도 `timingSource:"estimated-from-audio-duration"`인 자막이 정밀 타임스탬프로 바뀌지는 않습니다. 사용자 PC의 Companion 직접 Edge TTS는 서버 폴백 체인 밖입니다.
+- 이미지·영상·LLM 폴백은 대응 서버가 지원하는 동일 기능/입력 경로에서만 동작합니다. SUNO, 음성 클로닝, 정밀 정렬 등 모든 독점 기능에 호환 대체가 있는 것은 아닙니다. 상태 조회만으로 미확인 유료 작업을 재생성하지 마세요.
+
 ## 장면 이미지 준비와 영상 표현 선택
 
-다음 설정은 0.12.0부터 지원합니다. 기존 0.11.0 클라이언트는 위의 버전 고정 설정을 바꾸고 다시 연결해야 새 입력과 도구 안내를 사용할 수 있습니다. 이미지 모션 렌더에는 해당 기능을 지원하는 최신 컴패니언 런타임도 필요합니다.
+다음 설정은 0.12.0부터 지원합니다. 구형 클라이언트는 위의 자동 업데이트 전환 안내에 따라 한 번 전환하고 유휴 상태에서 다시 연결해야 새 입력과 도구 안내를 사용할 수 있습니다. 이미지 모션 렌더에는 해당 기능을 지원하는 최신 컴패니언 런타임도 필요합니다.
 
 - `plan_shorts_video`, `plan_commerce_video`, `plan_music_video`에서 `imageSourceMode: "web" | "ai" | "mixed"`와 `visualMotionMode: "image-motion" | "i2v"`를 독립적으로 선택합니다. 생략 시 기존 `ai + i2v`입니다. 반환된 `productionPath`를 이미지·영상·TTS·스티치에 계속 전달하면 다른 작업과 선택이 섞이지 않습니다.
 - 웹은 사용자 계정의 Pexels/Pixabay 키로 장면별 `webSearchQuery`를 검색합니다. `web`은 결과가 없으면 중단하고, `mixed`만 결과가 없을 때 AI로 이어집니다. 검색 요청 자체가 실패하면 먼저 오류를 확인합니다. `ai`는 웹 검색을 실행하지 않습니다. 여기서 ‘AI만’은 주 장면 이미지 기준이며 편집용 아이콘·이모지 등은 별도입니다.
@@ -96,7 +125,31 @@ detect_shots(원본별, 컴패니언) → analyze_edit_points(videos + shotsFile
 - `analyze_edit_points`가 돌려주는 영상별 `burnedSubtitle`(박힌 자막 관측)을 `prepare_remake_timeline`의 `sourceVideos[].burnedSubtitle`로 그대로 넘기고 `subtitleCropMode: "auto"`를 주면 자막 박힌 소스만 하단 크롭됩니다.
 - `[N]`/`[SN]` 행의 `audioContent`는 유료 TTS로 합성됩니다 — 실행 전 사용자 확인을 받으세요. 원본 다운로드·렌더는 이 PC의 컴패니언이 수행합니다.
 
-## 한도
+## 영화·드라마 리뷰 제작 (0.13.0)
+
+이 절은 런타임 0.13.0부터 대응 서버·컴패니언과 함께 사용하는 경로입니다. 기존 설치된 0.12.0에는 포함되지 않으므로 위의 자동 업데이트 전환 안내를 적용하고 유휴 상태에서 다시 연결하세요.
+
+```
+analyze_review_sources → resumePath → analyze_review_sources(resumePath) 반복
+→ 원본 청크 분석 → 전체 서사 종합 → 원본 영상 재검증 → reviewSourcePath
+→ plan_review_video → productionPath
+→ recommend_voice(productionPath) → prepare_review_timeline(productionPath)
+→ review_production → render_start → render_status → render_result → 시각·청취·스포일러 검토
+```
+
+- 원본은 YouTube ID/URL 또는 로컬 MP4/MOV/M4V/MKV/WebM, 최대 5편·원본별 24시간·총 500청크입니다. 기본 `analysisScope:"full"`은 Gemini 3.8로 처음부터 끝까지 영상과 오디오를 분석합니다. 컴패니언이 최대 300초/10MiB MP4로 압축하고 구간 사이 15초를 겹칩니다. 큰 원본 파일 하나를 직접 올리지는 않지만, **원작의 전체 내용이 압축 청크로 클라우드에 전송됩니다.** 사용자 업로드·과금 동의를 받은 뒤 `allowCloudVideoUpload:true`를 지정해야 합니다. 동의 없이는 샘플 분석으로 우회하지 않습니다.
+- 시작 예: `analyze_review_sources({sources:[{kind:"local",videoPath:"/path/movie.mp4"}],workTitle:"작품명",allowCloudVideoUpload:true})`. YouTube는 `kind:"youtube",videoId:"URL 또는 ID"`입니다. 첫 호출은 원본·지원 기능 검사와 범위/예상 유료 단계 수만 보여 주고 과금하지 않습니다. 이후 `analyze_review_sources({resumePath,allowCloudVideoUpload:true})`를 `complete:true`까지 반복합니다. 기본 한 호출당 1단계이며 `progress`와 `review_analysis_status({resumePath})`로 진행 상황·누적 비용을 확인합니다.
+- 체크포인트는 원본 식별자·전체 전사·장면·등장인물·서사·단계별 비용을 보존합니다. 오래된 `resumePath`로 재개해도 최신 영수증을 찾아 완료된 청크를 재호출하지 않습니다. 오디오 미검토/전사 누락, 원본 변경, 재검증 모순·근거 부족, 접수 여부가 불확실한 요청은 중단합니다. `failedStageResultPath`에 반환된 분석/반박 근거를 보존하며 자동 재시도하지 않습니다. 추가 비용을 사용자가 승인한 경우에만 `retryFailedStage:true`를 사용하세요.
+- `resumePath`·`reviewSourcePath`·`productionPath` 및 실패 근거는 MCP의 임시 media 저장소에 있으며 기본 48시간 보존 정책의 정리 대상입니다. 첫 체크포인트 생성 후 48시간 안에 이어서 진행하세요. 장기 보관에는 연결된 체크포인트·근거 파일까지 별도 내보내기/백업이 필요하며 무기한 재개를 보장하지 않습니다.
+- 전체 줄거리와 인물 주장은 관련 원본 MP4+음성을 다시 보내 검증합니다. 모든 대상 검증이 지지되어야 전체 분석 핸들이 나옵니다. 이는 모델 판정이며 모든 프레임의 관찰·전사 완전성·사실성을 보증하지 않습니다. 최종 영상·음성과 원본 근거는 사람이 확인해야 합니다.
+- `analysisScope:"sample"`을 명시하면 예전 대표 프레임 점검(최대 18장)만 수행합니다. 원작 전체 이해가 아닙니다. `segments:[{startMs,endMs,note,dialogueText,spoilerLevel}]` 및 `transcriptSegments:[{startMs,endMs,text}]`를 제공할 수 있고, 구간에 완전히 포함된 대사만 인용 근거로 사용합니다. 이 자료로 부분 구간 리뷰를 만들려면 별도로 `allowPartialSourceReview:true`를 명시해야 합니다.
+- 스포일러 등급은 자동으로 안전하다고 인증하지 않습니다. 미확인 구간은 `unknown`이며 `none`/`limited` 기획에서 제외됩니다. 장편의 편집 후보만 최대 500개/180,000자로 제한하고, 검증된 서사 근거 장면을 우선 선택한 내역을 `catalogSelection`으로 알려 줍니다. `sourceIds`로 직접 선택할 수도 있습니다. 전체 서사·전사는 자르지 않고 유지하며, 전편 맥락 한도를 넘으면 작품/회차 분리를 요청합니다.
+- `plan_review_video({reviewSourcePath,workType:"film" 또는 "drama",workTitle,episode?,targetDurationSec:60..900,spoilerPolicy:"none"|"limited"|"full",reviewAngle,deliveryStyle})`로 리뷰 관점과 말투를 선택합니다. 사실·해석·가상 해석은 구분하며 실제 대사 인용은 제공한 원본 근거가 필요합니다.
+- 내레이션 `[N]`, 원본 대사 `[S]`, 현장음 `[A]`를 편집할 수 있습니다. 리뷰 준비는 공통 자막 프리셋·아이콘/이모지 자동 배치를 사용하며 `autoCompose:false`와 명시 스타일/오버레이로 제어할 수 있습니다. 준비된 길이·실측 TTS가 맞지 않으면 자동 재합성이나 억지 늘이기 대신 오류를 확인하세요.
+- TTS 공급자 우선순위는 Typecast → ElevenLabs → Supertone → Edge TTS → Supertonic2입니다. 보이스를 명시했으면 공급자도 지정하세요. 반환된 최신 `productionPath`를 계속 사용하면 동시 제작의 음성·원본이 섞이지 않습니다. 원본이 분석 후 바뀌면 다시 분석해야 합니다.
+- 영상 및 음악의 사용 권리, 인용 내용, 대사·장면 타이밍, 스포일러, 최종 자막과 음성은 공개 전에 직접 검토해야 합니다. 자동 검토를 공개 허가나 품질 보증으로 표시하지 않습니다.
+
+## 호출 한도
 
 - 쓰기(생성) 호출 분당 20회, 조회 분당 120회, 동시 생성 2개 (서버 강제)
 - 사용자당 활성 PAT 5개, 기본 만료 90일

package/index.mjs

@@ -1,38 +1,25 @@
 #!/usr/bin/env node
-// AImakeAll MCP 서버 (stdio) — Claude Code/Codex에서 자연어로 영상 제작.
-// 클라우드 툴은 PAT(AIMAKEALL_PAT)로 aimakeall.com API를, 렌더 툴은 이 PC의
-// 컴패니언(127.0.0.1:9876)을 호출한다. 렌더는 절대 서버에서 수행되지 않는다.
+// Stable launcher: all tool/config imports live in runtime.mjs.
+import { promises as fs } from "node:fs";
+import { selectRuntime, MIN_NODE_MAJOR } from "./lib/auto-update.mjs";
+import { launchRuntime } from "./lib/runtime-launch.mjs";
 
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-
-import { createApiClient } from "./lib/api-client.mjs";
-import { registerCloudTools } from "./lib/cloud-tools.mjs";
-import { registerCompanionTools } from "./lib/companion-tools.mjs";
-import { MCP_PROXY_VERSION, resolveConfig } from "./lib/config.mjs";
-import { pruneOldMedia } from "./lib/media-store.mjs";
-
-const config = resolveConfig();
-
-// 오래된 스테이징 미디어 정리 (48h TTL) — 숨김 디렉터리가 무한정 커지는 것 방지.
 try {
-  pruneOldMedia(config.stateDir);
+  const metadata = JSON.parse(await fs.readFile(new URL("./package.json", import.meta.url), "utf8"));
+  if (process.argv.includes("--version")) {
+    console.log(`aimakeall-mcp launcher ${metadata.version}`);
+  } else if (Number(process.versions.node.split(".")[0]) < MIN_NODE_MAJOR) {
+    console.error(`[aimakeall-mcp] Node.js ${MIN_NODE_MAJOR} or newer is required; current ${process.versions.node}.`);
+    process.exitCode = 1;
+  } else if (process.argv.includes("--update-status")) {
+    const result = await selectRuntime({ checkOnly: true });
+    console.log(JSON.stringify({ launcherVersion: metadata.version, runtimeVersion: result.version, source: result.source, status: result.status, ...(result.availableVersion ? { availableVersion: result.availableVersion } : {}) }));
+  } else {
+    const selected = await selectRuntime();
+    console.error(`[aimakeall-mcp] launcher ${metadata.version}; runtime ${selected.version} (${selected.source}); ${selected.status}`);
+    process.exitCode = await launchRuntime(selected.runtime, { args: process.argv.slice(2) });
+  }
 } catch {
-  // 정리 실패는 무시
-}
-
-if (!config.pat) {
-  console.error("[aimakeall-mcp] AIMAKEALL_PAT 미설정 — 클라우드 툴은 안내만 반환합니다. aimakeall.com → API 키 설정에서 MCP 토큰을 발급해 환경변수로 넣어주세요.");
-} else if (!config.patLooksValid) {
-  console.error("[aimakeall-mcp] AIMAKEALL_PAT 형식이 올바르지 않습니다 (aio_pat_... 이어야 함).");
+  console.error("[aimakeall-mcp] launcher failed before runtime startup");
+  process.exitCode = 1;
 }
-
-const server = new McpServer({ name: "aimakeall", version: MCP_PROXY_VERSION });
-
-const api = createApiClient({ apiBase: config.apiBase, pat: config.pat });
-registerCloudTools(server, config, api);
-registerCompanionTools(server, config);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-console.error(`[aimakeall-mcp] v${MCP_PROXY_VERSION} 시작 — API ${config.apiBase}, 컴패니언 ${config.companionUrl}`);

package/lib/api-client.mjs

@@ -6,11 +6,21 @@ import { MCP_PROXY_VERSION } from "./config.mjs";
 const DEFAULT_TIMEOUT_MS = 60_000;
 
 export class AimakeallApiError extends Error {
-  constructor(message, { errorCode = "", retryAfterSeconds = 0, status = 0 } = {}) {
+  constructor(message, { errorCode = "", retryAfterSeconds = 0, status = 0, accountCostEvents, acceptedTaskCosts, operationId, costUsd, usage, partialProviderUsage, fallbackMetadata } = {}) {
     super(message);
     this.errorCode = errorCode;
     this.retryAfterSeconds = retryAfterSeconds;
     this.status = status;
+    this.accountCostEvents = Array.isArray(accountCostEvents) ? accountCostEvents : [];
+    this.acceptedTaskCosts = Array.isArray(acceptedTaskCosts) ? acceptedTaskCosts : [];
+    this.operationId = typeof operationId === "string" ? operationId : "";
+    this.costUsd = Number.isFinite(costUsd) ? costUsd : 0;
+    this.usage = usage && typeof usage === "object" ? usage : null;
+    this.partialProviderUsage = partialProviderUsage === true;
+    for (const field of ["fallbackStatus", "fallbackReason", "capability", "provider"]) {
+      if (typeof fallbackMetadata?.[field] === "string") this[field] = fallbackMetadata[field].slice(0, 160);
+    }
+    if (typeof fallbackMetadata?.fallbackAvailable === "boolean") this.fallbackAvailable = fallbackMetadata.fallbackAvailable;
   }
 }
 
@@ -26,7 +36,7 @@ function describeApiFailure(status, payload) {
   if (code === "PLAN_UPGRADE_REQUIRED") return String(payload?.message || "플랜 업그레이드가 필요한 기능입니다.");
   if (status === 413) return "요청 크기가 서버 상한을 초과했습니다. 오디오는 더 짧게/낮은 비트레이트로, 이미지는 더 작게 줄여 다시 시도하세요.";
   if (status === 431) return "요청 헤더가 너무 큽니다. 설명(description)이나 제목을 줄여 다시 시도하세요.";
-  if (status === 426) return "MCP 설정(mcpServers.args)의 aimakeall-mcp 버전을 최신으로 올린 뒤 클라이언트를 재시작하세요.";
+  if (status === 426) return "진행 중인 작업을 마친 뒤 MCP를 다시 연결해 승인된 버전을 자동 적용하세요. 구형 설치본은 AImakeAll MCP 설정의 ‘자동 업데이트 전환 안내’를 한 번 적용해야 합니다. 이 요청을 자동으로 재실행하지 마세요.";
   const message = String(payload?.message || payload?.error || "");
   return message || `AImakeAll API 요청 실패 (HTTP ${status})`;
 }
@@ -65,9 +75,13 @@ export function createApiClient({ apiBase, pat }) {
 
     if (!response.ok) {
       throw new AimakeallApiError(describeApiFailure(response.status, payload), {
-        errorCode: String(payload?.error || ""),
+        errorCode: String(payload?.code || payload?.error || ""),
         retryAfterSeconds: Number(payload?.retryAfterSeconds) || Number(response.headers.get("retry-after")) || 0,
         status: response.status,
+        accountCostEvents: payload?.accountCostEvents, acceptedTaskCosts: payload?.acceptedTaskCosts,
+        operationId: payload?.operationId, costUsd: payload?.costUsd,
+        usage: payload?.usage, partialProviderUsage: payload?.partialProviderUsage,
+        fallbackMetadata: payload,
       });
     }
     return payload;
@@ -98,8 +112,12 @@ export function createApiClient({ apiBase, pat }) {
         payload = null;
       }
       throw new AimakeallApiError(describeApiFailure(response.status, payload), {
-        errorCode: String(payload?.error || ""),
+        errorCode: String(payload?.code || payload?.error || ""),
         status: response.status,
+        accountCostEvents: payload?.accountCostEvents, acceptedTaskCosts: payload?.acceptedTaskCosts,
+        operationId: payload?.operationId, costUsd: payload?.costUsd,
+        usage: payload?.usage, partialProviderUsage: payload?.partialProviderUsage,
+        fallbackMetadata: payload,
       });
     }
     return {