open-multi-agent-kit 0.99.0 → 1.2.0

package/docs/model-catalog-refresh.md

@@ -3,6 +3,115 @@
 확인일: 2026-09-09. 생성기와 공급자 어댑터를 수정한 뒤 `npm run models:refresh`로
 두 카탈로그를 재생성했다. 생성 파일을 손으로 수정하지 않았다.
 
+## 2026-09-19 갱신: 라이브 재생성과 생성기 결함 3건 교정
+
+`npm run models:refresh`를 종료0으로 재생성했다(전 소스 응답, `--allow-partial` 미사용,
+키 없는 Zyloo는 정적 6개 유지). 결과는 **39 providers, 1,795→1,799 모델**, 추가 4·제거 0·
+변경 22(가격 20, OpenRouter 선언 thinking 2), 이미지 카탈로그 54개 변화 없음.
+
+첫 재생성에서는 제거 4·변경 220이 나왔고, 그중 상류 변화가 아닌 항목이 셋이었다.
+각각 실패하는 검사를 먼저 쓰고(11개 RED) 생성기를 고친 뒤 다시 생성했다.
+
+| 결함 | 원인 | 조치 |
+| --- | --- | --- |
+| `kimi-coding` 공급자 4개 전부 소실 | models.dev가 `kimi-for-coding` 키를 `kimi-code-plan-global`(api.kimi.ai)·`kimi-code-plan-cn`(api.kimi.com)으로 분리. 생성기는 옛 키만 읽어 조용히 빈 결과 | 세 키를 순서대로 조회. OMK endpoint(`api.kimi.com/coding`)·헤더·thinking 맵은 그대로. `kimi-coding-catalog.test.ts` |
+| cursor 143·devin 55개 고정-노력 레인에 `xhigh/max` 추가 | 직전 커밋은 `--cursor-only`로 가족 단위 pass를 우회했지만 전체 재생성은 `applyModelMetadata`(Fable→xhigh/max, Opus 5→전체 사다리 등)를 정적 레인에도 적용 | devin/cursor 항목을 pass 이후에 붙여 fast path와 동일하게 유지. `fixed-effort-lanes.test.ts`가 정적 카탈로그와 생성 결과의 동일성을 검사 |
+| OpenCode Zen `deepseek-v4.1-flash`가 구형 V4 맵(`high`, `xhigh→max`)만 받음 | V4.1 계약 보정 조건이 `opencode-go`만 인식 | [Zen 문서](https://opencode.ai/docs/zen/)가 같은 `chat/completions` gateway를 명시하므로 `opencode`도 `off/low/high/max`·`max_tokens`·`supportsReasoningEffort` 적용. `deepseek-v41-native.test.ts` route에 추가 |
+
+두 번째 결함은 cursor/devin 항목이 정적 카탈로그와 다르게 저장될 때 즉시 실패하므로,
+앞으로 fast path와 전체 재생성이 갈라지면 검사에서 드러난다.
+
+### 추가된 항목
+
+| 공급자 | 요청 ID | thinking | 가격(1M) | 근거 |
+| --- | --- | --- | --- | --- |
+| `opencode` | `deepseek-v4.1-flash` | `off/low/high/max`, `thinking.type`+`reasoning_effort`, `max_tokens` | $0.30/$1.20, cache $0.006 | Zen 문서 endpoint·가격표 |
+| `opencode` | `qwen3.8-flash` | Messages 예산 경로(기존 Zen Qwen과 동일) | $0.15/$0.47, cache read $0.016·write $0.20 | Zen 문서 |
+| `openrouter` | `z-ai/glm-5.3-flashx` | mandatory, `low/high/max` (route 선언) | $0.37/$1.25, cache $0.075 | OpenRouter `created` 09-18 |
+| `openrouter` | `prism-ml/ternary-bonsai-2-27b` | optional off, `medium/xhigh` (route 선언) | $0.075/$0.50 | OpenRouter `created` 09-18 |
+
+### 상류 변경(가격·선언)
+
+- OpenCode Zen·Vercel의 `gpt-5.6-sol`은 "50% Off" 표시가 끝나 $4/$20(cache $0.40/$5)로 복귀. Vercel `gpt-5.6-sol-fast`는 $8/$40.
+- OpenRouter DeepSeek 계열 인하: `deepseek-v4.1-flash` $0.15/$0.60, `deepseek-v4-pro` $0.54/$1.09, `-latest` 별칭 3개 동반 조정.
+  목록 값이며 DeepSeek 직접 API의 시간대별 가격과 다르다.
+- OpenRouter `moonshotai/kimi-k3`·`~moonshotai/kimi-latest` $1.70/$8.50, `z-ai/glm-5.3` $0.91/$2.86, `meta/muse-glimmer-30b` $0.35/$1.50, Nemotron 3 Ultra·3.5 Lightning 출력 상한 상향.
+- `upstage/solar-pro-3`(`off/minimal~high`)·`solar-pro4`(`off/minimal~max`)가 route 선언을 얻어 thinking 맵이 생겼다.
+
+### 조사했으나 넣지 않은 항목
+
+- **Amazon Bedrock Kimi K3** (09-18 GA). [모델 카드](https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-moonshot-ai-kimi-k3.html)
+  기준 ID `global.moonshotai.kimi-k3`(Global $3/$15, cache read $0.30·write $3.75) ·
+  `us.moonshotai.kimi-k3`(US $3.30/$16.50), in-region 없음, 1M context, 이미지 입력, Converse·도구·스트리밍 지원.
+  같은 카드가 "Converse는 이전 턴의 reasoning content가 포함되면 `InternalServerException`"을 명시하는데,
+  OMK `amazon-bedrock`은 non-Claude 모델의 thinking을 `reasoningContent`로 그대로 replay한다(`convertMessages`).
+  카탈로그만 넣으면 두 번째 턴부터 실패하는 경로를 광고하므로, 공급자에서 이전 턴 reasoning을 제거하는
+  수정과 유료 실검증을 묶은 후속 단위로 미룬다. models.dev bedrock 목록에도 아직 없다.
+- **Qwen3.8-Omni-Flash** (Alibaba, 09-18): OpenRouter·Vercel·models.dev의 tool 지원 목록에 없다. Model Studio 직접 경로는 OMK 내장 공급자가 아니다.
+- **Gemini 3.8 Live / Live Extended Thinking** (09-15~16): 오디오 네이티브 경로로 코딩 카탈로그 소스에 없다.
+- **GPT-6 Astra Law** (`gpt-6-astra-law`): OpenAI가 "coming soon"으로만 공지, API 미제공.
+- **Union Alpha**: `stealth/union-alpha`는 09-18 갱신에서 이미 빠졌고, 정식 `unbiased/pareto`($2.50/$7.50, cache $0.25, thinking 미선언)가 HEAD에 있다. 이번 갱신에서 변화 없음.
+
+### 검증과 한계
+
+표적 vitest 13파일 **149개 통과**(신규 `fixed-effort-lanes`·`kimi-coding-catalog`, 확장한
+`deepseek-v41-native` 포함), 전체 `tsgo --noEmit`, 변경 파일 Biome, module-size·import-cycles
+ baseline, `git diff --check` 모두 종료0. 공급자 추론, 전체 `npm run check`, build/install,
+commit/push는 실행하지 않았다. 계정별 사용 가능 여부와 실제 청구액은 검증 범위 밖이다.
+
+변경 단위: `packages/ai/scripts/{generate-models,catalog-thinking}.ts`, 생성 카탈로그, 검사 3파일, 본 문서.
+제안 메시지: `fix(ai): 모델 카탈로그 09-19 갱신과 생성기 결함 교정 (kimi-coding 소실·고정 레인 확장·Zen V4.1 계약)`.
+
+## 2026-09-17 후속: OpenCode Go DeepSeek V4.1 ID 변경
+
+[OpenCode Go 공식 endpoint 목록](https://opencode.ai/docs/go/)의 현재 ID는
+`deepseek-v4.1-flash`다. 직접 DeepSeek의 `deepseek-flash`와 구분한다.
+9월 17일 카탈로그 갱신은 새 ID를 반영했지만, 생성기의 V4.1 메타데이터 보정은
+이전 ID만 인식해 `low/max`와 `max_tokens` 설정이 누락됐다.
+
+생성기 조건에 Go의 새 ID를 추가하고 기존 Go ID의 보정도 유지했다. 회귀 테스트는
+공급자별 실제 요청 ID를 사용하며 `off/low/high/max`, 이미지 입력, 출력 상한,
+전송 직전 `thinking`과 `reasoning_effort` 검사를 그대로 유지한다.
+ID만 교체한 상태에서도 5개 실패가 재현됐으며 메타데이터 수정 후 통과했다.
+
+`node packages/ai/scripts/generate-models.ts`로 생성한 결과 중 해당 Go 모델의
+메타데이터 변경만 포함했다. 실시간 목록에서 함께 발생한 다른 모델의 추가/삭제,
+가격/상한 변경은 이번 수정에 포함하지 않았다. 생성 파일 값을 수작업으로 만들지 않았다.
+공급자 추론이나 계정별 사용 가능 여부는 검증하지 않았다. 아래 9월 10일 표는 당시 기록이다.
+
+## 2026-09-17 갱신: OpenRouter Union Alpha (stealth)
+
+`stealth/union-alpha` 추가 요청으로 `npm run models:refresh`를 종료0으로 재생성했다.
+생성 파일은 손대지 않았다. 전 소스가 응답했고 `--allow-partial`은 쓰지 않았다.
+
+| 항목 | 값 |
+| --- | --- |
+| 요청 ID | `stealth/union-alpha` (OpenRouter) |
+| context / maxTokens | 262,144 / 131,072 |
+| 입력 | text, image |
+| tool 지원 | `tools`, `tool_choice` |
+| 가격 | prompt/completion 모두 `0` |
+| **thinking** | **없음 — route가 `reasoning`을 선언하지 않음** |
+
+목록과 `/api/v1/models/stealth/union-alpha/endpoints` 모두
+`supported_parameters`가 `max_tokens, temperature, top_p, tools, tool_choice,
+response_format`이다. `reasoning`도 `include_reasoning`도 없다. 선언이 없으므로
+수준을 지어내지 않고 `reasoning: false`로 들어갔으며 `thinkingLevelMap`도 없다.
+이름이 frontier 계열을 연상시킨다는 이유로 effort를 이식하지 않는다.
+
+`created`는 2026-09-16으로 직전 갱신(09-09) 이후에 생긴 항목이다. 한 모델만
+집어넣는 경로가 없어 카탈로그 전체가 8일치 드리프트를 함께 반영한다.
+OpenRouter 371 → 376, 전체 추가 57 · 제거 28(고유 4)이다. 제거는
+`deepseek.r1-v1:0`과 mistral `devstral-small-2` · `mistral-medium` · `pixtral-12b`로,
+갱신 소스에서 더 이상 선정되지 않았다는 뜻이며 공급자의 폐기 공지나 모든 계정의
+사용 불가를 뜻하지 않는다.
+
+가격 `0`은 stealth 공개 기간의 목록 값이다. 무상 사용을 보장하지 않으며 stealth
+해제 시 달라질 수 있다. 실제 청구는 계정에서 따로 확인한다.
+
+표적 검사 `latest-model-thinking` · `catalog-thinking` · `latest-thinking-payload`
+51개가 통과했다. 공급자 추론은 호출하지 않았다.
+
 ## 2026-09-10 재검증: DeepSeek V4.1 Flash 제공 경로
 
 공식 문서·공개 API에서 확인한 기존 OMK 공급자 4곳을 반영했다.
@@ -114,7 +223,7 @@ OpenRouter의 `reasoning.supported_efforts`로 표시할 수준을 만들고,
 
 | 모델·route | 이번 정합성 규칙 |
 | --- | --- |
-| GPT-6 Astra, OpenAI/Responses 및 OpenRouter | low·medium·high·xhigh·max. off/minimal 미노출 |
+| GPT-6 Astra, OpenAI/Responses 및 OpenRouter | low·medium·high·xhigh·max. OMK `ultra`는 공식 천장 `max`의 선택기 별칭이며 와이어에 `ultra`를 보내지 않음. 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로 처리하며 완전 비활성화로 주장하지 않음 |

package/docs/models.md

@@ -233,7 +233,7 @@ Current behavior:
 
 ### Thinking Level Map
 
-Use `thinkingLevelMap` on a model to describe model-specific thinking controls. `models.json` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Built-in metadata can also expose the `ultra` CLI tier, but the current `models.json` schema has no `ultra` key.
+Use `thinkingLevelMap` on a model to describe model-specific thinking controls. `models.json` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Built-in metadata can also expose the `ultra` CLI tier (GPT-6 Astra maps it to documented `max`; GPT-5.6 Sol/Terra/MoA on Codex map it to backend `xhigh`), but the current `models.json` schema has no `ultra` key.
 
 | Value | Meaning |
 | --- | --- |

package/docs/neo.md

@@ -0,0 +1,134 @@
+# Neo public skills and computer-use setup
+
+Status: locally integrated and built on 2026-09-17, not a published release. Neo names the public computer-use workflow in this change; it is not a new model or an independent agent runtime.
+
+## What changes
+
+The normal `DefaultResourceLoader` now reads six publicly authored skills from `resources/neo/skills` inside the installed package. No private agent-home content is copied. Explicit, project and user skills retain ownership of matching names; bundled skills fill only missing names. `noSkills` disables automatic bundled loading while preserving explicitly supplied skills, and `OMK_BUNDLED_SKILLS=0` disables just the bundled set. Skill overrides continue to run after resource loading.
+
+Both the npm package allowlist and the two binary asset paths include the same `resources` tree. Files remain inside the installation; startup does not write skills into the user's home. A missing bundle produces a loader diagnostic, and `omk neo list` returns a nonzero exit code if one of its required skill files is missing.
+
+| Default skill | Purpose |
+| --- | --- |
+| `omk-computeruse` | Neo target/capability routing and observe, act, verify workflow |
+| `omk-browser` | DOM/accessibility interaction, bounded retries and side-effect approval |
+| `omk-site` | Existing-project site implementation, preview and responsive validation |
+| `omk-research` | Version-aware primary documentation and evidence handling |
+| `omk-code-review` | Minimal changes, real regression checks and live-call-path review |
+| `omk-mcp-setup` | Inventory, configuration preview, explicit setup and health verification |
+
+These instructions are available independently of the selected model family. Tool calling must actually work. Image interpretation additionally requires compatible model and provider input support. Text-only models should use DOM/accessibility observations. This change does not establish Astra-equivalent performance, add a native desktop driver, or turn an incapable model into a computer-use model.
+
+## Skills and MCPs are different products
+
+| Quantity | Meaning |
+| --- | --- |
+| Packaged skill | Instruction file is present in the installation |
+| Loaded skill | Resource loader admitted the file after overrides and disable settings |
+| Offered MCP | Public configuration preset is available |
+| Configured MCP | User selected a server in a configuration file |
+| Connected MCP | The running process completed its connection/handshake |
+| Verified tool | A discovered tool succeeded against the intended target |
+
+`omk neo list` reports packaged files and offered presets. It deliberately returns `connected: null` and `connectionStatus: "not_probed"`; it does not manufacture a nonzero MCP connection count. The normal session MCP status remains the connection authority.
+
+## Curated MCP choices
+
+| Preset | Distribution | Activation | Scope |
+| --- | --- | --- | --- |
+| `playwright` | Pinned stdio recipe for `@playwright/mcp@0.0.81` | Explicit user setup | Browser actions and accessibility snapshots; compatible browser required |
+| `context7` | Pinned stdio recipe for `@upstash/context7-mcp@4.1.1` | Explicit user setup | External technical documentation queries |
+| Native CUA/desktop driver | Not installed or configured by this change | Separate reviewed setup | Host permissions and host identity must be verified |
+| Chrome personal-profile attachment | Not enabled by default | Separate explicit session approval | May expose existing authenticated state |
+| Stagehand and Browserbase cloud | Not installed or configured by this change | Separate dependency, credentials and cost approval | Optional local library or cloud browser |
+| Account-connected repository/services | Not configured by this change | Per-user authentication and scope approval | No publisher credential is shared |
+
+The recipes pin the direct package version, not an entire third-party transitive dependency graph. They do not bundle executables or browser binaries. Installation and tool behavior still need to be tested on the target platform. No remote HTTP URL is advertised as directly loadable by the current stdio-only OMK loader.
+
+## Commands
+
+```bash
+omk neo list
+omk neo setup playwright context7
+omk neo mcp-config playwright context7
+```
+
+All three are local and do not start a process, download a server or connect a browser. `setup` without `--apply` is a dry run. `mcp-config` emits disabled entries only. Existing configuration is never printed.
+
+After approving the exact target and the server execution/network effects:
+
+```bash
+# Project-local, in the intended project directory:
+omk neo setup playwright context7 --apply
+
+# Alternative: explicitly select the global configuration target:
+omk neo setup playwright context7 --global --apply
+```
+
+Project target: `<cwd>/.omk/mcp.json`. Global target: `~/.omk/mcp.json`, not `~/.omk/agent/mcp.json`. On the next ordinary OMK startup `npx` may download and execute the selected pinned servers. The command itself only creates configuration and reports `configured_not_connected`. A project entry can override a global entry with the same server name.
+
+Setup is intentionally no-overwrite. It validates all presets before filesystem changes, writes a complete temporary file with mode `0600` and publishes it through an atomic no-replace hard link. An existing target, including malformed data or a symlink, is preserved. A symlinked `.omk` directory is rejected. Filesystems that do not support hard links fail closed. This is not a defense against a hostile process concurrently replacing an ancestor directory; use a trusted user-owned configuration location. Windows ACL and power-loss durability guarantees are outside this implementation.
+
+For an existing configuration, generate disabled entries with `mcp-config`, then review a manual merge without exposing secrets. Do not replace the file to work around the refusal. This change does not alter legacy MCP config precedence or overwrite any account settings.
+
+## Browser safety and capability
+
+The Playwright recipe requests `--headless --isolated --sandbox` and bounded action/navigation timeouts. It does not attach to a personal browser, disable TLS checks or request unrestricted file access. The upstream Linux bundled-browser default can disable its sandbox; the explicit positive flag is therefore intentional. A sandbox launch failure must be diagnosed rather than bypassed.
+
+Profile isolation is not OS or network isolation. Origin allowlists are not complete redirect or SSRF boundaries. Operator-managed process/network isolation is required for stronger threat models. The workflow rejects instruction authority from pages, tool output and server descriptions. Skills guide the model; they do not independently enforce every permission boundary in the runtime.
+
+After configuration, restart the intended OMK process, inspect the actual connection status and tool roster, and perform a read-only health check. Then use an observation before each action and verify the final requested state. A timeout is not permission to repeat a non-idempotent operation. Native desktop, paid cloud and private-account actions remain separate opt-ins.
+
+## Verification and release gates
+
+Harness impact: `advance` for distributable capability discovery; `preserve` for existing skill precedence, disable behavior and configuration ownership. Baseline is `739bc6f3b6fe1c89bfe058aad7ec17ad252fb10e` (`0.99.0`).
+
+Acceptance: six valid files in the npm and each platform bundle; six default skills in an empty agent/project environment; zero writes on list/dry run; byte-identical preservation of existing MCP config; no false connected count. No performance superiority claim is made.
+
+```bash
+node --experimental-strip-types --test scripts/test/neo-distribution.test.mjs
+cd packages/coding-agent
+node ../../node_modules/vitest/dist/cli.js --run test/neo-distribution.test.ts
+cd ../..
+npm run check
+npm run build
+```
+
+The Node test covers actual catalog/CLI/setup functions, file preservation, symlinks and asset inclusion declarations. The Vitest test additionally exercises the real skill loader and `DefaultResourceLoader`; it requires the repository dependencies and a buildable base. Source inspection of binary copy commands is not a built-binary smoke test. Each final archive must be extracted and `omk neo list` checked before release.
+
+Before publishing, run the targeted tests and complete repository gates, verify a clean npm install and real MCP/browser smoke tests, then follow the existing lockstep release procedure. A green test for a leaf module cannot override a failed monorepo build. Do not tag/publish this candidate until all release surfaces agree and blockers are resolved.
+
+## Local installation verification, 2026-09-17
+
+Integrated the candidate onto `887152bc5d`. `npm run build` and `tsgo --noEmit`
+passed. Standalone source tests passed 13 checks; Neo, resource-loader and SDK skill
+Vitest suites passed 39 tests. The Neo fixture isolates HOME and the agent directory
+so personal skills cannot contaminate its six-skill assertion.
+
+The existing local launcher resolves this checkout's `dist/cli.js`; its `neo list`
+reported all six packaged skills. The built resource loader also selected six skills
+in a clean environment. `npm pack --ignore-scripts --dry-run --json` included all six.
+Run `node --test scripts/test/neo-built-cli.test.mjs` after building for subprocess
+checks of list, write-free preview, apply and no-replace behavior.
+
+No live MCP configuration was created or overwritten. The existing Playwright
+connection answered a tab-list request and opened/closed a task-owned blank tab;
+this does not verify the candidate preset's browser or sandbox flags. Existing
+Context7 returned an invalid API-key error, so documentation retrieval is blocked.
+No credentials were changed and no native desktop driver was installed.
+
+Full `npm run check` stopped at pre-existing module-size failures in `agent-session.ts`
+and `model-registry.ts`. The documentation link guard also rejects the new untracked
+`neo.md` until it is included in Git; no files were staged to bypass that gate.
+Release-surface and shrinkwrap checks passed. Platform archives, clean dependency
+installation, all-suite tests and published release verification remain unrun.
+Restart OMK to load rebuilt code; changing source does not update an active process.
+
+## Primary source check, 2026-09-16
+
+- Playwright MCP release `v0.0.81`: https://github.com/microsoft/playwright-mcp/releases/tag/v0.0.81
+- Exact documented flags: https://github.com/microsoft/playwright-mcp/blob/v0.0.81/README.md
+- Context7 release `@upstash/context7-mcp@4.1.1`: https://github.com/upstash/context7/releases/tag/%40upstash/context7-mcp%404.1.1
+- Context7 stdio CLI: https://github.com/upstash/context7/blob/master/packages/mcp/src/index.ts
+
+Upstream source/release inspection is not an installed-server integration test. Credentials, provider quality and target-host permissions are not verified by this document.

package/docs/providers.md

@@ -25,7 +25,7 @@ Run `/login` and choose a configured subscription provider to open its account p
 
 Use `/logout` to clear all stored accounts for a provider. Tokens are stored in `~/.omk/agent/auth.json` and auto-refresh when expired.
 
-When the status sidebar is pinned, its **USAGE** section lists every configured subscription provider, with the active provider first. OMK reads quota windows from fixed provider endpoints for Codex, Claude, Kimi Code, GLM/ZAI Coding Plan, and native xAI SuperGrok, caches the result, and displays each percentage and reset countdown separately. Claude also passively merges the official `anthropic-ratelimit-unified-*` response headers used by Claude Code. If Anthropic's usage endpoint is rate limited and no complete recent snapshot exists, OMK mirrors Claude Code's own startup quota check with one fixed-endpoint Haiku request capped at one output token, no more than once per OAuth credential per hour. This fallback consumes a small amount of Claude plan quota.
+When the status sidebar is pinned, its **USAGE** section lists every configured subscription provider, with the active provider first. OMK reads quota windows from fixed provider endpoints for Codex, Claude, Kimi Code, GLM/ZAI Coding Plan, native xAI SuperGrok, Devin CLI, and Command Code, caches the result, and displays each percentage and reset countdown separately. Claude also passively merges the official `anthropic-ratelimit-unified-*` response headers used by Claude Code. If Anthropic's usage endpoint is rate limited and no complete recent snapshot exists, OMK mirrors Claude Code's own startup quota check with one fixed-endpoint Haiku request capped at one output token, no more than once per OAuth credential per hour. This fallback consumes a small amount of Claude plan quota.
 
 Codex streaming passively merges `x-codex-primary-*`, `x-codex-secondary-*`, and `codex.rate_limits` signals through the non-blocking `StreamOptions.onRateLimit` observer. These signals supplement missing polling windows only when the Codex service returns them; OMK does not infer a missing 5-hour value from a 7-day value.
 
@@ -33,6 +33,8 @@ 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.
 
+With a configured `commandcode` API key (`models.json` or auth storage), OMK reads `GET https://api.commandcode.ai/alpha/whoami`, then `/alpha/billing/credits`, `/alpha/billing/subscriptions`, and `/alpha/usage/summary` on that same origin. The rail shows the 5-hour and weekly credit windows plus the monthly pool (`spent / remaining+spent`) and the plan name. OMK never sends the key anywhere except `api.commandcode.ai`, never reads browser cookies, and does not scrape Studio.
+
 ### Model Studio DeepSeek V4
 
 Model Studio uses `enable_thinking`, including for DeepSeek. OMK's Chat Completions
@@ -83,6 +85,19 @@ Your account's model access and quota still apply. For presets, effort guidance,
 the 1M-token context budget, and the `devin-harness` loadout, see the
 [Devin SWE-2 harness](devin-harness.md).
 
+The `devin` catalog also carries every other lane `GetCliModelConfigs`
+advertises — each wire UID is its own logical model (`claude-opus-5-high`,
+`gpt-5-6-sol-xhigh`, `gemini-3-8-flash-medium`, `kimi-k3-max`, `glm-5-3-high`,
+`grok-4-6-xhigh`, `deepseek-v4-pro-max`, `swe-1-7`, `inkling-max`, …). Flat
+models pin their declared effort lane, so `/think` is fixed per model; entries
+whose lane is a no-thinking variant report `reasoning: false`. Availability is
+account- and plan-dependent: a lane absent from your catalog fails loudly
+instead of being remapped. Image input is still text-only at the adapter.
+
+```bash
+omk --provider devin --model claude-opus-5-high
+```
+
 **Authentication.** OMK uses the CLI's PKCE flow at
 `app.devin.ai/auth/cli/continue` and `api.devin.ai/auth/cli/token`. Its callback
 binds only to `127.0.0.1:59653`, validates state, and closes after success,
@@ -99,10 +114,12 @@ Devin agent, read browser cookies, or import another application's credentials.
 
 **Transport and limits.** The Node-only `devin-agent` adapter uses Connect/protobuf
 at the fixed HTTPS origin `https://server.codeium.com`. It exchanges the session
-token for a user JWT and reads `GetCliModelConfigs` before each turn. The server's
-SWE-2 family metadata supplies the effort's exact wire UID; OMK never invents a
-`swe-2-max` ID or downgrades an unavailable route. Disabled, internal, ambiguous,
-and fast-lane entries are excluded. The family's separate 1M-context entries form
+token for a user JWT and reads `GetCliModelConfigs` before each turn. The logical
+`swe-2` model resolves its effort through the server's SWE-2 family metadata;
+every other catalog model resolves by its own wire UID. OMK never invents a
+`swe-2-max` ID or downgrades an unavailable route. Disabled, internal, and
+ambiguous entries are excluded; fast-lane entries match only when their own UID
+is selected. The family's separate 1M-context entries form
 a second lane that is selected only when the model's local `contextWindow` is
 1,000,000 or more (the bundled default); a smaller budget uses the standard lane.
 
@@ -139,9 +156,49 @@ and the [official manifest](https://static.devin.ai/cli/current/manifest.json)
 (observed identity `3000.10.21`). Protocol fields follow the third-party
 [oh-my-pi snapshot](https://github.com/can1357/oh-my-pi/blob/942383f768c5f2f6a620fcab57326c0f59df623a/packages/catalog/src/discovery/devin-proto.ts),
 not a stable public inference contract; attribution is in `packages/ai/DEVIN-NOTICE`.
-Regenerate only this logical model, preserving every other catalog entry, with
+Regenerate only the Devin models, preserving every other catalog entry, with
 `npm --prefix packages/ai run generate-models -- --devin-only`.
 
+### Cursor
+
+Run `/login cursor` (PKCE + polling against `cursor.com`/`api2.cursor.sh`), then
+select a `cursor/*` model. `cursor/default` is the Auto router; sibling slugs
+carry their effort and lane (`-low|medium|high|xhigh|max`, `-thinking-*`,
+`-fast`) in the id, mirroring the CLI's flat list. `CURSOR_API_KEY` accepts an
+already-owned access token instead of the OAuth flow.
+
+```bash
+omk --provider cursor --model default
+```
+
+**Transport and limits.** The Node-only `cursor-agent` adapter runs the
+`agent.v1.AgentService/Run` bidirectional RPC over HTTP/2 at `api2.cursor.sh`
+with Connect-framed protobuf. Each `stream()` call is one `Run`:
+`userMessageAction` for a fresh user turn or `resumeAction` otherwise; history
+is replayed through `conversationState.rootPromptMessagesJson` — SHA256-keyed
+JSON message blobs the server fetches back via the kv channel — and system
+prompts ride `requestContext.rules` in the exec handshake. For OpenAI-family
+sibling slugs the adapter splits the effort into a `reasoning` request
+parameter because the Run endpoint rejects sibling `model_id`s; other ids pass
+through whole. `tokenDelta` frames accumulate output usage; plan-specific
+model availability is enforced server-side (free plans serve Auto only).
+
+Text, thinking, and reported usage enter the normal OMK agent loop; images
+attach through `selectedContext.selectedImages`. Server exec frames that ask
+the client to run tools are answered with the protocol's `throw` failure
+channel — OMK tools are deliberately not advertised inside the provider, so a
+cursor model reports the capability gap instead of bypassing tool governance.
+Wiring exec frames through governed OMK tools is a coding-agent bridge
+feature, not provider scope. Hosted search/fetch permission queries are
+approved; interactive ones are rejected.
+
+The bundled catalog was captured from `GetUsableModels` (2026-09-18; 223
+entries). Regenerate only the Cursor section with
+`npm --prefix packages/ai run generate-models -- --cursor-only`. Protocol
+fields follow the same third-party snapshot attribution as the Devin adapter.
+Live login, plan gating, and quota behavior remain account-dependent; the
+adapter is covered by loopback HTTP/2 protocol tests.
+
 ### OpenAI Codex
 
 - Requires ChatGPT Plus or Pro subscription
@@ -153,6 +210,14 @@ Regenerate only this logical model, preserving every other catalog entry, with
 omk --provider openai-codex --model gpt-5.6-moa --thinking ultra
 ```
 
+### GPT-6 Astra
+
+OpenAI-shaped Astra routes (`openai`, `azure-openai-responses`, `opencode`, `github-copilot`, OpenRouter) expose OMK `ultra` in the selector and send `reasoning.effort: "max"`. Official Astra effort values remain `low`, `medium`, `high`, `xhigh`, and `max`; there is no native `ultra` wire value. ChatGPT/Codex account catalogs may still reject `gpt-6-astra`.
+
+```bash
+omk --provider openai --model gpt-6-astra --thinking ultra
+```
+
 ### Claude Pro/Max
 
 Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party harness usage draws from [extra usage](https://claude.ai/settings/usage) and is billed per token, not against Claude plan limits.
@@ -187,6 +252,7 @@ omk
 | OpenAI | `OPENAI_API_KEY` | `openai` |
 | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek` |
 | Devin CLI session token | `DEVIN_API_KEY` | `devin` |
+| Cursor subscription | `CURSOR_API_KEY` | `cursor` |
 | NVIDIA NIM | `NVIDIA_API_KEY` | `nvidia` |
 | Google Gemini | `GEMINI_API_KEY` | `google` |
 | Mistral | `MISTRAL_API_KEY` | `mistral` |
@@ -205,6 +271,7 @@ omk
 | Fireworks | `FIREWORKS_API_KEY` | `fireworks` |
 | Together AI | `TOGETHER_API_KEY` | `together` |
 | Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
+| WorkBuddy (CodeBuddy) | `WORKBUDDY_API_KEY` | `workbuddy` |
 | 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` |
@@ -216,6 +283,58 @@ omk
 
 Reference for environment variables and `auth.json` keys: [`const envMap`](https://github.com/dmae97/omk/blob/main/packages/ai/src/env-api-keys.ts) in [`packages/ai/src/env-api-keys.ts`](https://github.com/dmae97/omk/blob/main/packages/ai/src/env-api-keys.ts).
 
+#### WorkBuddy (Tencent CodeBuddy)
+
+The cloud inference behind Tencent's CodeBuddy / WorkBuddy agents. Plan keys start
+with `ck_` and are issued by the CodeBuddy login flow:
+
+```bash
+export WORKBUDDY_API_KEY=ck_...
+omk --provider workbuddy --model glm-5.3
+```
+
+Endpoint and limits, verified against the live service on 2026-09-19:
+
+- Chat requests go to `https://www.workbuddy.ai/v2/chat/completions` and must
+  stream; a non-streaming request is rejected. The same key is accepted by
+  `www.codebuddy.ai`, not by the `*.cn` hosts.
+- The first message must be a `system` message. OMK sends the system prompt in
+  that position and prepends an empty one when a session has no system prompt.
+- `max_tokens` carries the output cap; `max_completion_tokens` is ignored
+  upstream.
+- Images are sent as data URIs, which is the only form the endpoint accepts.
+- Thinking levels expose only the effort values the provider declares for that
+  model (`glm-5.3`: low/high/max, `glm-5.2`: high/xhigh, `gpt-5.6-*`:
+  low/medium/high/xhigh, …). The endpoint accepts `reasoning_effort`, but its
+  effect on reasoning volume is not verified, and no `off` value is offered
+  because none was verified. Thinking can therefore not be disabled per request.
+- Model entitlement is per plan: the built-in catalog lists the 27 lanes verified
+  for one account, including eight the CLI's bundled product JSON never declares
+  (`claude-opus-5`, `claude-opus-4.6`, `claude-sonnet-4.6`,
+  `deepseek-v4.1-flash`, `gemini-3.8-flash`, `gpt-6-astra`, `grok-4.6`,
+  `hy4-preview`) which a cross-sweep of this repository's own model ids found.
+  `glm-5.0` answered `429` while its siblings answered `200`, so it is not
+  listed; the CLI's role aliases (`fast-model`, `balanced-model`,
+  `primary-model`, `deep-model`) resolve server-side to targets this catalog
+  cannot declare and are not listed either.
+- Billing is metered in the provider's own credit unit, which OMK reports as
+  zero cost rather than inventing a USD rate. Measured per-call charges on one
+  account (small prompts): `claude-opus-5` 0.26, `claude-opus-4.6` 0.20,
+  `claude-sonnet-4.6` 0.12, `grok-4.6` 0.06–0.08, `gpt-5.6-sol` 0.04,
+  `gemini-3.8-flash` 0.02–0.06, `glm-5.3` 0.01, and 0 credits on `hy3`,
+  `deepseek-v3-0324`, `deepseek-v4.1-flash`, `glm-5.2`, `kimi-k2.5/k2.6` and
+  `minimax-m3`. A charge scales with tokens, so these are magnitudes, not
+  tariffs.
+- Plan allowances (provider documentation, 2026-09-19): Free 100 credits/month,
+  Pro $10/month or $96/year for 2,000 credits/month, plus a limited-time
+  activity bonus of 30 credits/day on Free and 50/day on Pro. Credits are issued
+  monthly, do not carry over, and new accounts get 250 credits valid for 14 days;
+  Pro has a 7-day trial of 500 credits. Check the provider console for the
+  account's own balance: at the measured rates, the Free plan's 100 credits is
+  roughly 380 calls at `claude-opus-5` size, ~830 at `claude-sonnet-4.6`, and
+  1,600-5,000 at `gemini-3.8-flash`, while the 0-credit lanes above did not draw
+  on the allowance at all in these probes.
+
 #### NVIDIA NIM
 
 Set `NVIDIA_API_KEY` and select a currently listed NVIDIA model with `/model`.

package/docs/run-usage-ledger.md

@@ -0,0 +1,56 @@
+# Run usage ledger
+
+Status: implemented as an in-memory accounting module and explicit operation adapter.
+Not automatically connected to AgentSession, provider HTTP retries, MCP, or child CLI.
+Existing `RunBudget` request/concurrency/deadline behavior is unchanged.
+
+Source: `src/core/run-usage-ledger.ts` and `src/core/run-usage-operation.ts`.
+
+## Contract
+
+- `reserve(attemptId, requestId, reservation)` admits an operation only when reported
+  consumption + held reservation + proposed reservation fits each supplied cap.
+  Retry attempts may share a logical request ID. IDs cannot be reused for attempts.
+- `recordTransport(transportId, attemptId)` records a transport start observed by the
+  caller. An application dispatch does not automatically count as an HTTP attempt.
+- `recordUsage(eventId, attemptId, usage)` accepts one cumulative report per attempt.
+  Identical redelivery is idempotent; changed payloads and second reports are rejected.
+  Reports arriving after settlement or closure still bind to the original attempt.
+- `settle(attemptId)` requires observed operation settlement, not a cancellation request.
+  Unknown usage retains its reservation after settlement and blocks new capped admission.
+- `close()` seals admission and transport starts but retains ownership and reservations.
+- Snapshots distinguish the accounted subtotal from `total: null` when usage is missing.
+  `estimatedUsd` is an estimate in USD, never invoice-confirmed spending. Token figures
+  are caller-normalized reports; the ledger cannot detect provider zero-filled missing usage.
+- Counts and amounts reject negative, non-finite and unsafe arithmetic. Maps are bounded
+  by `maxEntries` (default 10,000); there is no automatic eviction of deduplication state.
+
+`runUsageOperation` reserves before invoking the callback and settles in `finally`.
+The adapter captures the admitted attempt ID before invoking the callback, so later
+input mutation cannot redirect settlement. Usage reporters must still supply the correct
+attempt ID themselves. The callback promise must represent the operation lifetime. Do not pass a timeout race
+that returns before the underlying work settles. No AbortSignal is treated as proof
+of termination. Failed operations still count as requests/attempts.
+
+## Verification and limits
+
+From `packages/coding-agent`:
+
+```sh
+node ../../node_modules/vitest/dist/cli.js run test/run-usage-ledger.test.ts test/run-usage-ownership.test.ts test/run-budget.test.ts test/run-budget-scope.test.ts
+```
+
+The local fixture records main work with two transport retries, continuation, summary,
+and child-labelled work: four logical requests, six transports, eight input tokens.
+These are explicit local adapter events, not real provider, process, or billing evidence.
+Tests cover 6 consumed + 3 reserved + 2 proposed against cap 10, delayed settlement,
+late usage, duplicate/conflicting events, missing usage, bounded input/state, and the
+ownership boundary: denied admission never runs the operation, cancellation retains
+the reservation until observed settlement, and settlement attribution survives caller
+input mutation.
+
+No durable replay/restart support, price-table revision binding, invoice corrections,
+work/verification/cleanup partitioning, or automatic whole-run transport instrumentation
+is provided. Actual usage can exceed its reservation: it is recorded honestly and blocks
+later capped admissions rather than being clipped. This is not a hard financial limit.
+R08 end-to-end product integration remains incomplete.