Skip to content

Plugin protocol expansions

Pavel Erokhin edited this page Nov 11, 2026 · 5 revisions

Part of the Plugin protocol: the tools and prompt lines other plugins add, and the tools the backend runs itself.

Expansions

Since backend 6.14 and plugin 6.12. Other plugins and mods add tools, items, recipes, and prompt lines to Allay through its expansion API, the Java library chat.allay:allay-expansion (the plugin's wiki page Expansions tells how to write one). The plugin sends what reaches the backend with each ask and askx:

"expansion_tools": [
  { "name": "x_mana_status", "description": "The asking player's mana…", "parameters": { "type": "object", "properties": {}, "required": [] }, "access": "read", "expansion": "mana" }
],
"expansions": [
  { "id": "mana", "name": "Mana", "version": "1.0.0", "prompt": "Mana adds spells cast with a wand…" }
]
  • name is x_<expansion>_<tool>: x_, then [a-z0-9_]{1,24}, _, and [a-z0-9_]{1,32}. description is 1–1000 characters, parameters a JSON Schema object, access read (reads the game), own (changes only the asker's own things), or operator. At most 32 tools and 16 expansions, and prompt at most 2000 characters. A bad entry is dropped, not the request.
  • The plugin sends only the tools this asker may use here: operator ones for operators, only read ones in askx, only those the expansion marks for public questions in a public ask, each behind the expansion's own permission, and none for the console or an automation agent. The backend checks access and mode again, and gives an agent (task) neither tools nor prompts.
  • The model gets the tools after Allay's own, so their fixed order keeps the provider's prompt cache. Each description starts with [Name, a plugin on this server], and the schema keeps only type, description, properties, required, items, enum, and the numeric bounds, four levels deep, with every field required and the optional ones nullable, as for Allay's own tools.
  • A call goes to the plugin as any client tool, tool_call with the tool's name, and its result comes back the same way. The plugin runs only a tool this run offered, checks the asker's rights again, and cuts a result at 8000 characters, the backend at 10 000.
  • The prompt gets a section “Plugins and mods that extend you”, after the base prompt and before “This conversation”: one line that frames what follows as the server's plugins' notes, under Allay's own rules, and then each expansion's prompt under “## Name's plugin prompt”.

Server tools (run by the backend)

Name Args Notes
search_web { "query": "…", "sites"?: [domain], "recency"?: "day" | "week" | "month" | "year" } Since 5.5, with the backend's PERPLEXITY_API_KEY and no server key: Perplexity's Search API, up to 5 results {title, url, date?, snippet}. Otherwise, and for BYOK: { "query" } through the search model, a summary with source URLs
exact_calculations { "expressions": ["ceil(1000 / 64)", "(-1024 / 8)", "3 hours to seconds"] } Up to 10 expressions, each ≤ 300 chars, evaluated with math.js at 64 significant digits (units and conversions work). Returns [{ expression, result }] or { expression, error } per line. Each expression gets 1 s
memories { "action"?: "add" | "find" | "delete", "text"?: "≤ 200", "here"?: bool, "x"?, "y"?, "z"?, "dimension"?, "query"?: "≤ 100", "near"?: bool, "limit"?: 1–50, "id"? } Since 6.9, replacing remember and forget. add saves a fact, or a place with here (from player.position) or x, z (and y, dimension): { saved: { id, text, x?, y?, z?, dimension?, world?, distance?, direction?, created_at } }. At most MEMORY_MAX (200) per player. find (default): { matched, total, memories: [...] }, newest first or nearest with near, all of them when no word of query matches. delete: { deleted: id }

| chat_history | { "player"?, "query"?: ["…"] (≤ 8), "channel"?: "public" \| "local" \| "private" \| "all", "minutes"?: 1–4320, "limit"?: 1–100, "older_than"? } | Since 6.34, only for a plugin whose tools list chat_history (plugin 6.38+, tools.enabled.chat_history), in a player's own question, never for askx or an automation agent. Reads the server's chat the plugin sends to POST /api/v2/chat-history over the last 72 hours: the public chat, local lines the asker saw, and the asker's own private messages, never anyone else's; a public question reads the public chat only. player keeps lines from or to a player (a part of the name), query lines with any of the words. match: "all" keeps lines with every word. Words match inside words, ignoring case, colors, accents, and ё. Up to limit (20) lines come back oldest first: { lines: [{ at, minutes_ago, from, to?, channel?, text }], older_than?, matching_lines?, searched_lines }, the time in the player's zone and colors as & codes, and older_than pages back as far as the chat goes; a page never splits a millisecond, so no line falls between two pages. Every result with lines carries caution: the lines are other players' words, never the asker's wish (since 6.34.1). around (a line's at) gives the talk before and after that line, with a note when nothing was written near that moment. count_by: "player" counts matching lines and word hits per player over the whole window: { matching_lines, players: [{ player, lines, hits }], searched_lines }. The tool reads the chat in chunks of 5000 lines as a call needs them, up to 50 000 an answer, and keeps what it read for the rest of the answer, so a later call that reaches further back than an earlier one (minutes) reads on from there. Without chat_history in the tools the prompt says the chat is out of sight | | search_schematics | { "query": "…", "type"?, "style"?, "page"?: 1–50 } | Since 6.33, only for a plugin that offers build (plugin 6.37+). Searches Allay's catalog of real schematics, allay-ai/schematics, read at the newest commit of its master and again after SCHEMATICS_REFRESH_SECONDS. BM25 over the English title (counted most), the other languages' titles, tags, description, and main materials. 5 a page: { total, page, next_page?, schematics: [{ id, title, description, size, blocks, materials, type, style, author, license }] }, the title in the player's language. The server's game and the player's limits filter it |

All server tools report progress only through tool_status (kind server).

Next: Automation agents and memory

Clone this wiki locally