open-multi-agent-kit 0.98.2 → 0.98.4

package/docs/model-catalog-refresh.md

@@ -0,0 +1,190 @@
+# 모델 목록·thinking 갱신 기록
+
+확인일: 2026-09-09. 생성기와 공급자 어댑터를 수정한 뒤 `npm run models:refresh`로
+두 카탈로그를 재생성했다. 생성 파일을 손으로 수정하지 않았다.
+
+## 2026-09-10 재검증: DeepSeek V4.1 Flash 제공 경로
+
+공식 문서·공개 API에서 확인한 기존 OMK 공급자 4곳을 반영했다.
+현재 설정의 인증·endpoint·선택 모델은 변경하지 않았다.
+
+| OMK provider | 요청 model ID | 입력 | 추론 요청 |
+| --- | --- | --- | --- |
+| `deepseek` | `deepseek-flash` | text/image | `thinking.type` + `reasoning_effort: low/high/max` |
+| `opencode-go` | `deepseek-flash` | text/image | `thinking.type` + `reasoning_effort: low/high/max` |
+| `openrouter` | `deepseek/deepseek-v4.1-flash` | text/image | `reasoning.effort: low/high/max` |
+| `vercel-ai-gateway` | `deepseek/deepseek-v4.1-flash` | text/image | adaptive `thinking` + `output_config.effort: low/high/max` |
+
+네 경로 모두 `off/low/high/max`를 노출한다. 새 native ID는 누락돼 있었고,
+OpenCode Go ID는 목록에는 있었지만 thinking 계약이 빠져 있었다. 직접/Go 경로는
+출력 상한을 `max_tokens`로 보내며, off는 명시적 `thinking.type: disabled`로 보낸다.
+기존 직접 `deepseek-v4-flash`는 제거하지 않고 **V4.1 Flash 호환 별칭**으로 표시한다.
+기존 별칭의 `xhigh → max` 호환 매핑도 유지한다.
+
+DeepSeek 공식 가격은 시간대별이다. native 정적 비용은 peak 가격
+(input/output/cache-read: $0.30/$1.20/$0.006 per 1M tokens)을 저장한다.
+Off-peak는 절반이며, Vercel·OpenCode Go 목록이 제공하는 기본 가격과 다를 수 있다.
+현재 숫자형 스키마는 시간대를 표현하지 않으므로 실제 청구액이라고 주장하지 않는다.
+V4 Pro도 현재 공식 peak 가격으로 정정했으며, 9월14일 예정된 리다이렉트는 미리 적용하지 않았다.
+
+`npm run models:refresh` 종료0: **37 providers, 1,333 coding models**,
+HEAD `29624c3962` 대비 **81 추가·35 제거**. OpenRouter 371, Vercel 235,
+이미지 54개다. 모든 필수 소스가 응답했고, 키 없는 Zyloo는 기존 정적 목록을 유지했다.
+제거는 갱신 소스에서 미선정됐다는 뜻이며 모든 계정의 폐기 여부까지 증명하지 않는다.
+
+`deepseek-v41-native.test.ts` 신규 11개가 먼저 실패했고, 생성기 보완·재생성 후
+11개 모두 통과했다. 기존 gateway 4개를 포함한 표적 5파일 62개도 통과했다.
+실제 모델 추론은 호출하지 않고 전송 직전 payload, 출력 상한, 토글·effort를 확인했다.
+models.dev에 있는 신규 provider 이름만 보고 별도 어댑터를 임의 등록하지 않았다.
+
+근거: [DeepSeek 출시·별칭](https://api-docs.deepseek.com/updates/),
+[직접 모델·가격](https://api-docs.deepseek.com/quick_start/pricing),
+[직접 thinking 계약](https://api-docs.deepseek.com/guides/thinking_mode),
+[OpenCode Go ID·endpoint](https://opencode.ai/docs/go/),
+[OpenRouter models](https://openrouter.ai/api/v1/models),
+[Vercel models](https://ai-gateway.vercel.sh/v1/models).
+
+## 2026-09-09 후속 갱신 기록: DeepSeek V4.1 Flash
+
+다시 조회한 목록에서는 OpenRouter와 Vercel 모두 정식 ID
+`deepseek/deepseek-v4.1-flash`를 제공한다. 이전 Vercel beta 항목 대신 이 ID를 사용한다.
+OpenRouter가 선언한 수준은 `low/high/max`, thinking은 선택적이다. 두 route 모두
+OMK에서 `off/low/high/max`를 노출한다.
+
+- OpenRouter: `reasoning.effort: "max"`.
+- Vercel Messages: `thinking.type: "adaptive"`와 `output_config.effort: "max"`.
+  이는 게이트웨이 요청 형식이다. DeepSeek 네이티브 API가 Claude의 adaptive 형식을
+  받는다는 뜻이 아니다. 고정 thinking-budget 경로로 낮추거나 요청 출력 상한을 늘리지 않는다.
+
+후속 재생성 결과는 코딩 모델 1,332개(OpenRouter 371개)이며, 아래 이전 집계는
+2026-09-09 갱신의 기록으로 유지한다. `deepseek-v41-thinking.test.ts`에서 정식 ID,
+두 route의 max payload와 상한 보존을 공급자 호출 없이 확인한다. 실제 게이트웨이의
+내부 매핑·모델 추론량은 별도 검증 대상이다. 후속 표적 검사 90개, 전체 타입 검사,
+주 LSP 2파일과 diff 검사는 종료0으로 통과했다. `npm run check`는 아래에 기록한 기존
+서식/import 오류3건에서 중단했다.
+
+후속 변경 단위는 `catalog-thinking.ts`, 생성 카탈로그, `deepseek-v41-thinking.test.ts`,
+adaptive-envelope 회귀 및 이 문서다. 제안 커밋 메시지는
+`fix: DeepSeek V4.1 Flash 정식 경로와 max effort 전달 보정`이다.
+실제 추론·빌드·커밋은 실행하지 않았다.
+
+참고: [Vercel Messages effort](https://vercel.com/docs/ai-gateway/sdks-and-apis/anthropic-messages-api/reasoning),
+[게이트웨이 effort 매핑](https://vercel.com/docs/ai-gateway/models-and-providers/reasoning).
+
+## 목록 확인 범위
+
+| 소스 | 확인 | 적용 범위 |
+| --- | --- | --- |
+| [OpenRouter models](https://openrouter.ai/api/v1/models) | HTTP 200, 431개 | tool 지원 364개 + 기존 auto 항목 = 365개 |
+| [models.dev](https://models.dev/api.json) | HTTP 200, 213개 공급자 | 기존 생성기가 지원하는 공급자들의 공개 메타데이터 |
+| [Vercel AI Gateway](https://ai-gateway.vercel.sh/v1/models) | HTTP 200, 373개 | tool 지원 235개 |
+| [NVIDIA NIM](https://integrate.api.nvidia.com/v1/models) | HTTP 200, 80개 ID | tool 메타데이터·기존 호환성 필터를 충족하는 19개 |
+| Zyloo | 키 미설정 | 기존 정적 6개 유지. 최신 목록 확인으로 표시하지 않음 |
+
+코딩 카탈로그는 **37개 공급자, 1,287→1,326개 모델**(74개 추가·35개 제거),
+OpenRouter 이미지 카탈로그는 **54개**다. 모델 수는 route별 항목 수이며 서로 다른 기반 모델 수가 아니다.
+models.dev는 공급자 원본 API나 계정별 권한 증명이 아닌 보조 카탈로그다.
+
+OpenRouter 추가 항목에는 GPT-6 Astra/Pro와 batch 변형, Mercury 2.5, Nex N2.5
+Mini/Pro free, Qwen3.8 Max 0902가 있다. OpenAI·Azure·OpenCode·Copilot에도 해당
+소스가 제공하는 Astra 항목을 반영했다. Copilot GPT-6는 Responses 경로를 사용한다.
+Vertex의 신규 Gemini 항목은 **Vertex 자체 목록에 있는 ID만** 추가한다.
+
+삭제 목록도 대조했다. 예를 들어 OpenRouter의 `qwen/qwen3.8-max` 대신
+`qwen/qwen3.8-max-0902`, `inception/mercury-2.5-preview` 대신 정식 Mercury 2.5가
+목록에 있다. Copilot 구형 route, Moonshot 구형 Kimi, NVIDIA 2개 항목도 갱신 소스에서
+더 이상 선정되지 않는다. 이것을 공급자의 공식 폐기 공지나 모든 계정의 사용 불가로
+해석하지 않는다. 소스 응답 실패를 숨기는 `--allow-partial`은 사용하지 않았다.
+
+자동 라우팅 항목 `openrouter/auto`·`openrouter/auto-beta`의 가격 `-1` 표시는 미정
+가격이다. 이를 음수 요금으로 계산하던 코딩·이미지 카탈로그 경로를 교정했다. 기존 숫자형 카탈로그의
+미가격값 0으로 저장하며 **무료라는 뜻이 아니다**. 실제 선택된 모델의 사용량·청구를
+별도로 확인해야 한다.
+
+## Thinking: 모델 이름보다 해당 route의 계약
+
+OpenRouter의 `reasoning.supported_efforts`로 표시할 수준을 만들고,
+`reasoning.mandatory`로 끄기 가능 여부를 구분한다. 선언이 있는 수준은 과거의 이름별
+추정보다 우선한다. 선언 자체가 없는 경우에는 기존 fallback을 유지하며 지원 범위를
+새로 지어내지 않는다.
+
+**토글과 노력 수준은 별개다.** 선택적 thinking 모델은 노력 목록에 `none`이 없어도
+`reasoning.enabled: false`로 끌 수 있다. 반대로 mandatory 모델에는 끄기를 노출하지
+않는다. Mercury 2 계열의 기존 tool-use/instant-mode 제한도 유지한다.
+
+| 모델·route | 이번 정합성 규칙 |
+| --- | --- |
+| GPT-6 Astra, OpenAI/Responses 및 OpenRouter | low·medium·high·xhigh·max. off/minimal 미노출 |
+| Claude Opus 5, Anthropic Messages | adaptive thinking, low·medium·high·xhigh·max. off는 high 이하에서 가능 |
+| Claude Opus 5, Bedrock | legacy budget 대신 adaptive 및 xhigh 사용. application profile의 표시명 매칭 보존 |
+| Gemini 3.7/3.8 Flash, Google/Vertex | low·medium·high. minimal은 API 오류. SDK의 off 요청도 LOW로 처리하며 완전 비활성화로 주장하지 않음 |
+| DeepSeek V4, 직접 API | low·high·max. 기존 OMK xhigh→max 별칭 보존 |
+| DeepSeek V4, OpenRouter | 해당 route가 선언한 high·xhigh 및 optional off. 직접 API의 max 문자열을 이식하지 않음 |
+| Qwen3.8 Max 0902, OpenRouter | mandatory, minimal·low·medium·high·xhigh. 추정으로 max를 추가하지 않음 |
+| GLM-5.2, OpenRouter | optional off·high·xhigh. ZAI 직접 route의 max 규칙과 구분 |
+| Nex N2.5 free, OpenRouter | off·medium·high |
+| Muse Spark 1.3, OpenRouter | gateway가 선언한 max 사용. 직접 Meta의 max→xhigh 규칙과 구분 |
+
+수준 이름은 제공된 API 값이지 모델 간 동일한 추론량이나 토큰 보장이 아니다.
+OpenRouter의 batch 항목을 모델 목록에 포함했다고 OMK가 Batch API를 별도로 구현한
+것은 아니다. 실제 route 지원과 과금은 공급자 계약을 따로 확인해야 한다.
+
+## 로컬 덮어쓰기와 적용
+
+`models.json`의 동일 ID custom model은 새 카탈로그보다 우선할 수 있다.
+기존 `thinkingLevelMap`이나 `compat.supportsReasoningEffort: false`가 남아 있으면
+새 수준이 숨겨지거나 전송되지 않는다. [모델 설정](models.md)을 함께 확인한다.
+
+Model Studio의 DeepSeek V4는 `thinkingFormat: "qwen"`과
+`supportsReasoningEffort: true`를 모델 단위로 설정하면 `enable_thinking`과
+공식 low/medium/high/xhigh/max 값이 전송된다. 네이티브 DeepSeek의 `thinking` 객체와
+혼동하지 않는다. 인증·주소·모델 ID·기본 선택 모델 변경은 thinking 수정과 분리한다.
+
+소스 변경을 설치 CLI에 적용하려면 검토한 build/install 및 새 프로세스가 필요하다.
+로컬 모델 설정만 바꾼 경우에도 진행 중인 요청의 모델 snapshot이 바뀌었다고 간주하지
+않고 모델 목록을 다시 로드한 새 세션에서 확인한다.
+
+## 검증과 한계
+
+카탈로그 누락/수준 오류 16개, Bedrock Opus 5 payload 오류 2개, Gemini off payload
+오류 4개, 직접 DeepSeek low/max 누락 2개를 먼저 실패로 확인했다. 추가 검토에서
+OpenRouter의 토글과 effort 목록을 혼동한 경로도 2개 RED 검사로 교정했다.
+
+검사는 합성 payload를 전송 직전에 포착하거나 HTTP fetch를 대체한다. 공급자 추론,
+OAuth 갱신, 벤치마크, 설치·배포는 하지 않는다. 실제 계정별 사용 가능 여부, rate limit,
+생성 품질과 청구액은 검증 범위가 아니다. 특히 OpenRouter의 모델 존재를 근거로
+ChatGPT/Codex 계정에서 같은 모델을 사용할 수 있다고 추론하지 않는다.
+
+```bash
+npm run models:refresh
+# packages/ai에서: 공급자 추론 없이 표적 검사
+node ../../node_modules/vitest/dist/cli.js --run test/latest-model-thinking.test.ts test/catalog-thinking.test.ts test/latest-thinking-payload.test.ts --maxWorkers=1 --no-file-parallelism
+# 저장소 루트에서
+node_modules/.bin/tsgo --noEmit --pretty false
+npm run check
+```
+
+### 현재 검사 결과와 커밋 체크포인트
+
+- 표적 검사 **251개 통과**, 유료 Bedrock E2E 1개 제외. 동일 검사의 재실행은 합산하지 않았다.
+- 전체 `tsgo --noEmit --pretty false`, 표적 Biome, 주 LSP 11파일, import-cycle 검사,
+  `git diff --check`는 통과했다. 원래 대형 어댑터의 thinking 책임을 작은 모듈로 분리해
+  이번 변경으로 module-size baseline을 늘리지 않았다.
+- `npm run check`는 기존 범위 밖 Biome 오류3건에서 중단했다:
+  `packages/ai/src/utils/oauth/meta.ts`, `packages/coding-agent/test/mcp/tools.test.ts`,
+  `packages/coding-agent/test/session-termination.test.ts`.
+  별도 module-size 검사의 기존 초과6건과 미추적 문서 링크 문제도 남아 있다.
+  전체 저장소 PASS라고 표현하지 않는다.
+- 카탈로그/생성기 단위: `packages/ai/scripts/{generate-models,generate-image-models,catalog-thinking,catalog-pricing}.ts`, 생성 카탈로그2개,
+  catalog/level 회귀와 본 문서. 제안 메시지: `feat: 최신 모델 목록과 route별 thinking 메타데이터 반영`.
+- 어댑터 단위: `packages/ai/src/providers/{google,google-vertex,google-thinking-disable,amazon-bedrock,bedrock-thinking,openai-completions}.ts`,
+  payload 회귀와 직접 사용 문서. 제안 메시지: `fix: 신규 모델 thinking 토글과 effort 전송 정합성 교정`.
+- 사용자 로컬 설정 변경은 저장소 커밋에 포함하지 않는다. 인증·주소·ID·기본 모델을
+  보존한 원본 백업과 별도 의미 비교로 검증한다. build/install·stage/commit·push는 하지 않았다.
+
+근거 문서:
+[OpenAI Astra](https://developers.openai.com/api/docs/models/gpt-6-astra),
+[Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/whats-new-opus-5),
+[Gemini thinking](https://ai.google.dev/gemini-api/docs/generate-content/thinking),
+[DeepSeek thinking](https://api-docs.deepseek.com/guides/thinking_mode),
+[Model Studio DeepSeek](https://www.alibabacloud.com/help/en/model-studio/deepseek-api).

package/docs/model-contract.md

@@ -0,0 +1,168 @@
+# Model dispatch contracts
+
+This opt-in working-tree feature implements the first execution-contract slice of
+[the harness roadmap](../../../ROADMAP.md). It restricts **logical stream dispatch**
+and checks the final **Chat Completions model ID and output-limit parameter**.
+Other APIs, network destinations, and billable attempts are not fully covered.
+It is not a sandbox or a benchmark-integrity attestation.
+
+## CLI
+
+Create a UTF-8 JSON policy, replacing the example identities with the exact
+provider and model you intend to use:
+
+```json
+{
+  "allowedModels": [{ "provider": "your-provider", "id": "exact-model-id" }],
+  "allowedProviders": ["your-provider"],
+  "allowedAuthOrigins": ["your-provider"],
+  "thinking": false,
+  "thinkingLevel": "off",
+  "maxOutputTokens": 4096
+}
+```
+
+```bash
+omk --provider your-provider --model exact-model-id --thinking off \
+  --model-contract ./policy.json -p "Run the requested checks"
+```
+
+The flag does not start an extra model call. A normal prompt still calls the
+configured provider and may incur cost. `--offline` suppresses startup network
+work; it does not prevent prompt inference.
+
+The CLI reads the policy once, before migrations and session creation, and keeps
+that snapshot when replacing or resuming sessions within the process. A later
+process must supply the flag again. It does not alter settings, credentials,
+model selection, or a saved transcript. `--help` does not read the policy.
+
+Missing, unreadable, malformed, non-regular, or oversized files exit with code 1.
+Reads are bounded to 64 KiB; invalid UTF-8 and unknown top-level fields are
+rejected. Missing flag values and duplicate flags are errors. Both
+`--model-contract policy.json` and `--model-contract=policy.json` are accepted.
+
+## SDK
+
+`createAgentSession()` and `createAgentSessionFromServices()` accept an optional
+`modelContract` and main-loop `maxTokens`. `Agent` accepts the same options.
+
+```typescript
+const { session } = await createAgentSession({
+  model,
+  thinkingLevel: "off",
+  modelContract: {
+    allowedModels: [{ provider: model.provider, id: model.id }],
+    allowedProviders: [model.provider],
+    allowedAuthOrigins: [model.provider],
+    thinking: false,
+    thinkingLevel: "off",
+    maxOutputTokens: 4096,
+  },
+});
+```
+
+`ModelContract`, `RouteRequest`, `ModelContractViolation`,
+`snapshotModelContract()`, and `assertModelContract()` are exported by
+`omk-agent-core`. No global setting enables this policy implicitly.
+
+The policy is copied and frozen. Each allowlist has 1–64 entries; identities are
+exact, bounded strings, not wildcards. Allowed models are provider/ID pairs.
+`allowedAuthOrigins` names logical credential resolvers, normally the provider;
+it does not authenticate an account or HTTPS origin.
+
+`thinking: false` forbids a requested reasoning level. `thinking: true` permits
+reasoning, while optional `thinkingLevel` pins the effective logical level.
+An absent level is `off` in the compatibility validator. The runtime supplies
+an explicit effective level when checking a request.
+
+Contract and explicit request limits must be positive safe integers. A larger
+explicit limit is rejected rather than silently clamped. When a runtime request
+omits `maxTokens`, the dispatch boundary supplies the smaller of the contract
+cap and model metadata cap. `assertModelContract()` alone retains compatibility
+with an omitted limit and does not fill it in.
+
+## Covered paths
+
+- In contract mode, tool-generated images do not trigger automatic vision routing.
+  For a text-only selected model, the provider view replaces those image blocks
+  with explicit uninspected-image notices and retains the existing text/tool IDs.
+  Original session attachments are unchanged. This is not OCR or visual analysis.
+  User-provided images still require a permitted vision route; they are not silently
+  discarded. A vision-capable selected model and non-contract routing retain their
+  existing behavior. The SDK summary stream uses the same projection.
+- Core prompt and continuation loops check the automatically selected route
+  before resolving its credentials. Policy remains fixed across lifecycle,
+  context, auth, and next-turn callbacks.
+- The SDK stream checks again before authentication, covering first-party
+  compaction and branch-summary calls that use `session.agent.streamFn`.
+  An explicitly requested summary cap above the policy is rejected, not reduced.
+- For `openai-completions`, the payload hook checks the serialized model ID and
+  exactly one defined `max_tokens` or `max_completion_tokens` before HTTP dispatch.
+  The cap must be a positive safe integer no larger than the effective logical
+  request cap. Missing, ambiguous, enlarged, or invalid limits are refused, even
+  without a user hook. Model identity is pinned before asynchronous callbacks.
+- Contracted payload hooks may observe detached immutable payload/model data or
+  return an equivalent payload. In-place changes and replacements are refused.
+  Optional `undefined` payload fields are accepted. Hook-return equivalence is
+  conservative JSON serialization equality, not arbitrary semantic equivalence.
+  Without a user observer, validation does not clone the conversation; nested
+  core/SDK enforcement shares the existing observation boundary.
+- Automatic cross-provider vision routing never forwards the source provider's
+  static API key, request headers, or model headers. This isolation also applies
+  when no contract is configured. Destination credentials must come from the
+  destination resolver or the provider's normal credential path.
+
+## Dispatch events
+
+Contracted **core-loop** calls emit:
+
+| Event | Meaning |
+| --- | --- |
+| `provider_denied` | A logical contract violation or observed cancellation prevented dispatch |
+| `provider_request` | The harness entered its stream-function dispatch boundary |
+| `provider_request_end` | That dispatch finished, errored, or aborted |
+
+`provider_request.omittedToolImages`, when present, counts tool attachments replaced
+in this request's provider view. It does not count visual interpretations or saved
+bytes in the session. A core contract denial becomes a non-retryable `configuration`
+termination rather than a provider-protocol diagnosis.
+
+`requestId` joins the events. Request and end events identify their boundary as
+`stream-dispatch`. Metadata excludes prompts, output, headers, keys, and raw
+errors. The end outcome is a transport/lifecycle result, not task correctness;
+`completed` does not mean an answer passed a verifier.
+
+A start event can be followed by an error before network transmission, including
+an observer or custom-stream error. An abort event does not prove that a remote
+request or custom stream has stopped. Auth/context failures before dispatch are
+not a complete attempted-request ledger. Summaries using the SDK wrapper are
+checked but do not yet emit these core-loop events. Persistence, run/attempt
+correlation, HTTP retry accounting, usage and billing joins remain follow-up work.
+
+## Limits and next steps
+
+The Chat Completions check validates the parameter sent by the first-party
+adapter, not the provider's interpretation or enforcement of it. Reasoning-token
+budgets, remote routing, response model identity, and actual charges still need
+separate evidence. Adapters that rewrite model names (for example, adding a
+namespace) are rejected by this exact-identity check unless the selected model ID
+already equals the transmitted ID.
+
+Other APIs still have only logical checks. For example,
+`adjustMaxTokensForThinking()` can add thinking tokens, and the inspected Codex
+request builder does not serialize `maxTokens`. Thus this contract is **not a
+universal output or billing cap**. A strict single-model benchmark still needs
+adapter-specific request provenance. For Model Studio's thinking fields and
+separate billing endpoints, see [the provider guide](providers.md#model-studio-deepseek-v4).
+
+Direct `omk-ai` calls, the separate `AgentHarness` family, advisory judges, child
+processes, custom streams that replace the SDK wrapper, and arbitrary extension
+code do not acquire this policy automatically. Extensions execute with their
+existing host permissions; freezing hook arguments does not isolate their code.
+Tool permissions, endpoint trust, effect idempotency, deadlines, and semantic
+completion still belong to their existing owners.
+
+A fresh build/restart is required to use source changes in an installed CLI.
+This implementation work did not build, install, deploy, change active settings,
+or run a paid benchmark. See [the boundary redesign](harness-boundaries.md) and
+ROADMAP §15 for dated evidence, limitations, and the remaining architecture work.

package/docs/models.md

@@ -4,7 +4,7 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.omk/a
 
 ## Table of Contents
 
-- [Built-in NVIDIA GLM-5.2](#built-in-nvidia-glm-52)
+- [Catalog availability](#catalog-availability)
 - [Minimal Example](#minimal-example)
 - [Full Example](#full-example)
 - [Supported APIs](#supported-apis)
@@ -16,9 +16,15 @@ Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.omk/a
 - [Anthropic Messages Compatibility](#anthropic-messages-compatibility)
 - [OpenAI Compatibility](#openai-compatibility)
 
-## Built-in NVIDIA GLM-5.2
+## Catalog availability
 
-With `NVIDIA_API_KEY` configured, `nvidia/z-ai/glm-5.2` supports OMK thinking levels through NVIDIA NIM. Its generated metadata explicitly enables `reasoning_effort`, so `/think max` is sent as `reasoning_effort: "max"`. Other NVIDIA models do not inherit that capability automatically.
+The NVIDIA catalog is filtered against NIM's live model IDs and known compatibility
+limits. A historical GLM route is not evidence that NIM still lists it. Use the
+current model selector rather than copying a removed ID from older examples.
+
+The [2026-09-09 catalog refresh](model-catalog-refresh.md) records new models,
+provider-specific thinking ladders, and verification limits. Model discovery does
+not prove that an account can invoke that model.
 
 ## Minimal Example
 
@@ -420,7 +426,18 @@ For providers with partial OpenAI compatibility, use the `compat` field.
 | `openRouterRouting` | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection). |
 | `vercelGatewayRouting` | Vercel AI Gateway routing config for provider selection (`only`, `order`) |
 
-`openrouter` uses `reasoning: { effort }`. `together` uses `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` uses top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that require `chat_template_kwargs.enable_thinking`.
+`openrouter` uses `reasoning: { effort }` for enabled thinking and
+`reasoning: { enabled: false }` for its supported off toggle. Mandatory-thinking
+models do not offer off. Declared per-route efforts override model-family guesses.
+`together` uses `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` uses top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that require `chat_template_kwargs.enable_thinking`.
+
+On official HTTPS Model Studio hosts, automatic defaults use `max_tokens`, the
+`system` role, and `enable_thinking`; OpenAI store and long-cache fields are omitted.
+The legacy `thinkingFormat: "deepseek"` override is translated to `qwen` on those
+hosts only. DeepSeek V4 also sends `reasoning_effort` when enabled; an explicit
+`supportsReasoningEffort: false` remains an opt-out. A custom proxy hostname needs
+explicit compatibility settings because its upstream protocol cannot be inferred.
+See [Model Studio endpoint and plan guidance](providers.md#model-studio-deepseek-v4).
 
 `cacheControlFormat: "anthropic"` is for OpenAI-compatible providers that expose Anthropic-style prompt caching through `cache_control` markers on text content and tool definitions.
 

package/docs/provider-resilience.md

@@ -21,7 +21,7 @@ Configure resilience in `~/.omk/agent/settings.json` or `.omk/settings.json`:
     "autoFailoverOnSafetyStop": true,
     "failoverCandidates": [
       { "provider": "kimi-coding", "id": "k3" },
-      { "provider": "modelstudio-maas", "id": "qwen3.8-max-preview" }
+      { "provider": "modelstudio-maas", "id": "qwen3.8-max" }
     ]
   }
 }
@@ -52,14 +52,16 @@ For a safety stop or recognized quota/billing error, OMK:
 
 A content/safety stop gets at most one automatic retry, including a retry that switches model, regardless of the larger transport retry budget. Other transient failures keep the configured retry policy and backoff. Plain authentication errors remain non-retryable and do not trigger failover.
 
-Recognized quota shapes include billing-cycle usage limits, `insufficient_quota`, exhausted balances, `GoUsageLimitError`, `FreeUsageLimitError`, and out-of-budget responses. These are classified as `provider.rate_limit`, even when a provider wraps them in HTTP 403.
+Recognized quota shapes include billing-cycle usage limits, `insufficient_quota`, exhausted balances, `GoUsageLimitError`, `FreeUsageLimitError`, and out-of-budget responses. These are classified as `provider.rate_limit`, even when a provider wraps them in HTTP 403. Provider-capacity bodies that omit a status or limit token are classified the same way: xAI `currently at capacity` / `high demand` (HTTP 429) and Anthropic `overloaded_error` / `Overloaded` (HTTP 529). Left unmatched they fall through to `provider.protocol` and advertise orphan-`tool_call_id` sanitize.
+
+Two HTTP 400s are permanent `configuration.invalid`, not retryable protocol faults: Anthropic `claude_code_version_too_old`, and Codex ChatGPT-account `The '<slug>' model is not supported when using Codex with a ChatGPT account.` Same-model retry, transcript sanitize, and `/new session` re-send the same client version or slug. Switch with `/model`, or for Codex use an API-key route that has the model.
 
 Gateway/upstream availability failures — "503 Upstream request failed", "Endpoint is unavailable", or a stream that ended without a finish reason — are classified as `provider.network`: transport problems that heal by retry or model switch, never by transcript sanitization.
 
 The default candidate order is:
 
 1. `kimi-coding/k3`
-2. `modelstudio-maas/qwen3.8-max-preview`
+2. `modelstudio-maas/qwen3.8-max`
 3. `xai/grok-4.5`
 4. `deepseek/deepseek-v4-pro`
 5. `deepseek/deepseek-v4-flash`

package/docs/providers.md

@@ -32,6 +32,41 @@ Alibaba Model Studio Token Plan is recognized as **QWEN TOKEN PLAN** and reads i
 
 With a stored native `xai` OAuth credential, OMK reads `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits` and shows the weekly SuperGrok pool from `config.creditUsagePercent` plus its reset from `config.currentPeriod.end`. `XAI_API_KEY` is a separate API-billing credential and does not authorize this subscription endpoint.
 
+### Model Studio DeepSeek V4
+
+Model Studio uses `enable_thinking`, including for DeepSeek. OMK's Chat Completions
+adapter recognizes official HTTPS DashScope and `*.maas.aliyuncs.com` hosts, defaults
+to `max_tokens` and the `system` role, and omits unsupported OpenAI store/long-cache
+fields. Legacy `thinkingFormat: "deepseek"` on these hosts is translated to the
+`enable_thinking` format. Native DeepSeek endpoints keep their native format.
+
+DeepSeek V4 sends the selected `reasoning_effort` when compatibility settings permit
+it. Without a model-specific mapping, `minimal` maps to the supported `low` value.
+An explicit `supportsReasoningEffort: false` still suppresses that field; remove
+that override or enable it for the model if you intend to send `high`, `xhigh`, or
+`max`. With thinking off, OMK sends `enable_thinking: false` rather than relying on
+the server default. See [custom model configuration](models.md#openai-compatibility).
+
+Keep the key paired with its purchased product and region. These are distinct
+billing paths, not interchangeable aliases:
+
+| Product | Example OpenAI-compatible base URL |
+| --- | --- |
+| Token Plan, Singapore | `https://token-plan.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1` |
+| Coding Plan, China | `https://coding.dashscope.aliyuncs.com/v1` |
+| Pay-as-you-go | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+
+Protocol detection never changes the URL, credentials, model ID, or subscription.
+For a comparison run, pin the exact Flash snapshot offered by that endpoint in
+both arms; `deepseek-v4-flash-0731` and an unversioned alias are not automatically
+the same experimental condition. Apply a [model contract](model-contract.md), and
+verify the installed adapter and final request before starting a benchmark.
+
+Sources: Alibaba's [DeepSeek API](https://www.alibabacloud.com/help/en/model-studio/deepseek-api)
+and [plan endpoint separation](https://www.alibabacloud.com/help/en/model-studio/token-plan-team-quickstart),
+consulted 2026-09-08. The local tests exercise serialization, not account availability,
+provider compliance, billing, or benchmark performance.
+
 ### OpenAI Codex
 
 - Requires ChatGPT Plus or Pro subscription
@@ -94,6 +129,7 @@ omk
 | Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
 | Together AI | `TOGETHER_API_KEY` | `together` |
 | Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
+| Meta Model API | `META_API_KEY` (or `META_MODEL_API_KEY`, `MODEL_API_KEY`) | `meta` |
 | MiniMax | `MINIMAX_API_KEY` | `minimax` |
 | MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
 | Xiaomi MiMo | `XIAOMI_API_KEY` | `xiaomi` |
@@ -106,7 +142,38 @@ Reference for environment variables and `auth.json` keys: [`const envMap`](https
 
 #### NVIDIA NIM
 
-Set `NVIDIA_API_KEY` and select an NVIDIA model with `/model`. The built-in `nvidia/z-ai/glm-5.2` entry sends `reasoning_effort`, including the `max` level. Other NVIDIA models keep conservative compatibility defaults unless their model metadata explicitly enables reasoning effort.
+Set `NVIDIA_API_KEY` and select a currently listed NVIDIA model with `/model`.
+NIM entries are filtered against its live `/v1/models` list; historical GLM examples
+may no longer be listed. Thinking capabilities stay model-specific. See the
+[latest catalog audit](model-catalog-refresh.md) for source coverage and limits.
+
+#### Meta Model API
+
+Meta's first-party [Muse Spark](https://dev.meta.ai/docs/overview) endpoint, served over the OpenAI
+Responses API at `https://api.meta.ai/v1`:
+
+```bash
+export META_API_KEY=...
+omk --provider meta --model muse-spark-1.3
+```
+
+Two auth paths:
+
+- **Subscription:** `/login` → Use a subscription → Muse Code. Device-code sign-in at
+  `auth.meta.com`, then a mint at `https://api.meta.ai/muse-code/key`. Honors `HTTP_PROXY` /
+  `HTTPS_PROXY`. The minted key is what inference uses.
+- **Pay-as-you-go:** `META_API_KEY` (then `META_MODEL_API_KEY`, then `MODEL_API_KEY`), or paste a
+  Model API key under `/login` → Use an API key → Meta Model API. Extra keys you create on the
+  dashboard are billed [per token](https://dev.meta.ai/docs/muse-code/subscriptions), even with an
+  active Muse Code subscription.
+
+Standard tier: `muse-spark-1.3`, `muse-spark-1.2`, `muse-spark-1.1`. Contributor tier:
+`muse-spark-1.3-contributor`, `muse-spark-1.2-contributor`. All carry a 1M-token context window.
+
+Thinking levels run `minimal` → `max`. Muse Spark's own effort ceiling is `xhigh`, which its docs
+call "maximum reasoning depth", so omk's `max` level maps onto `xhigh` rather than sending an enum
+the API would reject. Thinking cannot be switched off: Muse Spark rejects `reasoning_effort: "none"`
+with HTTP 400, so omk never sends it.
 
 #### Zyloo
 

package/docs/quickstart.md

@@ -85,6 +85,10 @@ Additional built-in read-only tools (`grep`, `find`, `ls`) are available through
 
 ## Give omk project instructions
 
+For optional, portable user defaults, preview `omk init --global --dry-run`, then
+run `omk init --global`. Existing instructions and settings are preserved.
+See [User context setup](context-files.md) for migration, loading, and interoperability.
+
 OMK loads context files at startup. Add an `AGENTS.md` file to tell it how to work in a project:
 
 ```markdown

package/docs/release-audit-0.98.3.md

@@ -0,0 +1,97 @@
+# Release audit: v0.98.3
+
+Date: 2026-09-06. Target: seven lockstep npm packages, GitHub Release and a tag on `main`.
+This audit is release engineering evidence, not algorithm accuracy or correctness proof.
+
+## Source and scope
+
+The published v0.98.2 tag was `7e10858f5ecfeee1eea5364a2f21336c5c416f11`.
+The working algorithm branch at `60f520f0c103888ef27438ac5058bdfc78b3e409` had forked before
+that release and still declared 0.98.1. Its four committed evidence-library changes were
+merged with remote main `92dca0f598243a38de156bbe4d099e3e60414cb6` in a separate clean
+publication checkout. The merge preserves the original release ancestry; it does not move
+the v0.98.2 tag or rewrite published changelogs.
+
+Included new work:
+
+- the four committed trace/effect/claim-closure/VERA projection changes;
+- the reviewed advisory SDK integrity patch, tests and specification;
+- release-facing documentation, manifest/lock/shrinkwrap alignment and publication-auth truth.
+
+Excluded: unrelated uncommitted provider integrations, UI, context-init and reverse-skill
+changes, private agent-home material, the untracked algorithm-copy document, research data,
+sessions, local temporary output and optional generated wiki corpora. The original dirty
+working tree was not reset, stashed, broadly staged or copied into the release.
+
+## Public package manifest
+
+| Package | Version | Role |
+| --- | --- | --- |
+| `open-multi-agent-kit` | `0.98.3` | CLI and explicit advisory/evidence SDK |
+| `omk-ai` | `0.98.3` | Provider API; lockstep, no catalog refresh in this release |
+| `omk-agent-core` | `0.98.3` | Runtime; internal trace/effect primitives |
+| `omk-tui` | `0.98.3` | TUI; lockstep |
+| `omk-protocol` | `0.98.3` | Run and claim-closure contracts |
+| `omk-adaptorch-wpl` | `0.98.3` | Explicit WPL and proof/VERA projections |
+| `omk-book-to-skill` | `0.98.3` | Optional document compiler; lockstep |
+
+The root/workspace manifests, internal dependency ranges, root/example lockfiles,
+book compiler version constant and CLI `npm-shrinkwrap.json` are synchronized.
+Model catalogs are not fetched or regenerated. No API is intentionally removed.
+The new `judge-tied` reason and stricter normal-stop requirement are documented in
+[Advisory selection integrity](advisory-selection.md).
+
+## Changelog and document audit
+
+- Each public package has a changelog; new protocol/book changelogs explicitly state their
+  historical limits instead of fabricating entries for old versions.
+- Root/package README release links and document-compiler install pins name v0.98.3.
+- The runtime-algorithm audit distinguishes its historical v0.97.0 snapshot from subsequent
+  v0.98.0 guards and the new v0.98.3 library scope.
+- Internal agent modules are not advertised as default runtime authority or root exports.
+- The actual workflow is token-authenticated GitHub CI. The earlier constitution claimed
+  OIDC despite an existing token-only job. A failing-first test exposed that mismatch; the
+  documentation now matches the unchanged workflow. No token was read or replaced.
+
+## Local verification
+
+The first full keyless pass used an isolated temporary HOME. All affected tests passed but
+one Rust diagnostics test could not find its rustup toolchain. Supplying the non-secret
+`RUSTUP_HOME` path restored that fixture: 6/6 diagnostics tests passed. No production code
+was changed to suppress this environment failure. Final release checks are run again on the
+bumped candidate with the isolated HOME and explicit toolchain path.
+
+Final local results on the 0.98.3 candidate:
+
+| Gate | Result |
+| --- | --- |
+| Seven-workspace build | PASS |
+| `npm run check` | PASS; informational legacy switch-case findings only |
+| `check-release-consistency --release` | PASS; v0.98.2 ancestor, all surfaces 0.98.3, no drift |
+| Full keyless workspace tests | 7,124 passed, 821 skipped, 0 failed |
+| Test breakdown | WPL 116, agent 640, AI 487, book compiler 22, coding-agent 5,109, protocol 25, TUI 725 |
+| Go initcheck vet/race/shuffle + native symbol validation | PASS |
+| Committed algorithm/staged patch gitleaks | No leaks found |
+| Seven npm dry-run packs | 0.98.3, each carries CHANGELOG.md, restricted-path matches 0 |
+| Existing five changelog histories from v0.98.2 | Byte-preserved |
+| Clean-environment compiled CLI | Reports 0.98.3 |
+
+The first tarball inspection exposed that six package `files` allowlists omitted changelogs.
+A failing-first release test now requires each public package to ship its current dated
+changelog; all six allowlists were corrected. The publication helper's misleading automatic
+CI-provenance message was also corrected without changing authentication behavior.
+
+An inherited `OMK_PACKAGE_DIR` pointed the local smoke command at older package metadata.
+Unsetting only that override changed its reported version from 0.98.1 to 0.98.3, and a fully
+clean environment confirmed 0.98.3. The override was not changed globally; the isolated build
+and package manifests are the release subject.
+
+A local pass is not a completed npm publication: the matching tag workflow must still pass,
+and npm `latest` plus GitHub Release must agree on the version.
+
+## Publication boundary
+
+The existing `build-binaries.yml` workflow verifies source/tag identity, builds six platform
+archives, validates and publishes npm packages, then creates the GitHub Release. Publishing
+uses the existing environment-scoped granular token; OIDC/Sigstore provenance is not claimed.
+No local `npm publish`, credential rotation, gate bypass or force-push is part of this release.