TokenForge API docs

01 · Quickstart

Two ways in

Play in the browser

Open play.html. No account, no key, no build step — the deterministic Mock LLM ships in the box, so every machine works offline. Add a real API key later in the settings panel if you want live models.

Run headless in Node

The whole engine is plain ES modules with zero dependencies. Clone the repo, save the script below in the repo root, and run it — a small factory is built inline, fed two inputs, and run to completion:

forge-demo.mjs

// forge-demo.mjs — run a TokenForge factory headless. No deps, no build step.
// Usage: node forge-demo.mjs   (run from the tokenforge/ repo root)
import { runBlueprint } from './src/engine/api.js';

// inbox → belt → Prompt Forge (2×2) → delivery, all facing East.
const bp = {
  v: 1, name: 'shout-machine', w: 12, h: 6,
  entities: [
    { t: 'inbox',    x: 1, y: 2, r: 1, c: { name: 'in' } },
    { t: 'belt',     x: 2, y: 2, r: 1 },
    { t: 'llm',      x: 3, y: 2, r: 1, c: { prompt: 'Uppercase this: {{input}}' } },
    { t: 'belt',     x: 5, y: 2, r: 1 },
    { t: 'delivery', x: 6, y: 2, r: 1, c: { name: 'out' } },
  ],
};

const result = await runBlueprint(bp, {
  inputs: { in: ['hello world', 'the factory must grow'] },
  ticks: 300,   // hard cap; stops early once the line settles
  seed: 42,     // deterministic MockLLM + rng
});

console.log(result.outputs.out);   // raw payloads: ['HELLO WORLD', ...]
console.log(result.text.out);      // stringified:  same, JSON for objects
console.log(result.ticks, 'ticks,', result.deliveries.length, 'deliveries');

$ node forge-demo.mjs
[ 'HELLO WORLD', 'THE FACTORY MUST GROW' ]
[ 'HELLO WORLD', 'THE FACTORY MUST GROW' ]
38 ticks, 2 deliveries

No provider was configured, so the Mock LLM handled the Prompt Forge — its uppercase rule matched the prompt. Swap in a real model via the provider config without touching the blueprint.

02 · Headless JS API

src/engine/api.js

One import gives you everything:

import { runBlueprint, createSim, Sim, MockLLM, load, serialize, makePacket, flush }
  from './src/engine/api.js';

runBlueprint(bp, opts) → Promise<result>

Loads a blueprint, feeds queued inputs to inbox buildings, ticks the sim until it settles (or the tick cap), and collects everything that landed in delivery buildings.

The resolved result object:

createSim(bp, {llm, seed, services}) → Sim

When you want to drive the simulation yourself — stepping tick by tick, subscribing to events, feeding inputs mid-run — build a Sim instead:

import { createSim, MockLLM, flush } from './src/engine/api.js';

const sim = createSim(bp, { llm: new MockLLM(), seed: 7 });

sim.on('deliver', ({ name, packet }) => console.log('deliver:', name, packet.payload));
sim.pushInput('in', 'tick by tick');   // queue a payload for inbox name 'in'

for (let i = 0; i < 20; i++) { sim.tick(); await flush(); }
// ...or simply: await sim.run(20)  — ticks and flushes async jobs for you

sim.deliveries        // [{ tick, name, packet, entId }, ...]
sim.outputs('out')    // packets delivered under a given name
sim.events            // rolling log of deliver/log/error events

Sim essentials:

• sim.tick() — one synchronous step: machines tick → output buffers drain (1 packet per port per tick) → belts move. Async work (LLM calls, scripts) runs between ticks; call await flush() after each tick, or use await sim.run(n) which does both.
• sim.pushInput(name, payload) — queue a payload; the next free inbox with that config.name emits it as a packet.
• sim.deliveries — everything delivery buildings received, in order.
• sim.on('deliver', fn) — subscribe to events; also 'log' and 'error'. Handlers get the event data ({name, packet, ent} for deliveries).
• sim.place(type, x, y, rot, config) — add a building programmatically; serialize(sim, name) turns the grid back into blueprint JSON.

MockLLM — the deterministic provider

src/engine/mockllm.js exports a fully offline "language model" that powers the game with no key and makes every test reproducible. It implements the same interface as real providers: await provider.complete(req) → { text, toolCalls?, usage } where req is { system?, prompt?, input?, messages?, tools?, temperature?, maxTokens?, model? }.

How a rule fires: the mock lowercases system + prompt and scans it for instruction keywords; the text it transforms is req.input if set, else the last user message, else the prompt itself. Rules are checked in this exact order — first match wins:

Tool-call heuristic

When req.tools is non-empty, the mock behaves like a one-shot agent and the rules above are skipped:

• First round (no role:'tool' messages yet): it scores every tool by word overlap between the tool's name + description and the task text, and returns { text: '', toolCalls: [{ name, args }] } for the best match. Arguments are filled heuristically from the input: number/integer params get numbers parsed out of the input (in order, 0 when exhausted); every other param gets the full input string.
• After tool results (any role:'tool' messages present): it answers Result: <tool contents joined by '; '> — a plain final answer, no further tool calls.

Scripted mode & call log

For exact tests, queue canned responses — they're consumed in order before any rules run:

const mock = new MockLLM();          // new MockLLM({ latencyMs: 50 }) to simulate latency
mock.script([
  { text: '', toolCalls: [{ name: 'calc', args: { expr: '1+1' } }] },
  { text: 'The answer is 2.' },
]);
// each scripted response is returned as { usage: {in:10, out:10}, ...yourFields }

const result = await runBlueprint(bp, { llm: mock });
mock.calls   // every request object the mock received — assert on prompts, tools, messages

In rules mode, usage is derived from real word counts ({ in: promptWords + 10, out: responseWords }). Once the script queue empties, the mock falls back to rules.

03 · Blueprint format

Blueprint JSON

A blueprint is the serialized factory — what the game saves, what runBlueprint loads, and what you POST to the HTTP API:

{
  "v": 1,                    // format version — must be 1
  "name": "shout-machine",  // display name
  "w": 12, "h": 6,           // grid size (defaults 48×32 when omitted)
  "entities": [
    { "t": "inbox",    "x": 1, "y": 2, "r": 1, "c": { "name": "in" } },
    { "t": "belt",     "x": 2, "y": 2, "r": 1 },
    { "t": "case",     "x": 3, "y": 2, "r": 1, "c": { "mode": "upper" } },
    { "t": "delivery", "x": 4, "y": 2, "r": 1, "c": { "name": "out" } }
  ]
}

Each entity: t = building id (see the reference), x, y = top-left grid tile, r = rotation (defaults to 1/East), c = config overrides merged over the building's defaults. Tiles hold at most one entity; multi-tile buildings (Prompt Forge and Agent Core are 2×2) occupy their whole footprint.

Rotation

r encodes the facing direction: 0=N, 1=E, 2=S, 3=W. Port sides in building definitions are declared for the default facing rot=1 (East) — "W in, E out" reads left-to-right — and the engine rotates them with the entity. Where a declared side ends up:

Belts move packets one tile per tick toward their own r. A belt hands into a machine only if the machine has an in-port on the facing side; machines butt-joined port-to-port skip belts entirely.

04 · HTTP API

Factory as a service

The bundled server serves the game and a JSON API from one process:

node server/serve.js
# → serving on http://localhost:8123  (set PORT to change)

It serves the repo root as static files with correct MIME types (html, js, css, json, svg, png), is path-traversal safe, and mounts the API below. All /api/* routes send Access-Control-Allow-Origin: * and answer OPTIONS preflights, so you can call them from any web page. Errors come back as JSON — the server never crashes on bad input.

Liveness probe: version and building count.

$ curl http://localhost:8123/api/health
{"ok":true,"version":"0.1.0","buildings":43}

The full machine catalog straight from the engine's registered definitions — an array of { id, label, icon, cat, desc, size, ports, configSchema, defaults, unlockTier }. Everything the building reference below shows, as JSON.

$ curl -s http://localhost:8123/api/buildings
[{"id":"belt","label":"Belt","icon":"➡️","cat":"core", ...}, ...]

The manifest of shipped example factories (examples/index.json). Returns [] if no manifest is present.

$ curl http://localhost:8123/api/examples

Run a factory server-side with runBlueprint. The body takes either an inline blueprint or the filename of a shipped example:

On success — 200 with the runBlueprint result (events trimmed to the last 50):

{ "ok": true, "outputs": {...}, "text": {...}, "ticks": 38,
  "deliveries": [{ "tick": 19, "name": "out", "packet": {...} }, ...],
  "events": [ ...last 50... ] }

On an invalid blueprint, unknown example, or malformed JSON — 400 with { "ok": false, "error": "..." }.

Full run with an inline blueprint:

curl -s http://localhost:8123/api/run \
  -X POST -H 'content-type: application/json' \
  -d '{
    "blueprint": {
      "v": 1, "name": "shout-machine", "w": 12, "h": 6,
      "entities": [
        { "t": "inbox",    "x": 1, "y": 2, "r": 1, "c": { "name": "in" } },
        { "t": "belt",     "x": 2, "y": 2, "r": 1 },
        { "t": "llm",      "x": 3, "y": 2, "r": 1, "c": { "prompt": "Uppercase this: {{input}}" } },
        { "t": "belt",     "x": 5, "y": 2, "r": 1 },
        { "t": "delivery", "x": 6, "y": 2, "r": 1, "c": { "name": "out" } }
      ]
    },
    "inputs": { "in": ["hello world"] },
    "ticks": 300,
    "seed": 42
  }'

Run a shipped example with your own inputs:

curl -s http://localhost:8123/api/run \
  -X POST -H 'content-type: application/json' \
  -d '{ "example": "hello-forge.json",
       "inputs": { "in": ["good morning, friend"] },
       "ticks": 400 }'

Run against a real model by adding a provider (see the security notes before doing this anywhere public):

  ...
  "provider": { "kind": "openai", "apiKey": "sk-...", "model": "gpt-4.1-mini" }
  ...

05 · CLI

server/cli.js

Run factories and inspect the catalog from a terminal:

# run a blueprint / example file, print the outputs
node server/cli.js run examples/hello-forge.json --ticks 300

# list every registered building
node server/cli.js buildings

06 · Providers

Bring your own key

src/engine/providers.js exports makeProvider(cfg); every provider implements the same complete(req) interface as MockLLM, tool calls included. Plain fetch, no SDKs:

import { makeProvider } from './src/engine/providers.js';
import { runBlueprint } from './src/engine/api.js';

const llm = makeProvider({
  kind: 'openai',
  baseUrl: 'https://openrouter.ai/api/v1',   // optional; default api.openai.com/v1
  apiKey: process.env.OPENROUTER_API_KEY,
  model: 'moonshotai/kimi-k2-thinking',
});

const result = await runBlueprint(bp, { inputs: { in: ['bonjour'] }, llm });

Where keys live

• In the browser, your key is stored in localStorage and the page calls the provider directly — there is no TokenForge server in the middle, no telemetry, no account. The Anthropic provider sends the anthropic-dangerous-direct-browser-access: true header, which is what Anthropic requires for direct browser calls; the name is a reminder that a key embedded in a page you share is a key you've given away.
• Server-side (POST /api/run), the key travels in the request body's provider field and exists only for that run — the server stores nothing.

07 · Building reference

All 43 buildings

Generated from the engine's registered definitions (src/engine/buildings/). Port sides are declared for facing East (rot=1) — see the rotation table. "Key config" lists each building's default-config keys; full schemas via GET /api/buildings. Tier is the campaign unlock tier (0 = available from level 1).

Core (7)

Text (10)

Flow (9)

Data (9)

LLM (4)

Script (1)

Agent (3)

08 · Agents & tools

Agents are built out of bricks

The Agent Core (agent, 2×2) runs a tool-calling loop on each packet arriving at its task port and emits the final answer from result. What makes it a factory game: its tools are discovered by physical adjacency. When a task arrives, the agent scans every building touching its footprint (sim.grid.neighborsOf(ent)) and collects:

• Any building whose definition has a tool property — in the shipped set that's the Toolbox (tool) and the Memory Shelf (memory), but any building def can opt in.
• Adjacent Agent Cores, exposed as delegable sub-agent tools named agent_<name> with a single task string parameter. Calling one runs that agent's own loop (with its adjacent tools) and returns its final text. Delegation depth is capped at 3.

The tool def contract

A building becomes agent-callable by declaring tool(ent, sim) on its definition, returning:

{
  name: 'shout',                    // tool name the model sees
  description: 'shout the input',  // the model reads this to pick tools
  parameters: { type: 'object', properties: { input: { type: 'string' } } },  // JSON Schema
  run: async (args) => 'result string',
}

The Toolbox fills this contract from its config: name, description, params (JSON Schema, as an object or a JSON string), and code — a sandboxed JS body where args holds the parsed tool arguments and the return value becomes the tool result (1000 ms timeout). The Memory Shelf exposes one tool with op: 'set' | 'get' | 'list' plus key/value; its jar (ent.state.kv) persists across tasks.

The loop, maxSteps, and the trace

Per task the agent builds messages = [{role:'user', content: task}] and repeats, up to config.maxSteps times (default 6, clamped to ≥1):

1. Call api.llm({ system, messages, input, tools }) — tools included only when any were discovered; config.model overrides the session model when set.
2. If the reply has toolCalls, run each one (unknown names and thrown errors become ERROR: ... results), append the assistant turn and one role:'tool' message per call, and loop.
3. Otherwise the reply text is the final answer — emitted from result as a text packet with meta.agent (the agent's name) and meta.steps.

If the step cap is hit without a final answer, the agent falls back to its last assistant text, or [agent] step limit reached. Every step is recorded in ent.state.trace — entries of { step, action: 'call' | 'tool' | 'final', detail }, capped at the last 50 — which the game UI displays live.

Complete example: agent + toolbox

The Agent Core occupies (2,2)–(3,3); the Toolbox at (2,4) touches its bottom edge, so it's discovered automatically — no wiring needed:

const agentBp = { v: 1, name: 'agent-demo', w: 14, h: 8, entities: [
  { t: 'inbox', x: 1, y: 2, r: 1, c: { name: 'task' } },
  { t: 'agent', x: 2, y: 2, r: 1, c: { name: 'helper' } },
  { t: 'tool',  x: 2, y: 4, r: 1, c: {
      name: 'shout', description: 'shout the input text loudly',
      params: { type: 'object', properties: { input: { type: 'string' } } },
      code: 'return String(args.input).toUpperCase() + "!!!"' } },
  { t: 'delivery', x: 4, y: 2, r: 1, c: { name: 'out' } },
]};

const r = await runBlueprint(agentBp, { inputs: { task: ['please shout: hello'] } });
console.log(r.outputs.out);   // [ 'Result: PLEASE SHOUT: HELLO!!!' ]

Under MockLLM, the tool heuristic picks shout by word overlap, then summarizes the tool result — deterministically. Swap in a real provider and the very same factory runs a real tool-calling agent.