open-multi-agent-kit 0.99.0 → 1.0.0

package/docs/audit-revalidation-2026-09-17.md

@@ -0,0 +1,77 @@
+# Audit revalidation — 2026-09-17
+
+Baseline: `1e58611d0c28775c8a066b6e913ea6710ccea396`, with unrelated local
+provider/model changes present. This is a scoped local revalidation, not a release
+approval, full security audit, or competitor benchmark.
+
+## Inputs and scope
+
+The local September 14 reproduction ZIP targets
+`69e0637d8fddd26eb40a7ec3f8ebfb65b500de5b`. All 25 entries listed in its
+SHA256SUMS matched. Its recorded six expected failures describe that historical
+snapshot, not the current checkout. The archived runner was not executed or
+substituted for current repository tests.
+
+The September 15 strategy report combines historical findings with proposed
+resource-aware scheduling, recovery, and comparative evaluation. These proposals
+are not measured product benefits. The September 16 GitHub audit targets
+`739bc6f3b6fe1c89bfe058aad7ec17ad252fb10e`; its missing DAG contract is no longer
+present in this baseline. The documents were used to select the checks below;
+not every proposed acceptance criterion was executed.
+
+## Executed regression groups
+
+Commands use `node ../../node_modules/vitest/dist/cli.js --run` from the named
+workspace. No external provider requests were needed.
+
+| Workspace | Test files | Result |
+| --- | --- | --- |
+| agent | `test/tool-dag-*.test.ts` | 83 passed, including 10,000 seeded bounded schedules |
+| coding-agent | `test/mcp/{protocol,protocol-required,manager-lifecycle,manager-health,client,tools}.test.ts` | 61 passed; client tests include a local stdio fixture |
+| protocol | `test/{protocol,evaluation-candidate-binding,validation,run-dag-contract,run-dag-properties}.test.ts` | 44 passed |
+| coding-agent | `test/{context-budget-v2-validation-cache,context-budget-cache,context-budget-cache-policy,context-budget-v2-tier-floor,context-budget-v2-eligibility,context-budget-v2-nonfinite-tokens,context-budget-governor-v2}.test.ts` | 46 passed after the fix below |
+
+These are 234 distinct passing test cases, not 234 independent production tasks.
+An initial command included nonexistent `test/mcp/manager.test.ts`; Vitest ran
+other matching files successfully. Manager coverage above comes from the actual
+`manager-lifecycle`, `manager-health`, and `client` files, not that missing path.
+
+## Fixed: input diagnostics leaked across plan-cache reuse
+
+`planPromptContextBudgetV2()` originally decided cache eligibility before
+`validateBudgetItems()`. Duplicate IDs are dropped and invalid token estimates are
+recomputed. Their sanitized items can produce exactly the same plan key as valid
+input, but their input diagnostics are different.
+
+Three regressions failed before the fix:
+
+1. A cached valid plan hid a duplicate-ID diagnostic on a later call.
+2. A plan produced from duplicate IDs carried its diagnostic into a later valid call.
+3. A cached plan hid the diagnostic for a recomputed non-finite token estimate.
+
+Cache eligibility is now decided after input validation. Calls with input or
+budget diagnostics neither read nor write the plan cache. Representation-cache
+validation and normal valid-input plan reuse remain unchanged. The regression
+uses a required item to isolate plan reuse from the existing
+`cache_dependency_unsafe` rejection for plans containing representation-cache hits.
+
+Changed implementation: `src/core/context-budget-v2-planner.ts`.
+Regression: `test/context-budget-v2-validation-cache.test.ts` (3 passed).
+This preserves diagnostics; it does not redesign duplicate-item handling or tier
+allocation policy.
+
+## Remaining boundaries
+
+- Full `npm run check` has been blocked by unrelated local module-size growth in
+  `agent-session.ts` and `model-registry.ts`; those files and the ratchet baseline
+  are not changed by this fix. A passing focused compiler/test run does not close
+  the full repository gate.
+- General observation evaluation still has existential semantics. Passing
+  candidate-binding tests does not establish latest-result or complete-coverage
+  semantics, or independently authenticate a verifier.
+- ECRAF remains an internal planner. Resource normalization, fairness, live
+  admission integration, and equal-budget performance comparisons were not added.
+- This pass does not validate the complete timeout/ownership fault matrix,
+  verified-run crash recovery, all MCP authorization boundaries, remote CI,
+  branch protection, published artifacts, or router calibration.
+- No release, commit, push, paid benchmark, or new runtime default is implied.

package/docs/devin-harness.md

@@ -1,6 +1,6 @@
 # Devin SWE-2 harness
 
-This page is the canonical operator guide for the built-in `devin` provider and its only logical model, `swe-2`. Use `/login devin` for the Devin CLI subscription PKCE flow or `DEVIN_API_KEY` for an already-owned CLI session token. A user-local `~/.omk/agent/devin.md` may add operator notes, but it is not the portable product contract.
+This page is the canonical operator guide for the built-in `devin` provider, centered on the logical `swe-2` model. Use `/login devin` for the Devin CLI subscription PKCE flow or `DEVIN_API_KEY` for an already-owned CLI session token. A user-local `~/.omk/agent/devin.md` may add operator notes, but it is not the portable product contract.
 
 Authentication, transport, and verification limits are owned by [Providers](providers.md#devin-cli); this page covers how OMK drives SWE-2 as a harness.
 
@@ -44,12 +44,12 @@ Guidance from the [SWE-2 announcement](https://cognition.com/blog/swe-2): `mediu
 
 ## Context budget: 1,000,000 tokens
 
-`devin/swe-2` ships with `contextWindow: 1000000` and `maxTokens: 16384`. These are local budgets that drive OMK's context budgeting and compaction, **not published SWE-2 limits**; Cognition has not published a context window for SWE-2. The budget also selects the catalog lane:
+`devin/swe-2` ships with `contextWindow: 1000000` and `maxTokens: 16384`. These are local budgets that drive OMK's context budgeting and compaction, **not published SWE-2 limits**; Cognition has not published a context window for SWE-2. Chat completion settings follow the captured native Devin CLI 3000.6.2 defaults (`maxNewlines` 400, empty stop list). `topP=0.95` is protobuf field 8; field 6 is `firstTemperature` and is omitted. This removes the old 200-newline cap and synthetic stops, but does not prove that every interrupted reply had that cause. The budget also selects the catalog lane:
 
 1. Before each turn OMK reads `GetCliModelConfigs`. SWE-2 family entries may carry a `1M Context` axis (order `1`) beside the effort axis. A local budget of 1,000,000 or more asks for that 1M-context lane; below it, the standard lane is used and 1M entries are ignored.
 2. A catalog with no 1M-context lane keeps the standard lane for the selected effort.
 3. If the chosen lane declares a context window smaller than the local budget, the request fails with `... declares a N-token context window; lower the models.json contextWindow before retrying`. OMK never shrinks the budget silently, never invents a wire UID, and never downgrades to another effort.
-4. Fast-lane (`Fast Mode`) entries are always excluded. Output is capped against the authenticated catalog's declared maximum.
+4. Fast-lane (`Fast Mode`) entries are excluded from effort routing and are reachable only through their own UID models (ids ending in `-fast` or `-priority`). Output is capped against the authenticated catalog's declared maximum.
 
 To lower the budget (for example if your account only serves the standard lane at 262,144 tokens), override the built-in model in `~/.omk/agent/models.json`:
 
@@ -87,7 +87,7 @@ General prompt-based domain routing is separate and opt-in through `OMK_DOMAIN_R
 
 ## Model selection
 
-The `devin` catalog contains only the logical `swe-2` model; the server's SWE-2 family metadata supplies each effort's wire UID at request time. Use `/model` or `omk --list-models devin` for the current list. Image input is unsupported; provide text.
+The `devin` catalog leads with the logical `swe-2` model; the server's SWE-2 family metadata supplies each effort's wire UID at request time. Every other lane the account catalog advertises is its own logical model whose id is the wire UID — for example `devin/claude-opus-5-high`, `devin/gpt-5-6-sol-xhigh`, `devin/gemini-3-8-flash-medium`, `devin/kimi-k3-max`, `devin/glm-5-3-high`, `devin/grok-4-6-xhigh`, `devin/deepseek-v4-pro-max`, `devin/swe-1-7`, or `devin/inkling-max`. Flat models pin their declared effort lane, so `/think` levels are fixed per model and `No Thinking`/`None` lanes report `reasoning: false`. Availability is account- and plan-dependent: a lane absent from your catalog fails loudly instead of being remapped. Use `/model` or `omk --list-models devin` for the current list. Image input is unsupported; provide text.
 
 ## Skill and MCP matrix summary
 
@@ -116,6 +116,35 @@ Relevant evidence hooks for SWE-2 lanes are `pre-shell-guard`, `protect-secrets`
 4. If a turn fails with an "unavailable or ambiguous" route or a smaller declared context window, treat it as a configuration signal: check `devin models list`, or lower `contextWindow` as shown above. Do not retry with a guessed wire UID.
 5. Keep credentials out of preset JSON, prompts, and logs: the session token, the exchanged user JWT, and `auth.json` contents are secrets under `protect-secrets`.
 
+## Troubleshooting `does not provide an export named`
+
+If Devin fails with `The requested module './devin-connect.js' does not provide an export named 'MAX_FRAME_BYTES'`, the loaded stream module is mixed with an older unary module. That is a client load error, not an orphan tool call or a remote protocol trailer.
+
+- Current OMK keeps the 16 MiB Connect frame cap inside `devin-connect-stream.ts`, so a stale `devin-connect.js` cannot fail that named import.
+- `/new` does not reload already-imported provider modules. Quit and restart OMK after a rebuild.
+- The failure banner should say to restart OMK, not to sanitize a sticky transcript.
+
+## Troubleshooting `invalid_argument`
+
+A Connect `invalid_argument` trailer is a provider/request failure, not evidence of
+an orphan tool call or a safety refusal. Keep any reported trace ID for support;
+OMK includes only a bounded hexadecimal trace ID, never the remote error body.
+
+- The SWE-2 adapter rejects zero, negative, and non-finite `temperature` values
+  before sending credentials. A controlled high-effort probe returned
+  `invalid_argument` at `temperature: 0`, while the default temperature completed
+  the same prompt. Omit the option to use the native default of `1`; OMK does not
+  silently replace an explicit zero.
+- Check model, effort, context budget, and request settings with `/debug`. Repair
+  tool history only when a tool/message mismatch is actually identified.
+- After updating or rebuilding the adapter, quit and restart the OMK process.
+  `/new` replaces conversation state; it does not reload an imported provider
+  module. This is an update-application step, not a guaranteed fix for every
+  provider error.
+- If a minimal tool-free request still fails at the default temperature, preserve
+  the trace ID and investigate provider compatibility or availability rather than
+  repeatedly sanitizing the same transcript.
+
 ## Local overlay
 
 When the `devin` provider is active, OMK appends `~/.omk/agent/devin.md` (capped at 24,000 characters) to the system prompt, mirroring the Grok `grok.md` overlay. Treat that file as optional host configuration for effort defaults, compaction notes, or team conventions; this page and the current provider documentation remain authoritative and it cannot override higher-priority instructions.

package/docs/ecraf-normalization.md

@@ -0,0 +1,83 @@
+# ECRAF dimensionless normalization (R11)
+
+Status: **pure planner, opt-in, not wired** — the same gate vocabulary as
+[runtime-algorithms](./runtime-algorithms.md) applies. This page documents what is
+implemented and verified, and states explicitly what remains unproven.
+
+## Versions
+
+`planEcrafAdmissions()` accepts an explicit `algorithmVersion`:
+
+| Version | Density formula | When selected |
+| --- | --- | --- |
+| `legacy-v1` (default when omitted) | `P_i / (epsilon + Σ_r weight_r · a_ir)` | No normalization options supplied. |
+| `normalized-v2` | `P_i / (epsilon + slotCost + Σ_r weight_r · a_ir / s_r)` | `algorithmVersion: "normalized-v2"` **or** `referenceScales` supplied without a version (compatibility with the earlier scales-only opt-in). |
+
+Compatibility policy:
+
+- Omitting `algorithmVersion` and every normalization option reproduces the
+  byte-for-byte legacy plan. Legacy regression and property tests are unchanged.
+- Supplying `referenceScales` (or `slotCost`) with `legacy-v1` is rejected with
+  `RangeError`; the scales-only shape silently choosing a different algorithm was
+  the ambiguity this version policy closes.
+- Unknown versions and unknown future options are rejected, not coerced.
+
+## normalized-v2 semantics (spec §13.2)
+
+- Every resource with a nonzero demand needs a positive finite reference scale
+  `s_r`. In `normalized-v2` omitted entries default to the resource's **positive
+  total capacity** — never remaining headroom — so the caller cannot implicitly
+  re-scale ranking by scheduling pressure. Unbounded resources (capacity omitted)
+  cannot fall back to a scale and require an explicit one.
+- Zero capacity is a **feasibility gate**, not a scale: a positive demand on a
+  zero-capacity resource is deferred before scoring; a zero demand still uses the
+  resource in the legacy sense (admission fails on held usage), so the documented
+  "missing capacity = unbounded" and `capacity: 0` meanings are preserved.
+- `slotCost` (λ_slot) is finite and **positive**; the slot term charges every
+  running candidate one execution slot even when its resource vector is empty or
+  all-zero, so an empty node cannot dominate on `epsilon` alone.
+- Infinite capacities are rejected in v2 (`RangeError`); the legacy finite-input
+  contract is unchanged. Finite inputs can still overflow the denominator,
+  density, or reserved usage, and those derived values are rejected with
+  `RangeError` as before.
+
+## Verified properties (unit invariance, spec §13.3)
+
+`a'_ir = c_r·a_ir` with `s'_r = c_r·s_r` (`c_r > 0`) produces the identical plan.
+The seeded property test (`tool-dag-ecraf-normalization.test.ts`) replays the same
+batch under independent power-of-two memory/CPU rescaling, both bounded and
+unbounded, with conflicts, held usage, and slot caps, and additionally asserts
+partition completeness, slot bounds, feasibility, conflict invariants, and input
+immutability. The spec's worked example holds: memory scale 4 GiB / CPU scale 8
+gives A = 0.625 < B = 0.75 in both GiB and byte units.
+
+Unit normalization is **not** a fairness guarantee or an optimality proof, and it
+is not equivalent to DRF.
+
+## What this is not
+
+- **No live path calls the planner.** `runDagFrontier()` in
+  `packages/agent/src/agent-loop.ts` admits ready calls by source order and
+  settled-claim conflicts; it does not import `tool-dag-ecraf`. There is no
+  shadow recording, feature flag, or default change, and **no measured benefit**
+  is claimed anywhere.
+- **The conflict predicate covers only this pass.** A live caller must re-check
+  unsettled claims, re-validate post-hook arguments, and refuse stale plans
+  before granting (spec §13.4). None of that wiring exists.
+- Starvation/fairness accounting (spec §13.5) and same-budget comparisons
+  (§13.6 steps 4–6) are separate, unstarted work.
+
+## Tests
+
+- `packages/agent/test/tool-dag-ecraf-normalization.test.ts` — version policy,
+  scale derivation, zero-capacity gating, slot cost, overflow/validation
+  boundaries, unit-invariance property test (seed 110917, 300 runs).
+- `packages/agent/test/tool-dag-ecraf.test.ts` — legacy behavior, input
+  rejection, admission invariants, and the §13.3 GiB/bytes ranking-flip example.
+- `packages/agent/test/tool-dag-ecraf-arithmetic.test.ts` — finite-arithmetic
+  overflow rejection, unchanged.
+
+Mutation/negative-control evidence: removing the demand/scale division, weakening
+slot-cost positivity to `< 0`, removing the zero-capacity gate, or removing the
+version whitelist each makes the assertion harness fail (run from a /tmp mutant
+copy; the working tree was not modified during the check).

package/docs/model-catalog-refresh.md

@@ -3,6 +3,56 @@
 확인일: 2026-09-09. 생성기와 공급자 어댑터를 수정한 뒤 `npm run models:refresh`로
 두 카탈로그를 재생성했다. 생성 파일을 손으로 수정하지 않았다.
 
+## 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 +164,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` |

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.