Build on Vyre

Writing a Vyre module: the brief

You are writing a module for Vyre. Read this whole page before you write a line. Everything you may use is here, in packages/module-sdk/index.d.ts, and in the complete example at examples/modules/bakery in the Vyre repository.

What a module is#

A module is a folder: module.json, an entry file (index.js) whose default export has start(ctx), and anything else it ships. It talks to the rest of Vyre only through ctx.

The golden rules#

1. Only ctx. Every way out of the module is a ctx member: another module's tool (ctx.call), the network (ctx.fetch), a vendor API with a key (ctx.vault.request), memory, push, spend, the Gate. An added module runs in a sandboxed host where nothing else works.
2. Never import a Vyre file. No ../core/..., no path outside your folder. Import only your own files and safe Node built ins (node:crypto, node:path, node:url, node:fs inside ctx.paths.data).
3. No process, socket or thread of your own. Never import node:child_process, node:net, node:http, node:https, node:dgram, node:worker_threads or node:cluster, with or without the node: prefix.
4. Every tool says who may call it. Each entry under does.tools is an object with name, summary and reach. A tool that acts as the person outside (sends, posts, pays, deletes somewhere else) also says outward.
5. Never ask for presence. No presence on a tool, no Touch ID, no prompt of your own. Use reach: "asked" for anything that changes settings, deletes local data or reshapes an agent. Use outward for anything that acts as the person outside; the Gate handles it.
6. Nothing polls faster than 60 seconds. Listen to events first. A timer you start, you clear in stop().
7. Migrations are forward only. ctx.store.migrate([...]) takes an ordered list. Add a step to change a table; never edit or remove a step that has run. Tables start with your module's name and an underscore.
8. Each ctx door has one declaration. ctx.call needs the tool in needs.tools, ctx.gate.request needs gate.request there, ctx.vault.request a needs.credentials id, ctx.connections.call a needs.connections provider, ctx.fetch a needs.network host, ctx.memory.write its kind in teaches.memory, ctx.ask and ctx.spend a needs.spend cap, and ctx.push.offer its kind in shows.notices. ctx.undo.record needs nothing. A call without its declaration throws an error with code undeclared. The install card is built from these declarations, so declare only what you use.
9. Plain words and the sample world. Summaries are one lowercase line. No em dash, no section sign. Example people and businesses are only alex, Juniper Studio, Northwind Bakery, juno and kit, and example hosts end in .example.

The steps#

1. Make the folder. vyre module new <name> --dir <parent> writes module.json, index.js, <name>.test.js, README.md, AGENTS.md (this brief) and jsconfig.json. It already passes every check. The name is lowercase letters, digits and dashes, 2 to 41 long.
2. Edit module.json. Declare every tool (with reach, and outward where it applies), every event you emit, every event you listen to, every setting, and everything you need.
3. Write the tools in index.js. Each one gets description, a JSON Schema input, at least one entry in examples, and run(input, meta).
4. Write the tests in <name>.test.js with the SDK's harness (testModule), one per tool, plus the refusals: an outward tool held for an agent, an asked tool refused without an ask.
5. Check until clean. Run vyre module check ., then vyre module test . (conformance, then your tests). Fix every line it prints, and run both again. Do not stop at one failure.
6. Add it. vyre module add <folder> shows the person an install card built from your manifest. Their tap turns it on.

Versions: what stays working#

• "vyre": "1" names the module contract you write for. Write "1.2" only when you use something added in contract 1.2; a Vyre that has only 1.0 then says so plainly and never runs your code.
• Inside contract 1, Vyre only adds. Nothing you use is removed, renamed or narrowed, and a default never changes what your module does. A module written for 1.0 keeps working on every 1.x Vyre.
• A key Vyre doesn't know is ignored when it loads, and vyre module check shows it as a warning: a typo, or a key from a newer contract. Warnings never fail a check or a test.
• Check for a newer ctx member with ctx.api.has("<feature>") and work without it when you can. ctx.api.version is the contract this Vyre speaks, like "1.0".
• Something deprecated keeps working, with a warning, for at least two Vyre releases or six months. vyre module upgrade . rewrites what it safely can (for example apiVersion to "vyre", string tool entries to objects, ctx.memory.teach to ctx.memory.write), lists what it left for you, and runs the checks. --dry-run shows the changes and writes nothing.
• When contract 2 arrives, a "vyre": "1" module keeps running beside it for at least 12 months.

module.json cheat sheet#

{
  "$schema": "https://vyre.run/schema/module-1.json",
  "name": "bakery",
  "version": "0.1.0",
  "vyre": "1",
  "description": "Northwind Bakery's orders, the daily target and the flour order.",
  "roles": ["box"],
  "does": {
    "tools": [
      { "name": "bakery.orders", "summary": "list today's orders" },
      { "name": "bakery.target", "summary": "change the daily target", "reach": "asked" },
      { "name": "bakery.flour", "summary": "order flour from the supplier", "outward": "pay" }
    ],
    "commands": [{ "verb": "orders", "tool": "bakery.orders", "summary": "today's orders" }],
    "watchers": ["watchers/big-order.json"]
  },
  "watches": { "emits": ["bakery.order-added"], "on": ["memory.written"] },
  "shows": { "deck": ["now:bakery.today"], "notices": ["target-reached"] },
  "settings": [{ "key": "bakery.target", "label": "Daily target", "type": "int", "default": 40,
                 "levels": ["account"], "apply": "live" }],
  "needs": {
    "credentials": [{ "id": "supplier", "kind": "api-credential", "provider": "flourco", "purpose": "place flour orders" }],
    "network": ["api.flourco.example"],
    "spend": { "dailyUsd": 0.5 }
  },
  "teaches": { "memory": ["note"] }
}

ctx cheat sheet#

Anything in index.d.ts tagged @internal is not for you: ctx.config, ctx.route, ctx.upgrade, ctx.provider, ctx.vault.fetch and the rest.

Worked example: Northwind Bakery#

A tool anyone may call, with examples and a coded refusal:

ctx.tool("bakery.add", {
  description: "Record an order: who it is for and how many items",
  input: { type: "object", required: ["customer", "items"], additionalProperties: false,
    properties: { customer: { type: "string", minLength: 1 }, items: { type: "integer", minimum: 1 } } },
  examples: [{ input: { customer: "Juniper Studio", items: 24 } }],
  run: async ({ customer, items }) => {
    const id = Number(insert.run(today(), customer, items, Date.now()).lastInsertRowid);
    ctx.events.emit("bakery.order-added", { id, items, big: items >= 20 });
    if (items >= 20) await ctx.memory.write({ kind: "note", text: `${customer} ordered ${items} items.`, source_ref: `bakery:order:${id}` });
    return { id };
  },
});

An outward tool. Vyre only runs it after the person's own words asked for it or they approved it. A tap on a button your module drew never runs it: Vyre shows its own Gate card instead. The one supplier write inside the cleared run goes through without a second card:

ctx.tool("bakery.flour", {
  description: "Order flour from the supplier, in kilograms",
  input: { type: "object", required: ["kg"], properties: { kg: { type: "integer", minimum: 1, maximum: 500 } } },
  examples: [{ input: { kg: 25 } }],
  run: async ({ kg }, meta) => {
    const r = await ctx.vault.request("supplier", { method: "POST", url: "https://api.flourco.example/orders", body: { kg } });
    if ("held" in r) return { held: r.held };
    if (r.status >= 400) throw Object.assign(new Error(`the supplier said ${r.status}`), { code: "supplier_refused" });
    return { ordered: true, kg, cleared: meta.gate };
  },
});

The migration, and a stop that leaves nothing running:

ctx.store.migrate([
  "CREATE TABLE bakery_orders (id INTEGER PRIMARY KEY AUTOINCREMENT, day TEXT NOT NULL, customer TEXT NOT NULL, items INTEGER NOT NULL, at INTEGER NOT NULL)",
  "CREATE INDEX bakery_orders_day ON bakery_orders (day)",
]);
const off = ctx.events.on("memory.written", e => ctx.log.debug("memory kept a note", { id: e.id }));
return { async stop() { off(); } };

The test, on the SDK's harness:

import { testModule } from "@vyre/module-sdk/testing";

test("bakery.flour is held for an agent and runs for the person", async t => {
  const h = await testModule(DIR, { vault: { supplier: { status: 201, headers: {}, body: {} } } });
  t.after(() => h.stop());
  assert.deepEqual(await h.call("bakery.flour", { kg: 25 }, { who: "agent" }), { held: "hold-1" });
  assert.equal((await h.call("bakery.flour", { kg: 10 })).data.cleared, "person");
  assert.equal((await h.call("bakery.target", { target: 60 }, { who: "agent" })).error.code, "not_asked");
});

h.call(tool, input, { who, asked }) routes a call as Vyre does: who is person (default), agent, module or hook. h.holds, h.calls, h.events and h.memory record what happened; h.approve(id, content) approves a hold as the person would.

Common refusals and their fixes#

What a module must never do#

• Send data with ctx.fetch. It reads only (GET or HEAD, no body). A URL can carry a secret, such as a webhook URL, so posting to one goes through an outward tool or ctx.vault.request, where the Gate and the vault see it.
• Import a Vyre file, or anything outside its folder.
• Open a process, socket, server or thread of its own.
• Read or write files outside ctx.paths.data, or another module's data.
• Hold, read or print a raw secret. Keys stay in the vault; ctx.vault.request attaches them.
• Act as the person outside without outward on the tool or ctx.gate.request.
• Declare presence, approve at the Gate, call as another caller, or add a prompt of its own.
• Emit a reserved event (sync.*, gate.*, presence.*, vault.*, turn.said).
• Poll faster than every 60 seconds, or keep running work nobody needs.
• Put a customer's or a person's words into an event.
• Use real people's names, emails or hosts in examples, tests or tips.