feat: add NEAR AI inference provider

[PierreLeGuen]

Relates to

No linked issue.

Risks

Low. This adds a new OpenAI-compatible inference provider plugin and wires it into existing provider discovery/configuration surfaces.

Background

What does this PR do?

Adds @elizaos/plugin-nearai as a first-party NEAR AI Cloud TEE inference provider for text generation. The plugin uses the NEAR AI Cloud OpenAI-compatible endpoint, supports TEXT_SMALL and TEXT_LARGE, and defaults to TEE-verifiable models from the public NEAR AI catalog.

The change also wires NEAR AI into provider auto-enable, onboarding/provider switching, provider status, credential discovery, model catalog discovery, plugin registry metadata, and provider documentation.

What kind of change is this?

Features (non-breaking change which adds functionality)

Documentation changes needed?

Documentation has been updated in the model provider references.

Testing

Where should a reviewer start?

Start with plugins/plugin-nearai, then review the provider wiring in packages/agent/src/runtime/plugin-collector.ts, the onboarding catalog, and packages/docs/model-providers.mdx.

Detailed testing steps

• bun run --cwd plugins/plugin-nearai lint:check
• bun run --cwd plugins/plugin-nearai typecheck
• bun run --cwd plugins/plugin-nearai test
• bun run --cwd plugins/plugin-nearai build
• bun run --cwd packages/agent test -- src/runtime/__tests__/plugin-collector-nearai.test.ts
• bun run --cwd packages/shared typecheck
• bun run --cwd packages/core typecheck
• ./node_modules/.bin/biome check packages/core/src/contracts/onboarding.ts
• ./node_modules/.bin/tsc --noEmit -p packages/core/tsconfig.json

Greptile Summary

This PR introduces @elizaos/plugin-nearai, a new first-party inference provider plugin that connects to NEAR AI Cloud's OpenAI-compatible API with TEE-verifiable model support. It follows the same structure as existing provider plugins and correctly wires NEAR AI into all relevant discovery, onboarding, credential resolution, routing policy, and provider-switching surfaces.

• The plugin core (index.ts, models/text.ts, providers/openai-compatible.ts) wraps the Vercel AI SDK's createOpenAICompatible client and applies a fetch interceptor to strip/rename OpenAI-specific fields (max_completion_tokens, store, reasoning_effort, strict, developer role) that the NEAR AI endpoint does not accept.
• Provider wiring spans ~15 packages: plugin registry, onboarding catalog, auto-enable, credential resolver, vault inventory, routing policy cost table, first-time setup, and model catalog fetch — all consistent with how other providers like zai and moonshot are integrated.

Confidence Score: 5/5

This PR is safe to merge. It adds a self-contained new provider plugin with no changes to existing provider logic.

The plugin implementation is complete and correct: the fetch interceptor properly normalizes NEAR AI-incompatible OpenAI fields, API key gating is consistently enforced across all provider discovery surfaces, and wiring into onboarding, credential resolution, vault, routing policy, and plugin-collector all follow the established patterns of adjacent providers (zai, moonshot). The large refactor in onboarding.ts extracts repeated inline patterns into named helpers without changing behavior. The two findings are configuration completeness gaps that do not affect runtime behavior.

No files require special attention. The two comments on nearai.json and config-routes.ts are config-surface completeness suggestions that do not affect the plugin's runtime operation.

Important Files Changed

Filename	Overview
plugins/plugin-nearai/index.ts	Plugin entry point — registers TEXT_SMALL/TEXT_LARGE handlers, exposes config keys, and delegates init to initializeNearAI. Clean structure, env captured once at module load (standard practice).
plugins/plugin-nearai/models/text.ts	Core text generation logic; fetch interceptor correctly strips OpenAI-specific fields (max_completion_tokens, store, reasoning_effort, strict) and remaps developer→system role for NEAR AI compatibility. Token usage events emitted correctly.
plugins/plugin-nearai/utils/config.ts	Config utilities: getApiKeyOptional, getBaseURL, getSmallModel, getLargeModel, getExperimentalTelemetry. validateConfiguration exported as an opt-in utility but not called from init (documented as deliberate via JSDoc).
packages/agent/src/api/model-provider-helpers.ts	Adds fetchNearAIModels using the /model/list catalog endpoint; NEAR AI is correctly excluded from keylessProviders so catalog fetch is gated behind a valid API key.
packages/app-core/src/registry/entries/plugins/nearai.json	Registry metadata for the plugin UI. Config section covers the 5 user-facing keys but omits NEARAI_EXPERIMENTAL_TELEMETRY, which is defined in package.json agentConfig — users won't see it in the configuration UI.
packages/core/src/contracts/onboarding.ts	Adds nearai to OnboardingProviderId/Family union types and ONBOARDING_PROVIDER_CATALOG. Large refactor of deriveOnboardingCredentialPersistencePlan into focused helper functions — logic is preserved, factoring improves readability.
plugins/plugin-nearai/init.ts	Lightweight init: warns on missing API key in node environments, silently skips in browser (expected for proxy setups). _config parameter intentionally unused — reads from runtime.getSetting() directly.
packages/agent/src/runtime/plugin-collector.ts	Maps NEARAI_API_KEY → @elizaos/plugin-nearai in PROVIDER_PLUGIN_MAP. Single-line addition consistent with all other provider entries.
plugins/plugin-nearai/providers/openai-compatible.ts	Thin wrapper around createOpenAICompatible; injects apiKey only when present (safe for browser builds), delegates fetch to runtime.fetch for TEE/proxy contexts.

Sequence Diagram

sequenceDiagram
    participant Agent as Agent Runtime
    participant Plugin as plugin-nearai
    participant Fetch as NearAIRequestFetch (interceptor)
    participant SDK as Vercel AI SDK (generateText)
    participant API as NEAR AI Cloud API

    Agent->>Plugin: "useModel(TEXT_SMALL | TEXT_LARGE, params)"
    Plugin->>Plugin: resolveTextParams(params)
    Plugin->>Plugin: getSmallModel / getLargeModel (runtime settings)
    Plugin->>Plugin: "createNearAIClient(runtime, {fetch: wrapped})"
    Plugin->>SDK: "generateText({model, prompt, maxTokens, ...})"
    SDK->>Fetch: "fetch(url, {body: OpenAI JSON})"
    Fetch->>Fetch: strip max_completion_tokens to max_tokens
    Fetch->>Fetch: delete store, reasoning_effort, strict
    Fetch->>Fetch: remap role:developer to role:system
    Fetch->>API: POST /v1/chat/completions (cleaned body)
    API-->>Fetch: "{choices, usage}"
    Fetch-->>SDK: response
    SDK-->>Plugin: "{text, usage}"
    Plugin->>Agent: emitEvent(MODEL_USED, tokens)
    Plugin-->>Agent: text string

Loading

_{Reviews (2): Last reviewed commit: "fix: tighten NEAR AI provider initializa..." | Re-trigger Greptile}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4db9524e-f5aa-4bfe-b6e3-1a5ac6bb0eef

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}