feat(providers): add xKiro

[diegosouzapw]

Summary

Rebased on release/v3.8.51 tip 225da11 (2026-09-15) after the Agnes 3.0 Flash catalog (9b4210a) and the Together $25 signup-credit removal (d6e62ae, #12526) landed — merge commits 6e628b8 (57 conflicted files, all count drift, resolved as described under "Operator note") and fd53ba5 (clean, brought #13582 / #13612 / #13736). The diff shown here is xKiro only, measured against the current release tip; #12649 and #12669 remain ancestors.

Adds xKiro (xkiro, https://xkiro.com) as an OpenAI-compatible API-key gateway with a documented free plan: 5M tokens/day per account, no card, across the 40 upstream models tagged access_tier: "free" on the public GET https://api.xkiro.com/v1/models. 39 of them are pinned here (Qwen, MiniMax, DeepSeek, Mistral, SenseNova — 24 with vision, all with tool calling, context 128K–1M); openai/gpt-5.3-codex-spark is deliberately left out (see below). The free-tier catalog gains one new recurring pool, xkiro-free = 5M × 30 = 150M tokens/month, counted once for the whole account, and every visible number that depends on it (headline, entries, pools, hard-stop rows, provider count) is re-synced through the docs gates.

Third PR of the "free-tier honest growth" series (PR1 re-audit of the existing quotas #12649, PR2 gated bucket #12669, PR3 this provider, PR4 radar-server feed). PR1 and PR2 have both landed on release/v3.8.51; this branch is merged up to that tip, so the numbers below are measured against the post-#12669 baseline and every delta is xKiro's own contribution.

What changed

Provider (routable + canonical)

• open-sse/config/providers/registry/xkiro/index.ts (new) — xkiroProvider via buildOpenAiCompatibleRegistryEntry, baseUrl https://api.xkiro.com/v1/chat/completions, 39 pinned models with contextLength / toolCalling / supportsVision taken from the public models endpoint (2026-09-02). Wired in open-sse/config/providers/index.ts (import + REGISTRY.xkiro).
• src/shared/constants/providers/apikey/gateways.ts — canonical xkiro block (serviceKinds: ["llm"], passthroughModels: true, hasFree: true, freeNote, authHint, apiHint). Bearer auth (x-api-key also accepted upstream).
• src/shared/constants/providers.ts — "xkiro" added to AGGREGATOR_PROVIDER_IDS (it fronts other vendors' models).

Free-tier catalog

• open-sse/config/freeModelCatalog.data.ts — 39 rows, all in pool xkiro-free, monthlyTokens: 150_000_000, freeType: "recurring-daily", tos: "caution", hardStopGuaranteed: true; FREE_CATALOG_CURATED_AT → 2026-09-03. Evidence block (verbatim quotes, dated) sits above the rows:
  • https://xkiro.com/ — Free plan card: "$0 / month · Free forever · Free tokens 5M / day · Access to 40+ free models · No credit card"
  • https://docs.xkiro.com/models/tiers/ — "free — any account — Callable on every plan, including the free one, within a daily token allowance" (one allowance per account ⇒ one pool)
  • https://docs.xkiro.com/api/rate-limits/ — "Past it, free-model requests are blocked with a 429 until the daily reset" (⇒ hardStopGuaranteed)
  • GET https://api.xkiro.com/v1/models — the 40 access_tier: "free" rows (public, no key needed)
  • ToS (2026-07-30) forbids reselling/redistributing the service and violating the upstream providers' terms; personal proxy use is not addressed ⇒ tos: "caution".
• openai/gpt-5.3-codex-spark is excluded although it is tagged free upstream: xKiro does not declare where that route is served from (no provenance for an OpenAI-branded model on a third-party gateway), so pinning it would advertise a free model we cannot vouch for. The unit test locks the exclusion in.

Tests

• tests/unit/free-provider-xkiro.test.ts (new, TDD — red 4/4 before the implementation, green after): routable + canonical + aggregator; one 150M pool counted exactly once by computeFreeModelTotals() (with − without = 150,000,000); no codex-spark in registry or catalog; registry ⟷ catalog are the same 39 ids.

Docs and counts (all gate-driven, npm run check:docs-counts + check:docs-sync green)

• docs/reference/PROVIDER_REFERENCE.md regenerated (npm run gen:provider-reference, exact generator output).
• README.md, llm.txt + 65 docs/i18n/*/llm.txt mirrors (66 locales after feat(i18n): 7 new locales — Hausa, Yoruba, Igbo, Amharic, Uzbek, Georgian, Armenian (66 locales) #13727; the duplicate in locale was retired upstream), docs/reference/FREE_TIERS.md (headline, dated note, ToS row, per-provider row, hard-stop sentence, frontmatter date), docs/architecture/{ARCHITECTURE,CODEBASE_DOCUMENTATION,REPOSITORY_MAP}.md, docs/frameworks/OPEN_SSE_ARCHITECTURE.md, docs/diagrams/{readme-hero,promise-pillars,comparison-table,cli-terminal,free-tier-budget}.svg (+ docs/diagrams/README.md), public/images/tier-flow-{dark,light}.svg — provider count, free-tier headline, entries/pools/hard-stop tallies, executor count, visible chips aligned with their own aria-labels (90+ → 150+, 352 → 357, 348 more → 353 more).
• AGENTS.md:49 and package.json description: number only (see operator note).

Numbers before / after

Measured on this branch with the same code the gate uses (computeFreeModelTotals(), the canonical provider collections, REGISTRY); "before" = the release/v3.8.51 tip 225da11 (post-Agnes 3.0, post-Together-credit-removal), which is this PR's base.

Metric	Before (release/v3.8.51 @ 225da11)	After
Canonical providers	358	359 (+1)
Steady recurring free tokens / month	~1.47B	~1.62B (+150M)
First month (steady + one-off credits)	~2.07B	~2.22B (+150M)
Free-tier catalog entries	443 (436 active + 7 discontinued)	482 (+39; 475 active + 7 discontinued)
Recurring pool keys	34	35 (+xkiro-free)
Pools with a published positive monthly budget	16	17 (+xkiro-free), plus Groq's 5 per-model caps
Entries with an independently documented hard stop	5	44 (+39, all sharing one daily allowance)
Recurring / keyless free-forever providers	52	53 (+1)
Providers carrying hasFree: true	152	152
Provider executors (soft count)	111	111 (unchanged — xKiro rides the OpenAI-compatible registry entry, no executor file)

Every delta is exactly xKiro's own contribution — nothing else moved across the merge. Exact live values: steady 1,623,225,000 (= the tip's 1,473,225,000 + xKiro's 150,000,000), first month 2,224,725,000 (the tip's 2,074,725,000 + 150M; #12526 took the Together $25 one-off credit out of the first-month figure, which is why it reads ~2.22B and no longer ~2.25B). #12669's eligibility-gated bucket (gatedRecurringTokens = 6,000,000, ModelScope) is carried through unchanged and stays out of the steady headline.

Why the headline reads ~1.62B and no longer ~1.63B: this PR's contribution is unchanged (+150M). The baseline moved underneath it — PR1's re-audit reclassified gemini and ollama-cloud as uncapped (−80M), re-scoped groq to five per-model caps (+15M), raised nara to a 7M/day bucket (+60M) and reclassified cerebras as a one-time signup credit (−30M). The post-#12669 baseline's ~1.47B + xKiro's 150M = ~1.62B.

All "after" values are the ones npm run check:docs-counts reports as actual on this branch — none were hand-guessed.

⚠️ Operator note

This PR bumps the provider count in AGENTS.md:49 ("358 LLM providers" → 359) and in package.json description — number only, demanded by check:docs-counts (STRICT), same precedent as #12440. AGENTS.md is an agent-instruction surface, so explicit operator approval is needed at merge for that one-line change.

Base sync done (2026-09-15): merge commit 6e628b8 brings origin/release/v3.8.51 @ 58f88a8 (Agnes 3.0 Flash catalog 9b4210a, Together credit removal d6e62ae, 7 new i18n locales #13727, the base-red fixes #13635/#13678), followed by the clean merge fd53ba5 up to the tip 225da11 (#13582, #13612, #13736). 57 files conflicted in the first merge, every one of them count drift (release 358 vs branch 357 vs base 356, and the same shape for the free-tier figures); each number was resolved as release value + xKiro's own delta and then confirmed by the gates:

• open-sse/config/freeModelCatalog.data.ts, open-sse/config/providers/index.ts, src/shared/constants/providers.ts, src/shared/constants/providers/apikey/gateways.ts — auto-merged: the release's Agnes 3.0 rows and the removed Together signup-credit row are kept and all 39 xKiro rows / the xkiro registry + gateway entries stay. Verified as a set: 443 → 482 entries, xkiro-free still one 150M pool.
• README.md, docs/reference/FREE_TIERS.md, docs/getting-started/FREE-TIERS-GUIDE.md — took the release's wording (Together $25 gone from the first-month note, the new STRICT mode sentence on the hard-stop paragraph), kept the xKiro prose (xKiro 150M in the budget-bar list, the "44 hard-stop entries, 39 of them xKiro" sentence), then set every count to what the gate reports live.
• AGENTS.md, package.json, llm.txt + 41 conflicted docs/i18n/*/llm.txt mirrors, docs/reference/PROVIDER_REFERENCE.md (total, API-key section count, generated date) — number only, 358 → 359. The 24 locale mirrors added by feat(i18n): 7 new locales — Hausa, Yoruba, Igbo, Amharic, Uzbek, Georgian, Armenian (66 locales) #13727 after this branch's last sync did not conflict and were given the same two-line bump so check:docs-sync stays exact.
• docs/diagrams/{readme-hero,promise-pillars,comparison-table,cli-terminal,free-tier-budget}.svg, public/images/tier-flow-{dark,light}.svg — number text nodes / aria-labels only (the release's own "20 routing strategies" change in comparison-table.svg is preserved). docs/screenshots/free-tier-budget-card.svg regenerated with scripts/research/gen-budget-card-svg.mjs.
• config/quality/file-size-baseline.json — kept every justification key from both sides (_rebaseline_2026_09_03_12648_xkiro_provider plus the release's 09-11/09-14 entries) and set the gateways.ts cap to the gate's measure of the merged file, 1520 (1519 lines + 1; the release had moved it 1462 → 1502 for Agnes 3.0, xKiro adds its +18).

One extra fix the merge surfaced: tests/unit/check-docs-counts-sync.test.ts asserted the live FREE_TIERS page against a hard-coded 5 hard-stop entries. That number went stale the moment the 39 xKiro rows landed (the doc says 44 and the gate agrees). The test now derives both expected counts from the catalog itself, so it cannot drift again.

Live validation — PENDING (awaiting the owner's free xKiro key; will be completed before marking the PR ready)

Done without a key (2026-09-02), as evidence of the validation endpoint and of the upstream model list the catalog was built from:

$ curl -s -o /dev/null -w "%{http_code}\n" https://api.xkiro.com/v1/usage
401
$ curl -s https://api.xkiro.com/v1/chat/completions -H "Content-Type: application/json" \
    -d '{"model":"qwen/qwen3.6-27b:free","messages":[{"role":"user","content":"Reply with the single word: pong"}],"max_tokens":8}'
{"error":{"message":"Missing ClientApiKey. Send \"Authorization: Bearer <key>\" or the \"x-api-key\" header.","type":"authentication_error","code":"authentication_error"}}   # HTTP 401
$ curl -s https://api.xkiro.com/v1/models | node -e '…'   # public, no key
total 109 · access_tier=free 40 · qwen/qwen3.6-27b:free present · openai/gpt-5.3-codex-spark tagged free (not pinned)

Still to record here once the key is available (Hard Rule #18): the direct upstream smoke with the key, then the through-OmniRoute call POST /v1/chat/completions with {"model":"xkiro/qwen/qwen3.6-27b:free", …} — HTTP status, echoed model, usage, first line of the content. The key itself is never printed or committed.

Validation

Re-run after merging origin/release/v3.8.51 up to 225da11, in the PR worktree at fd53ba5, 2026-09-15:

Check	Result
npm run check:docs-counts	✅ exit 0 — every STRICT claim passes (359 providers, ~1.62B steady / 35 pools / 6M gated, 482 entries, 44 hard-stop, 13 training-disclosure, 53 free-forever, 66 locales, 175 migrations). The only output is 2 soft warnings inherited from the tip (docs/architecture/{ARCHITECTURE,CODEBASE_DOCUMENTATION}.md do not mention the live executor count 111 — identical on origin/release/v3.8.51, not touched here).
npm run check:docs-sync	✅ exit 0 — PASS, 65 llm.txt mirrors match the root
npm run check:fabricated-docs	✅ exit 0
npm run check:file-size	❌ exit 1 — 1 violation, inherited: open-sse/utils/stream.ts 3115 > 3098. The file is byte-identical to the release tip (git diff origin/release/v3.8.51 -- open-sse/utils/stream.ts is empty) and the baseline itself records it as pre-existing tip drift (base-red #12732, owned by /sweep-reds). This PR's own entry, gateways.ts cap 1520, passes.
npm run check:provider-consistency	✅ exit 0 — 359 canonical providers, 277 registry entries, 0 registry-only exceptions
npx prettier --check on the resolved files	✅ exit 0 (the SVGs have no Prettier parser)
focused tests, run in three small batches (free-tier-reaudit-2026-09 + check-docs-counts-sync + free-model-catalog; free-tier-catalog + free-model-catalog-gated-bucket + gen-budget-card-svg + free-catalog-no-confidence-field; free-provider-xkiro)	✅ 88 pass / 0 fail (68 + 16 + 4) at fd53ba5

docs/screenshots/free-tier-budget-card.svg was regenerated with node --import tsx/esm scripts/research/gen-budget-card-svg.mjs --out docs/screenshots/free-tier-budget-card.svg (#12669's generator, which understands hardStopGuaranteed and gated rows); it reports steady=1.62B firstMonth=2.22B gated=6M oneTime=601M (22 pools, 9 first-month chips) and tests/unit/gen-budget-card-svg.test.ts passes its byte-for-byte comparison.

Full unit/vitest/coverage suites and the production build are left to CI on this PR (the devbox times out on them).

No open 🔴 Release branch not green: release/v3.8.51 issue at the time of this sync (2026-09-15); the one inherited red above (stream.ts file-size) is tracked by #12732 and is not touched by this PR.

CI triage (first run on 6155247)

Check	Verdict
API Route Typecheck / open-sse-typecheck — open-sse/executors/glm.ts TS2554 (baseline 0, live 1)	inherited: glm.ts was last changed on the base by #12179; this PR does not touch it (same red on #12649)
Fast Quality Gates — file-size gateways.ts	ours, rebaselined to 1480 after the merge with PR1 (xkiro entry + PR1's nara authHint rewrite + the Prettier reflow of two pre-existing over-long lines; same rationale as the seekai/logfare/freebuff entries); now 1520 after the 2026-09-15 sync absorbed the release's own Agnes 3.0 growth (1462 → 1502) on top of xKiro's +18

[diegosouzapw]

Held, not reviewed — Hard Rule #22b, plus a pending prerequisite.

.claude/worktrees/provider-xkiro is live on feat/provider-xkiro at 99333f34, exactly this PR's head SHA — another session owns it. Separately, this is still a draft and the free-tier plan has it blocked on a live xKiro API key for validation before the ~1.63B claim can be signed off.

Nothing touched. It comes back to the queue when the worktree is gone and the key validation is recorded.