A platform for community discussion. Free, open, simple.
/**
* Tool API Quick Reference
*
* Entry Functions
*
* invoke(parameters): Main function. Receives parameters defined in the tool's signature (Object).
* Must return a JSON-serializable value (e.g., string, number, object, array).
* Example:
* function invoke(parameters) { return { result: "Data processed", input: parameters.query }; }
*
* details(): Optional function. Returns a string (can include basic HTML) describing
* the tool's action after invocation, often using data from the invocation.
* This is displayed in the chat interface.
* Example:
* let lastUrl;
* function invoke(parameters) {
* lastUrl = parameters.url;
* // ... perform action ...
* return { success: true, content: "..." };
* }
* function details() {
* return `Browsed: <a href="${lastUrl}">${lastUrl}</a>`;
* }
*
* customSystemMessage(): Optional function. Called during prompt assembly (not during tool invocation).
* Runs each time a prompt is built, before the LLM sees any messages.
* Returns a string that is appended to the system prompt, or null/undefined to skip.
* Use this to inject persistent instructions into the AI's system prompt based on state
* (e.g., active skills stored via discourse.setCustomField).
* Has access to `context`, `discourse`, and `index` objects.
* Example:
* function customSystemMessage() {
* if (!context || !context.topic_id) return null;
* var skill = discourse.getCustomField("topic", context.topic_id, "active_skill");
* if (!skill) return null;
* var content = index.getFile(skill + ".md");
* return content ? "## Active Skill\n\n" + content : null;
* }
*
* Provided Objects & Functions
*
* 1. http
* Performs HTTP requests. Max 20 requests per execution.
*
* http.get(url, options?): Performs GET request.
* Parameters:
* url (string): The request URL.
* options (Object, optional):
* headers (Object): Request headers (e.g., { "Authorization": "Bearer key" }).
* Returns: { status: number, body: string }
*
* http.post(url, options?): Performs POST request.
* Parameters:
* url (string): The request URL.
* options (Object, optional):
* headers (Object): Request headers.
* body (string | Object): Request body. If an object, it's stringified as JSON.
* Returns: { status: number, body: string }
*
* http.put(url, options?): Performs PUT request (similar to POST).
* http.patch(url, options?): Performs PATCH request (similar to POST).
* http.delete(url, options?): Performs DELETE request (similar to GET/POST).
*
* 2. llm
* Interacts with the Language Model.
*
* llm.truncate(text, length): Truncates text to a specified token length based on the configured LLM's tokenizer.
* Parameters:
* text (string): Text to truncate.
* length (number): Maximum number of tokens.
* Returns: string (truncated text)
*
* llm.generate(prompt, options?): Generates text using the configured LLM associated with the tool runner.
* Parameters:
* prompt (string | Object): The prompt. Can be a simple string or an object
* like { messages: [{ type: "system", content: "..." }, { type: "user", content: "..." }] }.
* options (Object, optional):
* json (boolean): If true, requests JSON output from the LLM and automatically parses it.
* Returns: string | Object (generated text or parsed JSON)
*
* 3. index
* Searches attached RAG (Retrieval-Augmented Generation) documents linked to this tool.
*
* index.search(query, options?): Searches indexed document fragments.
* Parameters:
* query (string): The search query used for semantic search.
* options (Object, optional):
* filenames (Array<string>): Filter search to fragments from specific uploaded filenames.
* limit (number): Maximum number of fragments to return (default: 10, max: 200).
* Returns: Array<{ fragment: string, metadata: string | null }> - Ordered by relevance.
*
* index.getFile(filename): Retrieves the full content of an uploaded RAG file by its exact filename.
* Parameters:
* filename (string): The original filename of the uploaded file (e.g., "my_skill.md").
* Returns: string (all fragments joined in order) or null if file not found.
* Use case: When you need the complete, ordered content of a file rather than semantic search fragments.
*
* 4. upload
* Handles file uploads within Discourse.
*
* upload.create(filename, base_64_content): Uploads a file created by the tool, making it available in Discourse.
* Parameters:
* filename (string): The desired name for the file (basename is used for security).
* base_64_content (string): Base64 encoded content of the file.
* Returns: { id: number, url: string, short_url: string } - Details of the created upload record.
*
* upload.getUrl(shortUrl): Given a short URL, eg upload://12345, returns the full CDN friendly URL of the upload.
*
* upload.getBase64(uploadIdOrShortUrl, maxPixels): Fetches the base64-encoded content of an existing upload.
* Parameters:
* uploadIdOrShortUrl (number | string): Either an upload ID (number) or short URL (string, eg "upload://abc123").
* maxPixels (number, optional): Maximum pixel count for automatic resizing (default: 10,000,000).
* Returns: string (base64-encoded image data) or null if upload not found.
* Use case: Image editing tools can fetch existing uploads to send to external APIs.
*
* Note for Image Editing:
* To implement image editing in a tool:
* 1. Accept an `image_urls` parameter (array of short URLs like ["upload://abc123"]).
* 2. Use upload.getBase64() to fetch the base64 data for each image.
* 3. Send the base64 data to your image editing API (e.g., OpenAI's /v1/images/edits endpoint).
* 4. Create a new upload with the edited image using upload.create().
* 5. Use chain.setCustomRaw() to display the edited image.
* 5. chain
* Controls the execution flow.
*
* chain.setCustomRaw(raw): Sets the final raw content of the bot's post and immediately
* stops the tool execution chain. Useful for tools that directly
* generate the full response content (e.g., image generation tools attaching the image markdown).
* Parameters:
* raw (string): The raw Markdown content for the post.
* Returns: void
*
* 6. secrets
* Accesses credentials bound to this tool by alias.
*
* secrets.get(alias): Returns the credential value bound to `alias`.
* Parameters:
* alias (string): Alias defined in the tool's credential contract.
* Returns: string
* Throws: Error if alias is undeclared, alias is unbound, or credential is missing.
* Example:
* const apiKey = secrets.get("openai_api_key");
*
* 7. discourse
* Interacts with Discourse specific features.
*
* Security model — read before writing tools that are invoked by non-admins:
*
* Tools are authored by admins but can be triggered by any user who mentions
* the agent. The runner intentionally grants admin-level power to the script.
* Know these non-obvious defaults:
*
* - Read ops (`getPost`, `getTopic`, `getUser`, `getAgent`) use the
* SystemUser scope. Results may include PMs, user emails, IP addresses,
* staff-category content, and other staff-only serializer fields. Do not
* return this data verbatim to the invoking user unless you've verified
* they're authorized to see it.
*
* - `search` and `filterTopics` default to public visibility. Pass
* `with_private: true` to elevate them to the SystemUser scope.
*
* - Write ops (`createTopic`, `createPost`, `editPost`, `editTopic`,
* `createChatMessage`) enforce permissions via the Guardian of the user
* named by the `username` parameter — *except* when that user is staged,
* in which case the action runs with SystemUser privileges. This is
* intentional: it supports content-seeding patterns (create a staged
* user, then author content as them in categories they couldn't normally
* write to). The consequence: any staged username is effectively a
* privileged identity. Treat untrusted usernames as privilege-relevant.
*
* - `createStagedUser` itself has no permission check (admin power). A
* tool can spawn a staged user and then write as SystemUser via the rule
* above.
*
* - `updateAgent` can modify any agent on the site, including its
* `system_prompt`. A tool attached to agent A can permanently rewrite
* agent B's instructions.
*
* - `getCustomField` / `setCustomField` have no key allowlist and operate
* on posts, topics, and users. Some custom fields are security-sensitive
* (plugin metadata, tokens, flags). Be deliberate about which keys your
* tool reads or writes.
*
* discourse.baseUrl: The base URL of the Discourse site (e.g., "https://meta.discourse.org").
*
* discourse.search(params): Performs a Discourse search.
* Parameters:
* params (Object): Search parameters (e.g., { search_query: "keyword", with_private: true, max_results: 10 }).
* By default this searches public content. `with_private: true` searches across all posts visible to the
* SystemUser. `result_style: 'detailed'` is used by default.
* Returns: Object (Discourse search results structure, includes posts, topics, users etc.)
*
* discourse.filterTopics(params): Filters topics using Discourse topic filter syntax.
* Parameters:
* params (Object): { q: string, limit?: number, page?: number, with_private?: boolean }
* `q` uses Discourse topic filter syntax (for example: "category:support order:created").
* By default this only returns topics visible publicly. Pass `with_private: true` to elevate to the
* SystemUser scope.
* Returns: Object { query, page, limit, topics }
* query (string): The filter query that was executed.
* page (number): The page number used.
* limit (number): The effective per-page limit used.
* topics (Array<Object>): Topic summaries — same shape as `getTopic` (ListableTopicSerializer plus
* `url`, `tags`, `first_post_id`, `category_id`, `category_name`,
* `category_slug`, `views`, `like_count`).
*
* discourse.getPost(post_id): Retrieves details for a specific post.
* Parameters:
* post_id (number): The ID of the post.
* Returns: Object (Post details including `raw`, nested `topic` object with ListableTopicSerializer structure) or null if not found/accessible.
*
* discourse.getTopic(topic_id): Retrieves details for a specific topic.
* Parameters:
* topic_id (number): The ID of the topic.
* Returns: Object (Topic details using ListableTopicSerializer structure, plus `url`, `tags`,
* `first_post_id`, `category_id`, `category_name`, `category_slug`, `views`, `like_count`)
* or null if not found/accessible.
*
* discourse.getUser(user_id_or_username): Retrieves details for a specific user.
* Parameters:
* user_id_or_username (number | string): The ID or username of the user.
* Returns: Object (User details using UserSerializer structure) or null if not found.
*
* discourse.getAgent(name): Gets an object representing another AI Agent configured on the site.
* Parameters:
* name (string): The name of the target agent.
* Returns: Object { respondTo: function(params) } or null if agent not found.
* respondTo(params): Instructs the target agent to generate a response within the current context (e.g., replying to the same post or chat message).
* Parameters:
* params (Object, optional): { instructions: string, whisper: boolean }
* Returns: { success: boolean, post_id?: number, post_number?: number, message_id?: number } or { error: string }
*
* discourse.createChatMessage(params): Creates a new message in a Discourse Chat channel.
* Parameters:
* params (Object): { channel_name: string, username: string, message: string }
* `channel_name` can be the channel name or slug.
* `username` specifies the user who should appear as the sender. The user must exist.
* The sending user must have permission to post in the channel.
* Returns: { success: boolean, message_id?: number, message?: string, created_at?: string } or { error: string }
*
* discourse.editTopic(topic_id, updates, options?): Edits topic properties (tags, category, visibility).
* Parameters:
* topic_id (number): The ID of the topic.
* updates (Object): Properties to update (all optional):
* tags (Array<string>): Tags to apply to the topic.
* category (number | string): Category ID, name, or slug.
* visible (boolean): true to list, false to unlist.
* options (Object, optional):
* username (string): The username of the user performing the action.
* silent (boolean): Skip notifications for category changes (default: false).
* append (boolean): Append tags instead of replacing (default: false).
* Returns: { success: boolean, topic: { id, category_id, category_name, category_slug, tags, visible, visibility_reason_id } }
* Throws: Error if topic not found, permission denied, or operation fails.
* Note: `discourse.setTags(topic_id, tags, options)` is available as a backwards-compatible alias.
*
* discourse.editPost(post_id, raw, options?): Edits a post's content.
* Parameters:
* post_id (number): The ID of the post.
* raw (string): The new raw Markdown content.
* options (Object, optional):
* edit_reason (string): Reason for the edit.
* username (string): The username of the user performing the action.
* Returns: { success: boolean, post_id: number }
*
* discourse.getCustomField(type, id, key): Reads a custom field value from a post, topic, or user.
* Parameters:
* type (string): The model type - "post", "topic", or "user".
* id (number): The ID of the post, topic, or user.
* key (string): The custom field key to read.
* Returns: string | null (the custom field value, or null if not set)
* Use case: Check if a post has already been processed by the tool.
* Example:
* const processed = discourse.getCustomField("post", context.post_id, "ai_processed");
* if (processed) return { skipped: true };
*
* discourse.setCustomField(type, id, key, value): Sets a custom field value on a post, topic, or user.
* Parameters:
* type (string): The model type - "post", "topic", or "user".
* id (number): The ID of the post, topic, or user.
* key (string): The custom field key (max 256 characters).
* value (string): The value to set (max 1024 characters).
* Returns: { success: boolean, key: string, value: string }
* Throws: Error if type is invalid, key/value too long, or model not found.
* Use case: Mark a post as processed to prevent duplicate processing.
* Example:
* discourse.setCustomField("post", context.post_id, "ai_processed", Date.now().toString());
*
* 8. context
* An object containing information about the environment where the tool is being run.
* Tools can be invoked from multiple contexts - understanding where your tool is running
* helps you access the right data and take appropriate actions.
*
* Invocation Contexts:
*
* A) AI Bot Conversation (Post context):
* When a user mentions an AI agent in a topic or PM, tools run with:
* context.post_id (number): The post that triggered the agent.
* context.topic_id (number): The topic containing the post.
* context.private_message (boolean): Whether this is a PM.
* context.participants (string): Comma-separated usernames (in PMs).
* context.username (string): The user who triggered the tool.
* context.user_id (number): The user's ID.
*
* B) Chat Context:
* When a user mentions an AI agent in a chat channel:
* context.message_id (number): The chat message that triggered the tool.
* context.channel_id (number): The chat channel ID.
* context.username (string): The user who sent the message.
*
* C) Automation Context (ai_tool_action):
* When a tool runs via Discourse Automation (e.g., on post_created_edited trigger):
* context.post_id (number): The post that triggered the automation.
* context.topic_id (number): The topic containing the post.
* context.username (string): The post author's username.
* context.user_id (number): The post author's ID.
* context.feature_name (string): "ai_tool_action" - identifies automation context.
* context.feature_context (Object): { automation_id, automation_name } - the automation details.
*
* Common Properties (available in most contexts):
* context.site_url (string): The base URL of the Discourse site.
* context.site_title (string): The site's title.
* context.site_description (string): The site's description.
*
* Accessing Full Data:
* The context provides IDs - use the discourse API to fetch full objects:
* const post = discourse.getPost(context.post_id); // Full post with raw content
* const topic = discourse.getTopic(context.topic_id); // Full topic with tags, category
* const user = discourse.getUser(context.username); // Full user profile
*
* Example - Automation Tool Pattern:
* function invoke(params) {
* // Skip if not first post or already processed
* const post = discourse.getPost(context.post_id);
* if (post.post_number !== 1) return { skipped: "not first post" };
*
* const processed = discourse.getCustomField("post", context.post_id, "ai_processed");
* if (processed) return { skipped: "already processed" };
*
* // Do work (e.g., auto-tag, summarize, moderate)
* const topic = discourse.getTopic(context.topic_id);
* // ... your logic here ...
*
* // Mark as processed to prevent re-running
* discourse.setCustomField("post", context.post_id, "ai_processed", Date.now().toString());
* return { success: true };
* }
*
* 9. crypto
* Provides cryptographic hashing, HMAC, signing, and encoding utilities.
* These bridge to Ruby's OpenSSL — not the Web Crypto API.
* All functions are synchronous. Inputs accept strings or Uint8Array (binary
* values are sent across the bridge as raw bytes). Functions suffixed with
* `Bytes` return Uint8Array, which is preferable when chaining crypto ops.
* Input size is limited to 10MB per call.
*
* HMAC Functions:
*
* crypto.hmacSha256(key, data): HMAC-SHA256, hex output.
* crypto.hmacSha1(key, data): HMAC-SHA1, hex output.
* crypto.hmacSha256Base64(key, data): HMAC-SHA256, base64 output.
* crypto.hmacSha1Base64(key, data): HMAC-SHA1, base64 output.
* crypto.hmacSha256Bytes(key, data): HMAC-SHA256, Uint8Array output.
* crypto.hmacSha1Bytes(key, data): HMAC-SHA1, Uint8Array output.
*
* Hash Functions:
*
* crypto.sha256(data), crypto.sha1(data), crypto.md5(data): hex output.
* crypto.sha256Base64(data), crypto.sha1Base64(data), crypto.md5Base64(data): base64 output.
* crypto.sha256Bytes(data), crypto.sha1Bytes(data): Uint8Array output.
*
* RSA Signing (PKCS1v15):
*
* crypto.signRsaSha256(pemPrivateKey, data): RSA-SHA256 signature.
* crypto.signRsaSha1(pemPrivateKey, data): RSA-SHA1 signature.
* Parameters:
* pemPrivateKey (string): PEM-encoded RSA private key (PKCS8 or PKCS1).
* data (string | Uint8Array): The data to sign.
* Returns: Uint8Array (raw signature bytes — for RS256 on 2048-bit keys, 256 bytes)
* Throws: Error if the key is not a valid RSA private key.
*
* Encoding Utilities:
*
* crypto.base64Encode(text): Base64-encode (equivalent to btoa, absent in V8).
* crypto.base64Decode(base64): Decode standard base64. Returns string.
* crypto.base64UrlEncode(text): URL-safe base64 encode, no padding (JWT-style).
* crypto.base64UrlDecode(base64): URL-safe base64 decode. Returns Uint8Array
* (accepts input with or without padding).
*
* Random:
*
* crypto.randomBytes(length): Cryptographically secure random bytes.
* Parameters:
* length (number): Number of bytes, 1–1024.
* Returns: Uint8Array
*
* Example - Webhook signature verification:
* function invoke(params) {
* const secret = secrets.get("webhook_secret");
* const signature = crypto.hmacSha256(secret, params.payload);
* return { valid: signature === params.expected_signature };
* }
*
* Example - Signing a JWT (RS256) for a Google service account:
* function signJwt(privateKeyPem, claims) {
* const header = crypto.base64UrlEncode(JSON.stringify({ alg: "RS256", typ: "JWT" }));
* const payload = crypto.base64UrlEncode(JSON.stringify(claims));
* const signingInput = header + "." + payload;
* const sig = crypto.signRsaSha256(privateKeyPem, signingInput);
* return signingInput + "." + crypto.base64UrlEncode(sig);
* }
*
* Constraints
*
* Execution Time: ≤ 2000ms (default timeout in milliseconds) - This timer *pauses* during external HTTP requests or LLM calls initiated via `http.*` or `llm.generate`, but applies to the script's own processing time.
* Memory: ≤ 10MB (V8 heap limit)
* Stack Depth: ≤ 20 (Marshal stack depth limit for Ruby interop)
* HTTP Requests: ≤ 20 per execution
* Exceeding limits will result in errors or termination (e.g., timeout error, out-of-memory error, TooManyRequestsError).
*
* Security
*
* Sandboxed Environment: The script runs in a restricted V8 JavaScript environment (via MiniRacer).
* No direct access to browser or environment, browser globals (like `window` or `document`), or the host system's file system.
* Network requests are proxied through the Discourse backend, not made directly from the sandbox.
*/