Docs
The Deva Documentation - install, quick start, lifecycle, messaging between Devas, stamped packets, events and the full method reference.
Deva
@indra.ai/deva
Deva is a Vedic-based, event-driven, context-aware Feature, Zone, Action and State machine framework for building integrated artificial intelligence agents (“Devas”) in Node.js. Every Deva is one Deva class instance on a shared event bus. As it works, it moves through named features, zones, actions, states, intents, beliefs and contexts, and it broadcasts each step as an event. Every packet it builds is stamped with cumulative md5, sha256 and sha512 hashes.
Deva is distributed under the Vedic License Agreement (VLA). Read License before you use it.
Contents
- Requirements
- Install
- Quick start
- Constructor options
- Lifecycle
- Messaging: question, answer, ask, talk, listen
- The packet
- Stamping and the hash tiers
- The workflow: features, zones, actions, states, intents, beliefs, contexts
- Events
- Error handling
- Help
- Configuration files
- Testing
- Method reference
- License
- Links and author
Requirements
- Node.js 22 or later (
engines.node: ">=22"), npm 9.5.1 or later. - ES modules only. The package is
"type": "module"and uses JSON import attributes (import x from './x.json' with {type: 'json'}).require()won’t work. - A client object that carries a VLA matching the one in Deva’s
package.json.init()refuses to start without it (see Lifecycle).
Install
npm install @indra.ai/deva
Quick start
This is a minimal working Deva with one method. client.json is a client file shaped like tests/client.json. Its DATA.VLA must match the VLA block in Deva’s package.json.
import Deva from '@indra.ai/deva';
import Client from './client.json' with {type: 'json'};
const client = Client.DATA; // must carry a VLA matching the Deva package VLA
const hello = new Deva({
info: {id: 'hello', name: 'Hello Deva', version: '0.0.1', VLA: client.VLA},
agent: {
id: 'hello',
key: 'hello',
prompt: {emoji: '👋', text: 'hello'},
profile: {name: 'Hello Deva'},
},
config: {hash: {}}, // optional: ready() writes this._config.hash[agent.key]
vars: {context: {}}, // required: context() looks up this.vars.context
listeners: {
'devacore:error'(packet) {
console.log('error:', packet.error.message);
},
},
methods: {
greet(packet) {
return Promise.resolve({text: `hello ${packet.q.text}`});
},
},
async onReady(data, resolve) {
const packet = await this.question('/greet world');
console.log(packet.a.text); // hello world
return resolve(data);
},
});
hello.init(client);
Run it with node examples/hello-world.js and it prints hello world.
Three things to know from this example:
-
Do your work from
onReady, not afterawait init(). Theinit()promise resolves afterreadyhas run. -
Methods must return a Promise.
answer()callsthis.methods[method](packet).then(...).
Constructor options
new Deva(opts) accepts:
| Option | What it is |
|---|---|
id |
Instance id. Defaults to randomUUID(). |
info |
Package-style info object (id, name, version, dir, VLA, …). Returned by info(). info.VLA.uid goes into every uid(). |
agent |
The agent profile: id, key (the Deva’s name on the bus), prompt, profile (name, and optional warning, notice, copyright, status, vectors, owner, creator, salute). It can also carry custom zones, actions, states, intents, beliefs and messages, which are merged in without overwriting the core ones (keys already in config win), and then removed from the agent object. |
config |
Local config. Needs a hash object. Can set timeout.ask in ms (default 30000, 0 disables it). |
vars |
Free-form variables on this.vars. vars.context maps context keys to display text. |
utils, func |
Your helper functions. Bound to the Deva at init. |
methods |
Public commands, reachable by question('/name ...') or by another Deva’s #key name .... Bound at init. Each takes a packet and returns a Promise of a string or {text, html, data}. |
listeners |
{eventName: handler}. Bound and registered on the event bus at init. |
devas |
Child Deva instances. They inherit events, lib and config and are init‘d during ready. |
modules |
Third-party modules for your own use. |
events |
An existing EventEmitter to share. Defaults to a new one. |
maxListeners |
Passed to events.setMaxListeners. Default 0 (unlimited). |
| Lifecycle hooks | onInit, onStart, onEnter, onDone, onReady, onFinish, onComplete, onStop, onClose, onLeave, onExit, onShutdown, onError. |
Any other top-level option is copied onto the instance, as long as it doesn’t clash with an existing property.
Lifecycle
Start-up: init(client)
- Hashes the core package data (md5, sha256, sha512).
- Runs
license_check(client.VLA, core.VLA), comparing sha256 hashes of the two VLA objects. On a mismatch it prompts and resolves with❌ The Provided Client License Is Invalid, and the Deva stays inactive. - Marks the Deva active, then inherits into child devas, binds
listeners/methods/utils/func/lib, and registers listeners. - Runs the client feature chain:
Client, thenLicense,Error,Log,Data,Report,Legal,Security,Support,Services,Systems, thenDone. For each one that the client’sfeaturesobject defines, the Deva storesthis._<feature>={client_id, client_name, concerns, global, personal}, wherepersonalis the entry underdevas[agent.key]. Methods found inclient.features[x].methodsare bound intothis.methods. - Calls
onInit(data, resolve)if you defined it, otherwisestart.
The invoke chain
start, enter, done, ready, finish, complete, stop, close, leave, exit and shutdown all run through _invoke. Each step sets the context, zone, action and state to its key, writes a timestamp under that key on the data (data.start = Date.now() and so on), re-stamps the data, and emits its devacore:<key> event. Then:
- if an
on<Key>hook exists, it callson<Key>(data, resolve), and the hook decides what happens next: call the next step (this.enter(data, resolve)) orresolve(data); - otherwise it moves on to the next step itself.
| Step | Next by default | Hook |
|---|---|---|
| start | enter | onStart |
| enter | done | onEnter |
| done | ready | onDone |
| ready | (resolve) | onReady |
| finish | complete | onFinish |
| complete | (resolve) | onComplete |
| stop | close | onStop |
| close | leave | onClose |
| leave | exit | onLeave |
| exit | shutdown | onExit |
| shutdown | (resolve) | onShutdown |
ready also stores sha256 hashes of vars, utils, listeners, modules, func and methods in config.hash[agent.key], and inits each child Deva in devas.
finish and complete wrap every answer (see Messaging).
Shutdown: stop()
stop() returns a Promise and runs stop, close, leave, exit and shutdown. exit clears the inherited feature data (_license, _security, and so on). shutdown removes listeners and pending asks, and clears modules, listeners, events, _config and _active. After that, the Deva answers most calls with ⭕️ OFFLINE. With no hooks defined, await deva.stop() resolves with the data object, whose key is 'shutdown'.
Messaging
question(text, data=false)
question is the entry point. It returns a Promise and reads the first word of text:
| Form | Example | What happens |
|---|---|---|
Command (/) |
/greet world |
Calls local methods.greet through answer(). packet.q.text is world. A /method:a:b form puts ['method','a','b'] in meta.params. |
Ask (#) |
#helper shout hi |
Sends the packet to the Deva whose agent key is helper and waits for its reply. |
| Plain text | hi there |
Calls methods.question, if you defined one. |
Unknown methods resolve to a packet whose a.text is ⛔️ METHOD NOT FOUND <agent> <method>.
Ask between Devas
For #key method text, the asking Deva emits key:ask and waits once on key:ask:<packet uid>. The target’s ask(packet) runs methods[method], builds packet.a, and replies on that event. The asker then runs finish/complete and resolves. Each Deva listens on <its key>:ask automatically, as part of the state listeners registered at init.
- If nobody is listening on
key:ask, it resolves right away with⛔️ ASK TARGET NOT FOUND. - If no reply comes within
config.timeout.ask(default 30 s), it resolves with⛔️ ASK TIMEOUT.
Tested: a parent Deva with devas: {helper} asked #helper shout hi there and got HI THERE back, with a.meta.key === 'helper'.
Events directly
talk(evt, packet)emits on the bus and returnstrueif anyone was listening.listen(evt, callback),once(evt, callback)andignore(evt, callback)add, add-once and remove listeners.prompt(text)emits a stampeddevacore:promptpacket.
The packet
A packet resolved from question() looks like this (keys in order, verified):
packet: id, q, a, created, finish, complete, md5, sha256, sha512
q: id, agent, client, meta{key, method, params}, text, data, created, md5, sha256, sha512
a: id, agent, client, meta{key, method, params}, text, html, data, created, md5, sha256, sha512
idis auid()object, not a string:uid, time, iso, utc, date, license, fingerprint, client, agent, machine, core_hash, status, warning, notice, vectors, owner, creator, salute, copyright, md5, sha256, sha512. Usepacket.id.uidfor the id value.uid(true)uses a random UUID foruid. The default is a time-based numeric id.agentandclientare copies with their own hashes.finishandcompleteare timestamps added by those steps.- A method’s result becomes
a.text,a.htmlanda.data. A plain string result fillstext.
Stamping and the hash tiers
Deva hashes in three tiers, in the order config.hashes = ['md5', 'sha256', 'sha512']:
| Tier | Intended use |
|---|---|
| md5 | Fast, everyday (civilian) verification |
| sha256 | Government and authority verification |
| sha512 | Military, agency and legal high-security use |
The tiers are cumulative by design. Each hash is taken over the object including the hashes before it, so sha256 covers md5, and sha512 covers both. Hashes are base64 digests of JSON.stringify(data) (see hash(data, algo)).
-
_stamp(data, label='', uid='')adds the three hashes in order and returns the same object. When a label is given, it logs ahashaction per tier (<label>:<algo>:<uid>). -
_unstamp(data)removes them, logging adeleteaction per tier as<algo>:<uid>usingdata.id?.uid. If the data has noidor theidhas nouid, it usesthis._messages.noid(⛔️ NO ID PROVIDED) instead of throwing. -
To re-stamp after a change,
_stamp(_unstamp(data), label, uid). Since the tiers are cumulative, stamping twice without unstamping would change the values.
The return path in Core methods is: the return action, then the good intent, then _stamp.
A few spots (init, _workflow, client(), agent(), machine(), uid()) hash manually on purpose and are commented as such. Calling _stamp there would log a state change from inside the state machinery and overflow the stack.
The workflow
Each call to feature(), zone(), action(), state(), intent() or belief() takes (value, extra). If value exists in the matching list, it sets the current value, emits a hashed devacore:<key> event with text = the list’s label plus extra, and returns that data. Unknown values are ignored silently. context(value, extra) does the same, using vars.context for the label, and accepts any value.
The plural methods return a stamped object whose value is the full list:
| List | Method | Default | Source |
|---|---|---|---|
| features | features() |
— | _data/features.json |
| zones | zones() |
— | _data/zones.json |
| actions | actions() |
— | _data/actions.json |
| states | states() |
offline |
_data/states.json |
| intents | intents() |
neutral |
_data/intents.json |
| beliefs | beliefs() |
vedic |
_data/beliefs.json |
| contexts | contexts() |
— | your agent |
The features are init, agent, client, license, error, log, data, report, legal, security, support, services, systems. Each client feature has a getter of the same name (security(), support(), …) that returns a copy of what the client supplied for it.
Events
All core events are listed in _data/events.json (25). The ones you’ll usually listen to:
devacore:prompt, devacore:error, devacore:question, devacore:answer, devacore:ask, devacore:start, devacore:enter, devacore:done, devacore:ready, devacore:finish, devacore:complete, devacore:stop, devacore:exit, devacore:shutdown, devacore:context, devacore:feature, devacore:zone, devacore:action, devacore:state, devacore:intent, devacore:belief, devacore:load, devacore:unload.
Error handling
err(err, packet, reject) is the single error path. It sets the bad intent and the error context, feature, zone, action and state. It emits a stamped devacore:error packet carrying error: {name, message, stack} and the related packet. Then:
- if you defined
onError(err, packet, reject), it returns that, and you own the outcome. Callrejectto fail the caller’s promise, or the promise stays pending; - otherwise it calls
reject(err), or returnsPromise.reject(err).
A method that rejects or throws ends up here. Most calls made while the Deva is inactive return or resolve ⭕️ OFFLINE instead of throwing.
Help
Every Deva can carry its own help, written in feecting, the language Devas use to talk to each other. The name stands for Functional Expressive Emergent Cognitive Technical Intelligent Neural Generator a Key Value Pair Line Label Function Method Event Listener Zone Feature Action State Procedural Asynchronous Vector Programming Language. A Deva’s help system starts small and grows as the Deva grows.
help(msg, help_dir) looks in the Deva’s own folder and returns one section of a help file:
help_diris the Deva’s base directory, usually__dirnameof the Deva’s file. Help files live in<help_dir>/help/.- The first word of
msgpicks the file and the section, asfile:part. The file defaults tomain, and the part defaults toMAINand is always matched in upper case. - A section is the text between
::BEGIN:<PART>and::END:<PART>(thecontainermarkers in_data/index.js).
my-deva/
index.js
help/
main.feecting
ask.feecting
::BEGIN:MAIN
# My Deva
p: What this Deva does and how to talk to it.
::END:MAIN
::BEGIN:ASK
## Ask
p: Use #key method text to ask another Deva.
::END:ASK
| Call | Returns |
|---|---|
help('', __dirname) or help('main', __dirname) |
the MAIN section of help/main.feecting |
help('main:ask', __dirname) |
the ASK section of help/main.feecting |
help('ask', __dirname) |
the MAIN section of help/ask.feecting |
| a file or section that doesn’t exist | ⛔️ HELP NOT FOUND (_messages.help_not_found) |
| any call while the Deva is inactive | ⭕️ OFFLINE |
The section comes back as raw feecting text, with the surrounding newlines kept, so the Deva can pass it on to be parsed or shown. A found section sets the valid state and good intent. A missing file sets invalid and bad tagged help:not:exists, and a missing section sets them tagged help:not:found. Neither one raises an error. If help_dir isn’t passed, the promise rejects with a TypeError from path.join.
Configuration files
| File | Contents |
|---|---|
_data/index.js |
Command char /, ask char #, timeout.ask: 30000, hashes, container markers (::BEGIN/::END), uid salt range, inherit/bind lists, the invoke chain table, defaults |
_data/events.json |
Event names |
_data/features.json |
Feature labels |
_data/zones.json, actions.json, states.json, intents.json, beliefs.json |
Workflow labels |
_data/msgs.json |
System messages such as offline, noid, asktimeout, noask, method_not_found, plus default warning, notice and copyright text |
Each JSON file has id, title, copyright, VLA and DATA, and the values are in DATA.
Testing
npm test
This runs the assertion suite in tests/suite/ with Node’s built-in test runner (node --test), with no extra dependencies. GitHub Actions runs it on every push and pull request on Node 22 and 24, shown by the Tests badge at the top.
| File | Covers | Tests |
|---|---|---|
00-build.test.js |
Building a Deva | 1 |
01-init.test.js |
init() order and failures |
5 |
02-getters.test.js |
Getters and stamped copies | 31 |
03-hash.test.js |
The md5, sha256 and sha512 tiers | 6 |
04-license.test.js |
license_check |
6 |
05-messaging.test.js |
question, answer, ask and talk | 12 |
06-shutdown.test.js |
stop() and the shutdown chain |
8 |
07-help.test.js |
help() and feecting help files |
10 |
tests/suite/_deva.js builds a fresh test Deva from tests/agent.json and tests/client.json, and tests/suite/help/ holds the sample .feecting files for the help tests. The full list with edge cases is at deva.world/tests.
npm run demo runs the older tests/index.js walkthrough, which builds a Deva, runs it through the lifecycle and prints the log.
Method reference
These are the public methods.
| Method | Returns | Notes |
|---|---|---|
init(client) |
Promise | Starts the Deva. See the onReady caveat above. |
question(text, data?) |
Promise<packet> | /cmd, #key method, or plain text. |
ask(packet) |
— | Answer side of # asks. Usually called for you. |
stop() |
Promise | Runs the shutdown chain. |
talk(evt, packet) |
boolean | Emit on the bus. |
listen / once / ignore |
— | Manage listeners. |
prompt(text) |
stamped data | Emits devacore:prompt. |
feature/zone/action/state/intent/belief(value, extra?) |
data or undefined |
Set and broadcast. |
context(value, extra?) |
stamped data | Needs vars.context. |
features/zones/actions/states/intents/beliefs/contexts() |
stamped {id, key, value, agent, client, created} |
Full lists. |
agent() / client() |
hashed copy | |
info() / core() |
stamped copy | |
status() |
string | <profile.name> active since <date> |
uid(guid=false) |
uid object | See The packet. |
hash(data, algo='md5') |
base64 string | md5, sha256, sha512 |
_stamp(data, label?, uid?) / _unstamp(data) |
same object | See Stamping. |
license_check(personalVLA, packageVLA) |
stamped approval or false |
|
load(key, client) / unload(key) |
Promise | Init or stop a child Deva in devas. |
err(err, packet, reject?) |
— | See Error handling. |
help(msg, help_dir) |
Promise of feecting text | See Help. |
Not covered here because they weren’t exercised for this README: sign(packet), machine(), and the lib helpers (this.lib.copy, formatDate, and others).
License
Deva is distributed under the Vedic License Agreement, version 1.4.2, VLA 31711622713594414221, owned by Quinn Michaels, through License Deva. The full text is in LICENSE.md. It states, among other things, that:
- by accessing or using the Software, you agree to its terms;
- the Software is the sole proprietary property of the Owner;
- use is subject to a threefold hierarchy: Vedic Law, the Constitution of the United States, and Owner Authority;
- modification, distribution, sub-licensing, derivative works, reverse engineering, and official, government or commercial use without the Owner’s verified authorization are prohibited;
- unauthorized use is subject to Vedic fines and sanctions.
Read LICENSE.md in full before you use the Software. This summary isn’t a substitute for it.
Copyright ©2000-2026 Quinn Michaels; All rights reserved.
Links and author
- Repository: https://github.com/indraai/deva
- Issues: https://github.com/indraai/deva/issues
- npm: https://www.npmjs.com/package/@indra.ai/deva
- Homepage: https://indra.ai
Author: Quinn Michaels, Inside The Net, Inc. (quinn@indra.ai)