Atom Reference

An atom is one operation the AJS VM can perform: a loop, a variable write, an HTTP request, a model call. A compiled agent is a tree of atom steps, and every step is charged fuel, checked against the atom's declared inputs, and run under the atom's timeout.

This page lists every atom the VM registers: 54 core atoms, plus 6 battery atoms when the host passes batteryAtoms. A host can list what its own VM has:

import { AgentVM, batteryAtoms } from 'tjs-lang/vm-ast'

Object.keys(new AgentVM().atoms).length // 54
Object.keys(new AgentVM(batteryAtoms).atoms).length // 60

AgentVM and batteryAtoms come from tjs-lang/vm-ast, the VM without a parser (they are also exported by tjs-lang/vm and tjs-lang). The transpiler is transpile from tjs-lang/lang, the model-server connection is getBatteries from tjs-lang/batteries, and the fluent builder Agent comes from the main tjs-lang entry.

Hosts can add atoms of their own; Capabilities and Custom Atoms covers that. How to give a run its budgets and capabilities is in Hosting the VM.

Terms used on this page

• Fuel is the run's work budget. Every step costs some, and the run stops when it runs out. A run gets 1000 unless the host sets fuel. For scale: a variable write costs 0.1, a callback method such as map 1 plus its steps, a store call 5, a model call 100. Time is limited separately: a run's overall timeout is twice the slowest registered atom's (240 s with the core atoms, because llmPredict allows 120 s) unless the host sets timeoutMs.
• A capability is an object the host passes in vm.run(ast, args, { capabilities }), such as fetch, store or llm. The VM has no IO of its own; an atom that reaches outside calls one.
• The membrane is the boundary between capabilities and the agent. A value crossing it, either way, is a checked copy of plain JSON data (plus Date), never the host's object.
• A run option is a field of that third vm.run argument: fuel, capabilities, costOverrides, timeoutOverrides, quotas (a cap on how many times an op may run, as in quotas: { llmPredict: 3 }), and context, which carries the host's policy lists such as allowedFetchDomains. Hosting the VM lists them all.
• An AST is the JSON tree the transpiler produces and the VM runs. The transpiler writes format version 2. The fluent builder (Agent.take()…toJSON(), from the main tjs-lang entry) and older stored ASTs use version 1; a few atoms exist only for those.
• A guest schema is a JSON Schema an agent builds with Schema, limited to the keywords the VM accepts (see Schema in The AJS Language).

Find an atom

Alphabetically, with the section each is in: agentRun (Code and agents), cache (Utilities), callLocal (Flow control), clearExpiredProcedures (Stored procedures), consoleError, consoleLog, consoleWarn (Console), constSet (State), Error, evaluate (Flow control), filter, find (Arrays and objects), hash (Utilities), httpFetch (Network), if (Flow control), join (Arrays and objects), jsonParse, jsonStringify (Text, JSON and XML), keys, len (Arrays and objects), llmPredict (AI: llmPredict), llmPredictBattery, llmVision (AI: battery atoms), map (Arrays and objects), memoize (Utilities), merge, omit, pick, push (Arrays and objects), random (Utilities), reduce (Arrays and objects), regexMatch (Text, JSON and XML), releaseProcedure (Stored procedures), return (Flow control), runCode (Code and agents), scope, seq (Flow control), split (Arrays and objects), storeCreateCollection (AI: battery atoms), storeGet (Store), storeProcedure (Stored procedures), storeQuery, storeQueryWhere (Store), storeSearch (AI: battery atoms), storeSet (Store), storeVectorAdd, storeVectorize (AI: battery atoms), storeVectorSearch (Store), template (Text, JSON and XML), transpileCode (Code and agents), try (Flow control), uuid (Utilities), varAssign, varGet, varSet, varsExport, varsImport, varsLet (State), while (Flow control), xmlParse (Text, JSON and XML).

Calling an atom from AJS

An atom takes one object of named inputs, or nothing:

function stamp({ name = 'Ada' }) {
  let id = uuid()
  let digest = hash({ value: name })
  let n = random({ min: 1, max: 7, format: 'integer' })
  return { id, digest, n }
}

Returns a fresh UUID, the SHA-256 hex digest of 'Ada', and an integer from 1 to 6 (max is exclusive; see Utilities).

The entry function's parameters are the run's arguments. A default such as name = 'Ada' applies when the caller leaves that argument out; vm.run(ast, { name: 'Bo' }) uses 'Bo'.

These rules apply to every call:

• Inputs are named and checked when the source is transpiled. A positional call such as storeGet('k') (refused) fails with 'storeGet' takes named arguments: write storeGet({ name: value, … }), not storeGet(a, b). An input the atom does not declare, as in storeGet({ k: 1 }), fails with 'storeGet' has no input 'k'. It takes storeGet({ key }). A spread or a missing required input is refused the same way.
• An atom call is a statement, and so is a callback method. Write let x = atom({ … }), x = atom({ … }), or a bare atom({ … }), and bind let ys = xs.filter((x) => …) before using ys. Both mistakes are refused when the agent is transpiled: a callback method inside a larger expression (xs.filter(…).length), and an atom call inside one (return { id: uuid() }, if (regexMatch({ … }))), which says Atom 'uuid' cannot be called inside an expression.
• There is no await. Every atom call is awaited for you.
• console.log, console.warn and console.error do nothing. They are accepted and record nothing, and console.error does not stop the run. Use the consoleLog, consoleWarn and consoleError atoms (see Console), or put what the caller needs in the object you return.

Two names look like atoms but follow other rules. Error('message') is an atom called positionally: the transpiler puts the message in its args input. filter(data, shape) with two arguments is a builtin, not the filter atom (see Arrays and objects). Your own helper functions and the other builtins (Math.max(a, b), JSON.parse(s)) take positional arguments as usual.

How to read the tables

Most atoms that run other steps (seq, if, while, try, map, …) have no timeout of their own. Four keep the 1 s default: agentRun, runCode, memoize and cache. That limit is on time spent waiting, such as a sub-agent's slow fetch; computation inside a sub-agent is bounded by fuel, not by this timeout. See Code and agents.

The ajs examples on this page run in the doc site as they stand. An example that needs a capability the site does not have (a model, a custom store, a host) is fenced as plain JavaScript, and its first line says which side it runs on: // In the agent or // On the host.

Flow control

You write these as ordinary JavaScript. while also charges 0.1 fuel per iteration, so while (true) runs out of fuel instead of hanging.

callLocal declares no output, but a helper's return value still reaches the caller: let y = double(x) binds what double returns, as in JavaScript. evaluate runs an expression for its effect and discards the value; a statement such as xs.push(2) compiles to it.

AJS has no throw. Error('message') is how an agent fails on purpose: it sets the run's error, and the steps after it are skipped until a catch takes it. Inside the catch block the parameter (e below) is the error's message as a string, not an Error object, so there is no e.message. The variable errorOp is bound in the same block, and only there, to the name of the atom that failed:

function safeDivide({ a = 10, b = 0 }) {
  try {
    if (b == 0) {
      Error('division by zero')
    }
    return { value: a / b }
  } catch (e) {
    return { failed: e, at: errorOp }
  }
}

Returns { failed: 'division by zero', at: 'Error' }. Which failures can be caught and which end the run is covered in The AJS Language.

State

varSet declares a variable in the current scope. varAssign writes the scope that already owns the name, which is how total = total + x inside a loop body updates the outer total. constSet declares a binding that cannot be reassigned. varsImport copies the run's arguments into scope; the transpiler emits it from the entry function's parameters.

varGet, varsLet and varsExport exist for builder ASTs. In AJS source a variable is read by naming it.

Arrays and objects

The callback atoms (map, filter, reduce, find) are what the transpiler emits for the array methods that take an arrow function, and map is also what a for...of loop compiles to. Each charges 1 fuel, plus whatever its steps cost for every item:

function totals({ prices = [12, 5, 30] }) {
  let big = prices.filter((p) => p > 10)
  let doubled = prices.map((p) => p * 2)
  let sum = prices.reduce((acc, p) => acc + p, 0)
  let first = prices.find((p) => p > 20)
  return { big, doubled, sum, first }
}

Returns { big: [12, 30], doubled: [24, 10, 60], sum: 47, first: 30 }. A callback method must be bound to a variable, as above; xs.filter(…).length or return { big: xs.filter(…) } is a transpile error. The message does not say so: it reads Unsupported expression type in condition: ArrowFunctionExpression.

The v1 data atoms (push to keys) date from version 1 ASTs and the fluent builder. New code should not call them. In AJS source, use the method or builtin instead: xs.push(x), xs.length, s.split(','), xs.join('-'), Object.keys(o), { ...a, ...b } or Object.assign({}, a, b) for merge, and an object literal ({ name: o.name }) for pick. The method is what the transpiler emits for those, has JavaScript's semantics, and goes through the same budget checks. The atoms differ in small ways: push returns the array where xs.push(x) returns the new length. They remain callable by name, and a host's costOverrides or quotas entry keyed on split or push applies only to those atom calls, not to the methods.

filter(data, shape) with two arguments is something else: a builtin that returns a copy of data holding only the fields shape declares, and fails if the data does not match. shape is a schema, or an example value such as { name: '', age: 0 } whose field values give the types (a string and a number here). filter({ name: 'Ann', age: 3, secret: 'x' }, { name: '', age: 0 }) is { name: 'Ann', age: 3 }. Use it to strip what a capability returned down to what you mean to keep.

Text, JSON and XML

template fills {{name}} placeholders from vars, reading only vars' own keys. In AJS source a template literal does the same job and is what you should write; it compiles to string concatenation. template is useful when the template text itself is data, such as a prompt stored by the host:

function greet({ name = 'Ann', tmpl = 'Hi {{name}}, welcome back, {{name}}!' }) {
  let fromData = template({ tmpl, vars: { name } })
  let literal = `Hi ${name}`
  return { fromData, literal }
}

Returns { fromData: 'Hi Ann, welcome back, Ann!', literal: 'Hi Ann' }.

regexMatch returns true if value contains a match for pattern, a string or a regex literal. It runs on the VM's own linear-time regex engine, so no pattern can hang a run; the price is that backreferences (\1) and lookaround ((?=…), (?<=…)) are refused with an error. The string methods (replace, split, match, search) take the same patterns; use them when you need the matched text, and regexMatch when you need a yes or no:

function check({ code = 'abc123' }) {
  let endsInDigits = regexMatch({ pattern: '\\d+$', value: code })
  let lettersOnly = regexMatch({ pattern: /^[a-z]+$/, value: code })
  return { endsInDigits, lettersOnly }
}

Returns { endsInDigits: true, lettersOnly: false }. A pattern given as a string is a JavaScript string first, so a backslash is doubled ('\\d+$'); a regex literal (/\d+$/) needs no doubling. What the engine supports is listed under Regular expressions in The AJS Language.

jsonParse and jsonStringify are v1 data atoms; write JSON.parse(s) and JSON.stringify(v).

xmlParse hands the string to the host's xml.parse capability and returns whatever it produces, copied through the membrane. The VM has no XML parser of its own, so without that capability the call fails with Capability 'xml.parse' missing.

Store

With no store capability, a run gets its own in-memory store that holds get and set only, lives for that one run, and adds the warning Using default in-memory store (not suitable for production) to the run's warnings:

function remember() {
  storeSet({ key: 'user:1', value: { name: 'Ann' } })
  let user = storeGet({ key: 'user:1' })
  let missing = storeGet({ key: 'user:2' })
  return { user, missing }
}

Returns { user: { name: 'Ann' } }; missing is undefined, so it is left out of the result.

storeQuery passes query to the store's query method, in whatever form your store understands. storeVectorSearch calls store.vectorSearch(collection, vector, k). Both return [] when the store has no such method, which includes the default store.

storeQueryWhere sends a canonical verified predicate to the store instead of fetching rows and filtering them in the agent. The host builds the predicate outside the VM with canonicalizePredicate() from tjs-lang/lang, which turns a pure function's source into a plain object ({ key, canonical, ast, entry }), and passes it in as data, here as an argument:

// On the host
import { canonicalizePredicate } from 'tjs-lang/lang'

const adult = canonicalizePredicate('function isAdult(p) { return p.age >= 18 }')
const run = await vm.run(ast, { adult }, { capabilities: { store: myStore } })

// In the agent
function adults({ adult }) {
  let rows = storeQueryWhere({ predicate: adult, collection: 'users', limit: 10 })
  return { rows }
}

The store's queryPredicate({ collection, predicate, limit }) receives the predicate object and decides how to apply it; predicate.key does not change when the function is reformatted or its names are changed, so a store can cache on it. Unlike storeQuery and storeVectorSearch, storeQueryWhere fails rather than returning everything when the store has no queryPredicate, because a filter that silently does not filter is a data-exposure bug.

storeVectorSearch or storeSearch. Both call the store's vectorSearch. storeVectorSearch is a core atom: its input is vector, collection is optional, and it returns [] when the store cannot search. storeSearch is a battery atom: its input is queryVector, collection is required, it can pass a filter, and it fails when the store cannot search. Use storeSearch with the battery store, and storeVectorSearch with a store of your own that may lack the method.

Network

With no fetch capability, httpFetch uses a built-in client that fetches only from hosts the run option context.allowedFetchDomains lists. The doc site lists api.github.com, so this runs here; in your own VM, pass context: { allowedFetchDomains: ['api.github.com'] }:

function repo({ owner = 'tonioloewald', name = 'tjs-lang' }) {
  let r = httpFetch({ url: `https://api.github.com/repos/${owner}/${name}` })
  return { name: r.full_name, language: r.language }
}

Returns { name: 'tonioloewald/tjs-lang', language: 'TypeScript' }.

httpFetch returns the response body as data: parsed JSON when the response is JSON or responseType is 'json', a string otherwise, or a data: URL with responseType: 'dataUrl'. The built-in client returns the body of a 404 or a 500 the same way, without the status, so check the body. It does not follow redirects: a 3xx comes back as { redirect: true, status, location }, and fetching location is a new request. A network failure is an error the agent can catch, with the failure's message as e. A host's own fetch capability decides these things itself, and must return plain data, not a Response.

Methods other than GET and HEAD, and request headers not on the VM's default list, are refused unless the host allows them. The policy, including the header list, is in Hosting the VM under Fetch policy.

AI: llmPredict

llmPredict is the core model atom: a prompt in, a string out. The host supplies llm.predict(prompt, options) and decides which model answers.

// In the agent
let answer = llmPredict({
  prompt: 'Name the capital of France in one word.',
  options: { temperature: 0, maxTokens: 10 },
})

options takes these keys only: model, temperature, maxTokens (or max_tokens), topP (or top_p), stop, seed, responseFormat and tools. Any other key is refused. A responseFormat is { type: 'json_schema', json_schema: { name, schema } } (Schema.response builds it), { type: 'json_object' } or { type: 'text' }. A tool is { type: 'function', function: { name, description?, parameters?, strict? } }. Every schema in them must be a guest schema (see Schema in The AJS Language).

For structured output, build the format with Schema.response(name, shape), where shape is an example value or a schema, and parse the reply, which is still a string:

// In the agent
let format = Schema.response('capital', { city: '' })
let raw = llmPredict({ prompt: 'What is the capital of France?', options: { responseFormat: format } })
let answer = JSON.parse(raw) // { city: 'Paris' }

Schema.response('capital', { city: '' }) is { type: 'json_schema', json_schema: { name: 'capital', strict: true, schema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] } } }. Whether the model keeps to it is up to the model server.

AI: battery atoms

The battery atoms are not in the core set. The host registers them and passes capabilities that match, usually from getBatteries(), which connects to a local OpenAI-compatible model server:

// On the host
import { AgentVM, batteryAtoms } from 'tjs-lang/vm-ast'
import { getBatteries } from 'tjs-lang/batteries'
import { transpile } from 'tjs-lang/lang'

const vm = new AgentVM(batteryAtoms)
const batteries = await getBatteries()
const { ast } = transpile(source, { atoms: vm.atoms })
const run = await vm.run(ast, args, { fuel: 1000, capabilities: batteries })

Passing atoms to transpile makes it check calls to the battery atoms' inputs too. What getBatteries() returns, and how to supply the same keys from your own backends, is in Capabilities and Custom Atoms. With no model server, llmBattery and vector are empty, and these atoms fail with a "missing" error the agent can catch.

llmPredict or llmPredictBattery

Use llmPredict for a prompt and a string answer. Use llmPredictBattery when you need a system prompt, a multi-turn conversation, tool calls, or the whole message back.

llmPredictBattery

It returns the model's message. content is the text (or null when the model called tools) and tool_calls lists the calls. The message is an open object: fields a provider adds, such as reasoning_content, come through.

// In the agent
let reply = llmPredictBattery({
  system: 'Answer in one word.',
  user: 'What is the capital of France?',
})
let answer = reply.content // 'Paris'

llmVision

It returns a message, like llmPredictBattery. An http(s) image URL is a request the model server makes for the agent, so it gets the fetch rule: it is refused unless the run's context.allowedFetchDomains lists its host. Inline base64 image data always passes. To analyze a remote image without letting the model server reach it, fetch it with httpFetch({ url, responseType: 'dataUrl' }) and pass the result.

// In the agent
let page = httpFetch({ url: imageUrl, responseType: 'dataUrl' })
let seen = llmVision({
  prompt: 'Transcribe the text in this image.',
  images: [page],
})
let text = seen.content

Embeddings and vector search

storeVectorize({ text }) returns the embedding of text from the vector capability, as an array of numbers. Its model input is accepted but not passed on: the capability's own model is used.

storeCreateCollection({ collection, dimension? }) creates a collection in the store. storeVectorAdd({ collection, doc }) adds a document to it. The battery store does not embed for you: it needs the document's vector in an embedding field, so call storeVectorize first. storeSearch({ collection, queryVector, k?, filter? }) returns the k documents nearest to queryVector, best first, and costs 5 fuel plus k; the battery store ignores filter, which is for stores that support one. Unlike storeVectorSearch, these three fail when the store lacks the method rather than returning nothing.

// In the agent
storeCreateCollection({ collection: 'articles' })
let text = 'TJS types are examples.'
let embedding = storeVectorize({ text })
storeVectorAdd({ collection: 'articles', doc: { title: 'Types', text, embedding } })
let query = storeVectorize({ text: 'How do types work?' })
let hits = storeSearch({ collection: 'articles', queryVector: query, k: 3 })

Code and agents

agentRun runs another agent with input as its arguments and returns its result. agentId is one of three things:

• a procedure token from storeProcedure (below): the stored AST runs inside this VM;
• an AST object, such as one passed in the arguments: it runs inside this VM;
• any other string: the host's agent.run(agentId, input) capability decides what runs, as a separate run with its own budget.

Inside this VM the sub-agent gets a fresh scope that sees only input, and shares the run's fuel, heap ceiling and capabilities. If it fails, agentRun fails with its message, which the caller can catch.

transpileCode({ code }) turns AJS source into an AST, and runCode({ code, args }) transpiles and runs it, returning its result. Both need the host's code.transpile capability, so an agent can generate and run code only if the host allows it. Generated code runs as its own program: it sees only args, not the caller's variables or helpers, and shares the run's fuel and capabilities. runCode calls may nest 10 deep.

Before the source reaches code.transpile, the VM refuses it if it is over 8 KB (the run's maxSourceBytes option can lower that, never raise it) and charges fuel for its size. The cap matters more than the fuel: parsing happens before fuel can stop it, and a parser's worst case grows faster than the source does. Give the capability's own transpile a cap as well, so it is safe whoever calls it.

agentRun and runCode, like memoize and cache, keep the 1 s default timeout. It fires only while the atom is waiting, as on a sub-agent's slow fetch, which then fails with Atom 'agentRun' timed out; computation inside a sub-agent is bounded by fuel instead. A host whose sub-agents call slow services raises it.

A host that allows generated code:

// On the host
import { transpile } from 'tjs-lang/lang'

const run = await vm.run(ast, args, {
  fuel: 1000,
  capabilities: {
    code: { transpile: (source) => transpile(source, { maxSourceBytes: 8192 }).ast },
  },
  timeoutOverrides: { runCode: 10_000, agentRun: 30_000 },
})

And the agent:

// In the agent
let code = 'function double({ n = 1 }) { return { d: n * 2 } }'
let out = runCode({ code, args: { n: 21 } }) // { d: 42 }

Hosting the VM explains where to transpile untrusted source.

Stored procedures

storeProcedure({ ast }) saves an AST and returns a token (proc_…) that agentRun or the host's vm.run(token, args) can run later. The token expires after ttl milliseconds (default one hour), and an AST larger than maxSize bytes (default 100KB) is refused. The AST's format version (1 or 2, see Terms) is checked when it is stored, so an AST this VM cannot run is refused then rather than failing later for whoever runs the token. releaseProcedure({ token }) deletes one and returns whether it existed; clearExpiredProcedures() deletes the expired ones and returns how many.

The procedure store belongs to the process, not the run: a token stays valid across runs until it expires or is released. For a host running untrusted agents, that has consequences:

• The store is one map shared by every VM in the process. It is not scoped per run or per tenant: any run that holds a token can run it. Tokens are random UUIDs, so they cannot be guessed, but one that leaks to another tenant works there too.
• An agent needs no capability to store a procedure, and nothing limits how many it stores beyond its fuel and the per-AST size limit. Each stays in memory until it is released, or until it has expired and is cleared (by an attempt to run it, or by clearExpiredProcedures).
• A host that does not want agents to store procedures can refuse the atom with quotas: { storeProcedure: 0 }, which fails the call with Quota exceeded for 'storeProcedure': 0 calls allowed.

// In the agent; `child` is an AST the host passed in the arguments
let token = storeProcedure({ ast: child, ttl: 60000 })
let result = agentRun({ agentId: token, input: { n: 3 } })
let released = releaseProcedure({ token }) // true

Utilities

random() returns a float in [min, max), from 0 to 1 by default. format: 'integer' rounds it down, and format: 'base36' returns a random string of length characters (default 10) instead. uuid() returns a version 4 UUID. Both use the platform's secure random source when it has one.

hash({ value }) returns a hex digest, SHA-256 unless algorithm names another one the platform supports ('SHA-1', 'SHA-384', 'SHA-512'). A value that is not a string is hashed as its JSON. Hashing charges fuel for the size of the input.

function ids() {
  let id = uuid()
  let code = random({ format: 'base36', length: 6 })
  let die = random({ min: 1, max: 7, format: 'integer' })
  let sha1 = hash({ value: 'abc', algorithm: 'SHA-1' })
  return { id, code, die, sha1 }
}

sha1 is 'a9993e364706816aba3e25717850c26c9cd0d89d'; the others change on every run.

memoize and cache take steps, which AJS source cannot express, so only builder ASTs use them. memoize runs its steps once per key within a run and returns the saved result after that. cache saves the result in the store under cache:<key> for ttlMs (default 24 hours), so with a real store it survives across runs. Both require a key, and neither saves a result whose steps failed. The value saved is what the steps return or, if they return nothing, the variable named result that they set. In the builder the arguments are positional, steps first:

// On the host
import { Agent } from 'tjs-lang'
import { s } from 'tosijs-schema'

const ast = Agent.take()
  .cache(
    (b) => b.httpFetch({ url: 'https://api.example.com/rates' }).as('result'), // steps
    'rates-today', // key
    3_600_000 // ttlMs: one hour
  )
  .as('rates')
  .return(s.object({ rates: s.any }))
  .toJSON()
// a second run within the hour returns the stored rates without fetching

Console

consoleLog({ message }) records the message in the trace, when the run has trace: true. consoleWarn({ message }) adds it to the run's warnings as well. consoleError({ message }) sets the run's error, like Error(message), and the steps after it are skipped unless a catch takes it.

Call these atoms by name. As the rules at the top say, console.log(…), console.warn(…) and console.error(…) in AJS source are accepted but do nothing: they compile to calls on a builtin that records nothing, and console.error does not stop the run. An agent should put what its caller needs in the object it returns.

// In the agent
consoleWarn({ message: 'rate limit nearly reached' })
// run.warnings includes 'rate limit nearly reached'