# Keyless automatic fallback coverage and compatibility

Status: implemented and verified. Publication and replacement of the running bot
remain user-owned; the running bot has not been restarted by this work.

## Requested outcome

Make the automatic inference fallback chain function in the production Telegram
and TUI backend. Add only anonymous, keyless providers. Check the whole public
catalog at https://robit-man.github.io/inference/, find additional free providers,
and reuse OpenCode's free-model discovery and routing, including Nemotron where
it is actually available without credentials.

The user requested "never fail." No implementation can guarantee an external
provider's availability. This work must maximize compatible route coverage,
preserve successful replies, and test bounded, honest failure when every remote
route is unavailable; it must not manufacture successful inference or hide a
failed request. This limitation does not reduce the coverage requirement.

## Ordered work and acceptance evidence

1. Inspect the current registry, cascade, production integration and live failure
   evidence. Preserve unrelated worktree changes. Record all catalog families,
   candidate URLs, protocols, anonymous authentication requirements and exclusion
   reasons instead of counting endpoint discovery as working inference.
2. Trace OpenCode's actual free-provider loader, catalog and wire transport from
   primary source. Reuse its zero-cost/keyless selection behavior, not a stale
   handpicked model list. Exclude paid entries, signup/API-key routes, unsupported
   protocols and services that reject anonymous Omnius clients.
3. Probe candidate routes with synthetic public data only. Check text, streaming,
   native tools, tool-result continuation, structured output and advertised input
   capacity. No action emitted by a probe is executed. Record observed support
   and failures separately from catalog hints. Do not send local model requests.
4. Implement the usable adapters and compatibility conditions, shared discovery
   where practical, fair cascade coverage, provider/model cooldowns, cancellation
   and local recovery. Keep whole prompt and required tool/schema contracts;
   preserve manual approval, credential isolation and no replay after visible
   streaming output begins. New automatic routes must require no actual keys.
5. Test deterministic transport failures, quota/auth failures, malformed/empty
   replies, incompatible models, catalog loss, provider retirement, tool/schema
   constraints, all-routes failure, Stop and successful local recovery. Exercise
   production backend plus Telegram/TUI integration rather than only a separate
   raw HTTP harness.
6. Rebuild workspaces, verify packaged runtime, run synthetic live checks on
   admitted providers and save sanitized receipts. Commit and push scoped changes
   after tests pass. Report remaining coverage, failures and activation state
   precisely; do not claim runtime adoption before it occurs.

## Current evidence

Baseline: commit 57e93104. The saved Telegram run at 2026-10-13T01:03:40Z
exhausted Hermes, OVH and LLM7 and consolidated as a timeout without any tools.
The previous cascade allowed six model routes and three models per provider,
with a 20-second request / 60-second remote budget.

The production cascade now starts with OpenCode and Kilo's anonymous routes,
followed by the existing Hermes, LLM7, OVH and ch.at routes. OpenCode discovery
requires explicit zero costs and optionally intersects the gateway's live model
IDs to remove retired entries. Kilo requires explicit zero prompt and completion
prices and excludes non-chat models, including classifiers and music generators.
OVH's documented anonymous tier is pinned independently of its authenticated
catalog prices. Public registry entries cannot grant these provider-specific
exceptions or request identities. No actual keys or new credentialed profiles
are required by the added routes.

Runtime and onboarding share OpenCode's source-derived request adapter. Original
host tool schemas remain authoritative; compatibility-only calls are rejected.
Full prompt and required tool/schema contracts are preserved. The parser accepts
framed SSE and complete JSON responses to streaming requests without replaying a
generation. Local availability failures admit fallback, cancellation and manual
decisions remain binding, and a later request retries local inference. Provider
quota cooldowns apply across models and respect bounded Retry-After values.
Selection allows 16 compatible models per provider, with fair dispatch across
admitted providers. Healthy Hermes continuation took 32 seconds; remote defaults
are therefore 45 seconds per request and 120 seconds overall.

## Verification and limits

Live synthetic checks used the actual production backend and executed no tools:

- [Hermes](evidence/keyless-compatibility-20261012.json) passed text, streaming,
  native tools, tool-result continuation, strict schema and a large native-tool
  packet. ch.at passed text, streaming and the large packet but failed tool and
  schema contracts; it is restricted to text requests without required schemas.
- [OpenCode Nemotron 3.5 Lightning](evidence/opencode-production-compatibility-20261012.json)
  passed all six contracts. Big Pickle passed five but rejected strict schema.
  Retired catalog rows found by these probes are now removed through live-ID
  discovery. Ling quota failures remain recorded, not counted as success.
- [Kilo Nemotron 3 Super, North Mini Code and Dots 3 Note](evidence/kilo-production-compatibility-20261012.json)
  each passed all six contracts. Lyria's authentication failure exposed a
  non-chat metadata ambiguity; music generators are now excluded and covered by
  regression tests. Other catalog models remain unverified.
- [OVH](evidence/ovh-production-compatibility-20261012.json) passed text,
  streaming and native tools before a quota response. A later
  [structured/context check](evidence/ovh-structured-context-compatibility-20261012.json)
  passed both contracts. LLM7 returned a one-hour quota cooldown, which was
  honored rather than repeatedly probed.

All 460 unique source regression tests passed, with one existing skip, across
the orchestrator and CLI suites. An isolated snapshot of the staged code also
passed a full recursive build and all 460 tests (365 orchestrator, 95 CLI),
without depending on unrelated unstaged changes. This includes production private/public
Telegram greeting admission and semantic review without a false incomplete
suffix. The compatibility harness passed 26 tests. The
[freshly installed bundle receipt](evidence/installed-fallback-verification-20261012.json)
records 36 passing mocked transport cases, including automatic/manual fallback,
local recovery, quota handling, more than six failed routes, OpenCode/Kilo,
native tool/schema contracts and cancellation. These installed tests sent no
real inference requests or Telegram messages.

A full clean recursive workspace build, publish bundling, tarball audit
(540 files, zero warnings) and fresh compiler-free npm installation passed.
The required SQLite prebuild loaded. The prepared artifact is
`publish/omnius-1.0.847.tgz`, SHA-256
`5266aa7ca1845bb389f4e7470eb461837516ed99607d09673f11b9ad4fe89309`.
Its installed `dist/index.js` hash matches the packaged receipt. No package was
published and no running bot was replaced.

The durable [provider survey](evidence/keyless-provider-survey-20261012.json)
covers all 12 public-page families and seven additional candidates. Keyed,
non-chat and unverified adapters are classified explicitly; discovery alone
does not enroll a route. Every catalog model has not been live-tested, and
external providers can still exhaust quotas or fail simultaneously. See
[provider findings](../keyless-provider-survey.md) and
[OpenCode source provenance](../opencode-free-model-discovery.md).
