Skip to content

feat(provider): add MiMo Free -- keyless Xiaomi MiMo public tier#129

Merged
lidge-jun merged 7 commits into
lidge-jun:mainfrom
Wibias:codex/mimo-free-provider
Jul 15, 2026
Merged

feat(provider): add MiMo Free -- keyless Xiaomi MiMo public tier#129
lidge-jun merged 7 commits into
lidge-jun:mainfrom
Wibias:codex/mimo-free-provider

Conversation

@Wibias

@Wibias Wibias commented Jul 14, 2026

Copy link
Copy Markdown
Contributor

What

Adds MiMo Free (mimo-free) as a new keyless provider backed by Xiaomi MiMo's free public tier.

How it works

Xiaomi MiMo's free chat endpoint at �pi.xiaomimimo.com/api/free-ai is gated by two anti-abuse mechanisms:

  1. JWT bootstrap: before the first chat request, the adapter POSTs a SHA-256 machine fingerprint (hostname + platform + arch + CPU model + username) to /api/free-ai/bootstrap and receives a short-lived JWT (~50 min). This JWT is cached in-process with a 5-minute early-refresh buffer and reused across all requests until expiry.
  2. System marker injection: the endpoint returns 403 "Illegal access" unless a system message containing the exact string "You are MiMoCode, an interactive CLI tool that helps users with software engineering tasks." is present. The adapter idempotently prepends this marker to every request.

Additional required headers: X-Mimo-Source: mimocode-cli-free, a Chrome-like User-Agent, and x-session-affinity: ses_.

On 401/403, the adapter flushes the JWT cache and retries once with a fresh token.

New files

  • src/adapters/mimo-free.ts: custom ProviderAdapter wrapping the openai-chat base. Exports getMimoJwt,
    esetMimoJwtCache, injectMimoSystemMarker, generateMimoFingerprint for testability.
  • src/server/adapter-resolve.ts: registers the mimo-free adapter name.
  • src/providers/registry.ts: adds the mimo-free registry entry (keyOptional, featured, liveModels, defaultModel: mimo-auto).

GUI: Free badge + optional key field

  • Exposes keyOptional through DerivedProviderPreset and entryToPreset so /api/provider-presets surfaces it to the GUI picker
  • AddProviderModal: green Free badge in picker list, no API key field by default (replaced with a green Free tier banner), collapsible Use your own key instead section for power users

Tests

17 new unit tests in ests/mimo-free-provider.test.ts:

  • Registry shape (adapter, baseUrl, authKind, keyOptional, featured, liveModels, defaultModel)
  • providerConfigSeed() propagation (keyOptional, liveModels)
  • Key-login map and featured list presence
  • System marker: prepend when absent, prepend when system message lacks marker, idempotent when marker present, passthrough for non-object / missing messages
  • Fingerprint: 64-char hex, stable across calls
  • JWT cache: fetch-and-cache (single fetch for two calls), error on 503, reset forces re-fetch
  • Adapter �uildRequest: correct URL (MIMO_CHAT_URL), Authorization with JWT, X-Mimo-Source header, ses_ session affinity, system marker in body
  • GUI preset: deriveProviderPresets exposes keyOptional for picker

All 39 tests pass.

Risk

Medium-low. The JWT bootstrap makes one outbound network call per server lifetime (cached until 5 min before expiry). This call fails gracefully -- a bootstrap error surfaces as a 500 to the requesting client, not a crash. The public tier may be rate-limited, changed, or revoked by Xiaomi MiMo at any time. No existing providers are affected.

Wibias added 7 commits July 14, 2026 20:18
Xiaomi MiMo exposes a free public tier gated by a short-lived JWT that
is bootstrapped from a public endpoint using a machine fingerprint.

Implementation:
- src/adapters/mimo-free.ts: custom ProviderAdapter wrapping openai-chat.
  - getMimoJwt(): bootstraps a JWT from api.xiaomimimo.com/api/free-ai/bootstrap
    using a SHA-256 machine fingerprint; caches in-process with exp-aware TTL
    (5 min early refresh buffer).
  - injectMimoSystemMarker(): idempotently prepends the anti-abuse system
    message required by the upstream gate (returns 403 without it).
  - buildRequest(): async -- fetches JWT, builds body via openai-chat base,
    injects marker, sets required headers (X-Mimo-Source, User-Agent,
    x-session-affinity, Authorization: Bearer JWT).
  - fetchResponse(): retries once on 401/403 with a freshly bootstrapped JWT.
  - resetMimoJwtCache(): exported for testing.
- src/server/adapter-resolve.ts: register the 'mimo-free' adapter name.
- src/providers/registry.ts: add mimo-free entry (keyOptional, featured,
  liveModels, defaultModel: mimo-auto).

Tests (16 unit tests in tests/mimo-free-provider.test.ts):
- Registry shape (adapter, baseUrl, authKind, keyOptional, featured, liveModels)
- providerConfigSeed propagation
- Key-login map and featured list presence
- System marker injection: prepend, idempotent, non-object passthrough
- Fingerprint: hex format and stability
- JWT cache: fetch-and-cache, error propagation, resetMimoJwtCache re-fetch
- Adapter buildRequest: correct URL, Authorization header, system marker

All 36 tests pass (16 new + 20 parity).
@Wibias Wibias marked this pull request as ready for review July 15, 2026 00:19
@lidge-jun lidge-jun merged commit f17510e into lidge-jun:main Jul 15, 2026
6 checks passed
@Wibias Wibias mentioned this pull request Jul 15, 2026
2 tasks
@lidge-jun

Copy link
Copy Markdown
Owner

Merged into dev and released in v2.7.19 — thanks! Since the bootstrap contract mirrors the official MiMoCode client rather than public docs, we stacked privacy/robustness fixes (65d3fdc): the bootstrap client id is now a random UUID persisted under the config dir (no hostname/username-derived fingerprint), retry is 401-only with the first body drained, and bootstrap got timeout/abort propagation + single-flight, all covered by activation-level tests. Provider note now discloses the contract risk.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants