NexusAI

Feature release: a plugin API for text and JSON generation, events for other plugins, daily token quotas, keyword knowledge selection and Folia support. It also stops printing API keys placed in a provider URL. Everyone on 1.1.2 can update. The new keys are appended to config.yml automatically, and it stays at config-version: 2.

Upgrading

• Replace NexusAI-1.1.2.jar with NexusAI-1.2.0.jar and restart. Commands and placeholders are unchanged. NexusAIApi.API_VERSION is now 3.
• You do not need to edit config.yml, and do not change config-version. On the first start, 18 missing keys are copied from the jar default: plugin-api.*, quotas.* and knowledge.select / knowledge.keywords.*. The log shows Added missing config keys: …, and that start writes one config.yml.bak (or config.yml.bak.<timestamp>). Values you already set and your comments stay.
• The appended defaults keep 1.1.2 behaviour: quotas are off and reject nothing, and knowledge selection stays full.
• providers.<id>.structured-output, model-queue daily-token-limit, and the prompt keys knowledge-select / knowledge-keywords are not inserted. Add them yourself when you want them.
• prompts.yml, pool.yml and usage.yml stay on version 1. token-usage.yml is created by the first counted request.
• To roll back: stop the server, put NexusAI-1.1.2.jar back and start it. 1.1.2 ignores the new keys, so config.yml can stay as it is. To remove the new keys, restore the config.yml.bak written by 1.2.0. token-usage.yml is not read by 1.1.2. Details are in docs/migration-1.2.0.md.

Keys in provider URLs

• Fix: a key in a provider URL is no longer printed. This covers query values such as ?key=… and userinfo such as user:pass@. Affected places: /nai status, the startup base-url: line, /nai test and reload errors, provider warnings, exception messages and FINE request logs. Every query value is shown as ***, userinfo as ***@, and scheme, host, port and path stay readable.
• Secret-looking query values from your configured URLs are also masked wherever they appear, including in provider error bodies that echo the request, events and the last error. This means names such as key, api_key, token, sig, x-goog-api-key, or a name ending in key/token/secret. The userinfo password is masked the same way. Ordinary values such as Azure api-version or a model id are left alone in replies.
• The HTTP request still sends the real query string.
• 1.1.1 and 1.1.2 printed an unmasked ?key= value on the /nai status Base URL line and in the startup log. If you put a key in a provider URL, check old logs and consider rotating that key. api-key or api-key-file remains the recommended place for keys.
• actions.log and moderation.log are now owner-only (0600) on POSIX, including a file that already had a looser mode.

Plugin API

• NexusAIApi.generate returns a GenerationResult with the text, source, provider, model, token counts, finish reason, latency, and a NexusErrorKind when the model did not answer. The future completes on a NexusAI thread. Do not join it on the main thread or a region thread.
• NexusAIApi.generateJson takes a JsonSchema, and a successful result has been checked locally against it. It uses response_format when the provider accepts it. providers.<id>.structured-output may be auto (default), json-schema, json-object or prompt. One invalid reply is retried once on the same row; a second one completes as INVALID_JSON with the fallback text. Only validated JSON is cached.
• NexusAIApi.registerPrompt registers a namespace:id prompt that survives /nai reload and is removed with its plugin. An admin entry with the same id in prompts.yml overrides it.
• New config.yml keys: plugin-api.enabled, plugin-api.max-template-chars and plugin-api.max-var-chars.

Events

• New events for other plugins: NexusPreGenerateEvent, NexusPostGenerateEvent, NexusGenerateFailEvent, NexusProviderErrorEvent, NexusActionEvent and NexusModerationFlagEvent.
• One real model call fires Pre, then any failed HTTP attempts, then exactly one of Post or Fail. A cache hit, an in-flight join and a pooled answer fire none of them.
• Cancelling Pre skips HTTP and reports CANCELLED. Cancelling NexusActionEvent refuses the action without spending its cooldown. The order is documented in docs/api.md.

Token quotas

• With quotas.enabled: true, a request is sent only while each cap that applies is not yet reached. The caps are per server, per player (or the most generous nexusai.quota.<name> group), per API plugin, and per model-queue row (daily-token-limit). Tokens reserved for calls in flight count. One call in flight can finish above a cap.
• /nai usage [players|consumers|history], %ainexus_usage_*% and /nai status show today's tokens. /nai talk shows talk.quota, and the API reports QUOTA_EXCEEDED. A local rejection does not pause a provider.
• With quotas off, nothing new is rejected and the counters still update in token-usage.yml.

Knowledge by keywords

• knowledge.select: keywords (or knowledge-select on a prompt) sends only the paragraphs that match the request instead of whole files. There is no vector search and no embeddings.
• knowledge.keywords.* sets the paragraph and file limits, the minimum matches, on-no-match and the stop words. knowledge-keywords on a prompt adds words to the query.
• /nai test prints which knowledge was attached. full stays the default and keeps the 1.1.2 cache key.

Folia

• Folia is supported on 1.21.8, 1.21.11, 26.1.2 and 26.2, and plugin.yml sets folia-supported: true. This rests on a thread audit and a CI smoke test on each of these versions. Other Folia versions may work and are not tested.
• When the placeholder thread does not own the player, the world name given to a context provider is empty.

Masking and dialogue memory

• More vendor keys are masked even when they are not configured: DeepSeek, OpenRouter, one-case Groq and lowercase Anthropic keys. A CamelCase token such as sk-NexusAIPluginForMinecraft2026 is left as written.
• A failed save or load of a data file or log logs the exception class and a masked message at WARNING. The stack trace goes to FINE. A data folder whose name contains a key does not print that key.
• Fix: stopping the server while dialogue-memory.yml is still loading saves the characters that are only in memory. Stop now splices them into the file within a 5-second budget. The existing bytes stay unchanged, and the file is replaced atomically. If that is not possible in time, the file is left untouched and one warning says how many characters were not saved.

Known issues

• The player-input boundary and the reply filter reduce prompt-injection risk. They do not eliminate it.
• An HTTP 429 on one model pauses its whole provider. Put fallback-model on a different provider so /nai talk can still answer.
• A key under a secret-looking URL parameter that is shorter than 6 characters is still hidden in printed URLs. It is not masked when a provider echoes it in an error body. Use api-key or api-key-file for such keys.
• With a very large dialogue-memory.yml, stop can take up to its 5-second budget.
• Live structured output was checked only with Groq. OpenRouter, OpenAI and Ollama use the same code path but were not checked against the live service.

Compatibility

• Paper and Purpur 1.20.6–26.2; Folia 1.21.8, 1.21.11, 26.1.2 and 26.2 only; Java 21 or newer
• PlaceholderAPI 2.11.6+ (soft-depend); on Folia 2.11.7+
• Tested with PlaceholderAPI 2.12.3 on Paper 1.20.6-151, 1.21.1-133, 1.21.4-232, 1.21.8-60 and 26.2-129/133, on Purpur 1.20.6-2233 and 26.2-2633, and on Folia 1.21.8-6, 1.21.11-14, 26.1.2-8 and 26.2-7 (Java 21 on 1.20.6–1.21.11, Java 25 on 26.1.2 and 26.2).
• Paper and Purpur 26.3, Spigot and CraftBukkit are not supported.

Download

NexusAI-1.2.0.jar, SHA-256 f7add005ffd3eec3716174a6a93ad07f7ff2a7b1f1458285e197e2b40aff10ee

Full history: CHANGELOG.md