The Deva Documentation - install, quick start, lifecycle, messaging between Devas, stamped packets, events and the full method reference.

Deva

npm Tests

@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

  1. Requirements
  2. Install
  3. Quick start
  4. Constructor options
  5. Lifecycle
  6. Messaging: question, answer, ask, talk, listen
  7. The packet
  8. Stamping and the hash tiers
  9. The workflow: features, zones, actions, states, intents, beliefs, contexts
  10. Events
  11. Error handling
  12. Help
  13. Configuration files
  14. Testing
  15. Method reference
  16. License
  17. 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 after await init(). The init() promise resolves after ready has run.

  • Methods must return a Promise. answer() calls this.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)

  1. Hashes the core package data (md5, sha256, sha512).
  2. 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.
  3. Marks the Deva active, then inherits into child devas, binds listeners/methods/utils/func/lib, and registers listeners.
  4. Runs the client feature chain: Client, then License, Error, Log, Data, Report, Legal, Security, Support, Services, Systems, then Done. For each one that the client’s features object defines, the Deva stores this._<feature> = {client_id, client_name, concerns, global, personal}, where personal is the entry under devas[agent.key]. Methods found in client.features[x].methods are bound into this.methods.
  5. Calls onInit(data, resolve) if you defined it, otherwise start.

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 calls on<Key>(data, resolve), and the hook decides what happens next: call the next step (this.enter(data, resolve)) or resolve(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 returns true if anyone was listening.
  • listen(evt, callback), once(evt, callback) and ignore(evt, callback) add, add-once and remove listeners.
  • prompt(text) emits a stamped devacore:prompt packet.

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
  • id is a uid() 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. Use packet.id.uid for the id value. uid(true) uses a random UUID for uid. The default is a time-based numeric id.
  • agent and client are copies with their own hashes.
  • finish and complete are timestamps added by those steps.
  • A method’s result becomes a.text, a.html and a.data. A plain string result fills text.

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 a hash action per tier (<label>:<algo>:<uid>).

  • _unstamp(data) removes them, logging a delete action per tier as <algo>:<uid> using data.id?.uid. If the data has no id or the id has no uid, it uses this._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. Call reject to fail the caller’s promise, or the promise stays pending;
  • otherwise it calls reject(err), or returns Promise.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_dir is the Deva’s base directory, usually __dirname of the Deva’s file. Help files live in <help_dir>/help/.
  • The first word of msg picks the file and the section, as file:part. The file defaults to main, and the part defaults to MAIN and is always matched in upper case.
  • A section is the text between ::BEGIN:<PART> and ::END:<PART> (the container markers 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.

  • 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)