Advanced

Rienda is extended in JavaScript, without touching its source and without compiling anything. Two kinds of extension exist:

  • A tool is a capability the model can invoke during a conversation, such as reading a project file or calling an internal API.
  • A hook is your code running at a fixed point of a run, so you can inspect it, gate it, or change what happens.

Start with Tools and continue with Hooks. Both pages share the same runtime and the same ctx object, so everything you learn on the first applies to the second.

Nothing extra to install

The JavaScript engine is embedded in the binary. Rienda runs your scripts with goja, a pure Go implementation of JavaScript, so there is no Node.js, no npm, and no dependency to install: write an index.js file, start a session, and it is there.

That also means the language you write is not the one your editor may assume. The engine implements ECMAScript 5.1 in full, plus some features of ECMAScript 6: the newer revision is still work in progress upstream, so treat ES5.1 as the language you can always rely on. In practice:

  • Everything of ES5 works: var, functions, prototypes, closures, Object utilities, JSON, regular expressions, try/catch, and strict mode.
  • A good part of ES6 works: let and const, arrow functions, classes with extends, template literals, destructuring, default and rest parameters, the spread operator, for...of, Map, Set, Symbol, Promise, generators, getters and setters, and the additions to the standard library such as Object.entries, Object.assign, Array.prototype.includes and String.prototype.padStart.
  • Not everything does. There is no module loader, so import and export do not exist and a script assigns module.exports instead. Async iteration (for await...of) and async generators are unsupported, and the engine does not provide the host globals a browser or Node.js would, such as setTimeout, fetch, URL, Buffer, or console: the ctx object is what replaces them.

When in doubt, write ES5-compatible code, which always runs. The example pages use nothing beyond what the engine supports.

How the runtime behaves

Four rules explain almost everything about writing an extension:

  1. One call, one fresh runtime. Every invocation of a tool or a hook starts with a clean engine, so nothing is remembered between calls. To keep something, write it to a file.
  2. No event loop. The runtime is synchronous: setTimeout, setInterval, process, and require do not exist, and nothing waits for a callback that would fire later. A Promise resolves only after your function has already returned, so a result you need must be produced by the code you return from directly.
  3. No timeout. A tool or a hook runs until it returns or the run is interrupted, so you own the timeouts of anything slow you call.
  4. ctx is the surface. Everything Rienda offers a script, from reading a file to asking the user a question, is a member of the ctx object. The Tools page documents it completely, and hooks receive the same one.

Provider modules

A provider is a directory with an index.js under ~/.rienda/providers. The built ones ship inside the binary; a user module of the same name replaces the built one entirely. Every module exports one synchronous function receiving the same ctx a hook receives and returning the canonical declaration of the provider:

module.exports = function(ctx) {
  var catalogue = JSON.parse(
    ctx.http.fetch("https://models.dev/api.json").body,
  );
  // pick the models of the provider you serve, filter to the adapters
  // Rienda speaks, and return the declaration:
  return {
    name: "My Provider",
    protocol: "openai_chat_completions", // one of openai_responses,
    // openai_chat_completions, anthropic
    base_url: "https://opencode.ai/zen/go/v1",
    session_header: "x-opencode-session",
    headers: {},
    auth: "api_key",
    models: [{ id: "kimi-k2", context_window: 128000, reasoning: false }],
  };
};

name is the display name the interface shows the provider by in the header and the model picker; it is optional and falls back to the directory name, just like a model falls back to its id. The declarations that reach the modules are the roster the picker offers and the connections every run uses; the module owns its catalog, and the caches it writes sit beside its declaration, inside its own directory. Keys travel through rienda auth, which stores them at ~/.rienda/credentials.json.