@indra.ai/deva 1.62.91 → 1.62.93
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/_includes/header.html +1 -0
- package/package.json +1 -1
- package/vibe.md +377 -0
package/README.md
CHANGED
|
@@ -116,7 +116,7 @@ Any other top-level option is copied onto the instance, as long as it doesn't cl
|
|
|
116
116
|
1. Hashes the core package data (md5, sha256, sha512).
|
|
117
117
|
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.
|
|
118
118
|
3. Marks the Deva active, then inherits into child devas, binds `listeners`/`methods`/`utils`/`func`/`lib`, and registers listeners.
|
|
119
|
-
4. Runs the client feature chain: `Client`, then `License`, `Error`, `Log`, `Data`, `Report`, `
|
|
119
|
+
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`.
|
|
120
120
|
5. Calls `onInit(data, resolve)` if you defined it, otherwise `start`.
|
|
121
121
|
|
|
122
122
|
### The invoke chain
|
package/_includes/header.html
CHANGED
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"id": "23221940810208468106",
|
|
3
3
|
"name": "@indra.ai/deva",
|
|
4
|
-
"version": "1.62.
|
|
4
|
+
"version": "1.62.93",
|
|
5
5
|
"description": "Deva Core a Vedic-inspired Event Based Context Aware Feature, Zone, Action, and State Machine integrated Artificial Intelligence Framework",
|
|
6
6
|
"main": "index.js",
|
|
7
7
|
"license": "VLA:23221940810208468106 LICENSE.md",
|
package/vibe.md
ADDED
|
@@ -0,0 +1,377 @@
|
|
|
1
|
+
---
|
|
2
|
+
layout: page
|
|
3
|
+
title: Vibe Coding with Deva
|
|
4
|
+
description: A plain-English guide to building with the Deva Core when you work with an AI assistant and don't read every line yourself.
|
|
5
|
+
image: /assets/banner.png
|
|
6
|
+
permalink: /vibe/
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
[](https://www.npmjs.com/package/@indra.ai/deva)
|
|
10
|
+
|
|
11
|
+
**{{page.description}}**
|
|
12
|
+
|
|
13
|
+
"Vibe coding" means building software by describing what you want to an AI assistant, accepting most of what it writes, and checking the results rather than every line. That's a real way to work, and the **Deva Core** (`@indra.ai/deva`) suits it well in one way: it writes down everything it does. If you can read its records, you can see what your code actually did, even if you didn't write that code yourself.
|
|
14
|
+
|
|
15
|
+
This page explains the Core in plain English, using one picture the whole way through.
|
|
16
|
+
|
|
17
|
+
## The picture: a small office
|
|
18
|
+
|
|
19
|
+
Imagine a small office.
|
|
20
|
+
|
|
21
|
+
- **The specialists.** Each **Deva** is a specialist who sits at a desk and is good at a few jobs. One greets people, one translates, one does sums. A Deva's jobs are its **methods**.
|
|
22
|
+
- **The intercom.** The office has one shared intercom. Anyone can make an announcement, and anyone who's tuned in hears it. Specialists also use it to ask each other for help. In code this is the **event bus** (`this.events`), and the Core's own announcements all start with `devacore:`.
|
|
23
|
+
- **The logbook.** Every specialist writes down each step as they do it: which part of the business it's for, where they are, what they're doing, what condition the work is in, and why. These are the **diary labels**: feature, zone, action, state and intent.
|
|
24
|
+
- **The wax seals.** Every record and every message gets sealed with three wax seals, one on top of the other. If anyone changes the paper afterwards, the seals no longer match. These are the **hashes** (md5, sha256, sha512).
|
|
25
|
+
|
|
26
|
+
Keep this picture in mind. Every section below goes back to it.
|
|
27
|
+
|
|
28
|
+
## Intent and principles first
|
|
29
|
+
|
|
30
|
+
Before the mechanics, it helps to know what the Core is *for*.
|
|
31
|
+
|
|
32
|
+
The Deva Core is meant to be a **deterministic, auditable agent core**. "Deterministic" means the same steps happen in the same order every time. "Auditable" means someone can come along later and check what happened. That's why the logbook and the seals aren't optional extras. They're built into almost every function. In the Core, each action leaves a labeled, sealed record.
|
|
33
|
+
|
|
34
|
+
A few principles follow from that:
|
|
35
|
+
|
|
36
|
+
- **A fixed vocabulary.** The logbook uses a fixed list of words, kept in the Core's `_data` files. A `valid` state means the same thing in every Deva, so records can be searched and compared without guessing.
|
|
37
|
+
- **Every record is sealed.** Packets and records carry three cumulative hashes. Each seal is pressed over the paper *and the seals beneath it*, so sha256 covers md5, and sha512 covers both. This tiering is deliberate. The README describes md5 as fast everyday verification, sha256 as government and authority verification, and sha512 as military, agency and legal high-security use.
|
|
38
|
+
- **Licensed use.** The Core is distributed under the **Vedic License Agreement (VLA)**, owned by Quinn Arjuna America Michaels. A Deva will not start unless the client it serves carries a VLA that matches the one in the Core's `package.json`.
|
|
39
|
+
- **A stated legal order.** `LICENSE.md` says use of the software "is subject to a threefold hierarchy of law": first Vedic Law, "as the supreme spiritual and religious authority"; second the Constitution of the United States, as "the secular legal framework"; and third Owner Authority, resting with Quinn Arjuna America Michaels, "whose signature and consent are required for any valid license." It adds: "All three levels must be satisfied; violation of any one constitutes unlawful use."
|
|
40
|
+
|
|
41
|
+
**Read [LICENSE.md](https://github.com/indraai/deva/blob/master/LICENSE.md) in full before you build anything with the Core.** Among other things, it restricts modification, distribution, derivative works, and commercial or government use without the Owner's verified authorization, and it limits use to the United States. This page is not a substitute for it, and your AI assistant can't decide for you whether your use is allowed.
|
|
42
|
+
|
|
43
|
+
## What a Deva is
|
|
44
|
+
|
|
45
|
+
A Deva is one instance of the single `Deva` class in the Core's `index.js`. You create it with `new Deva({...})` and give it:
|
|
46
|
+
|
|
47
|
+
- an **agent**: who this specialist is (`key`, `profile.name`, and so on). The `key` is its name on the intercom.
|
|
48
|
+
- **methods**: the jobs it can do. Each one takes a packet and **must return a Promise**.
|
|
49
|
+
- **listeners**: what it does when it hears a particular announcement.
|
|
50
|
+
- optional **hooks** such as `onReady`, which run at points in its lifecycle.
|
|
51
|
+
- optional **child Devas**: specialists who work inside this one's office.
|
|
52
|
+
|
|
53
|
+
Then you call `init(client)` with a **client** object. The client is who the office is working for. It carries the VLA and the settings for each client feature.
|
|
54
|
+
|
|
55
|
+
The Core runs on **Node.js 22 or later** and is **ES modules only** (`import`, not `require`). It has no runtime dependencies.
|
|
56
|
+
|
|
57
|
+
## The logbook: diary labels
|
|
58
|
+
|
|
59
|
+
{% assign n_features = site.data.features.DATA | size %}{% capture u_features %}{{ "/core/features/" | relative_url }}{% endcapture %}
|
|
60
|
+
{% assign n_zones = site.data.zones.DATA | size %}{% capture u_zones %}{{ "/core/zones/" | relative_url }}{% endcapture %}
|
|
61
|
+
{% assign n_actions = site.data.actions.DATA | size %}{% capture u_actions %}{{ "/core/actions/" | relative_url }}{% endcapture %}
|
|
62
|
+
{% assign n_states = site.data.states.DATA | size %}{% capture u_states %}{{ "/core/states/" | relative_url }}{% endcapture %}
|
|
63
|
+
{% assign n_intents = site.data.intents.DATA | size %}{% capture u_intents %}{{ "/core/intents/" | relative_url }}{% endcapture %}
|
|
64
|
+
{% assign n_beliefs = site.data.beliefs.DATA | size %}{% capture u_beliefs %}{{ "/core/beliefs/" | relative_url }}{% endcapture %}
|
|
65
|
+
|
|
66
|
+
Every step a Deva takes goes into the logbook with up to six kinds of label. Each label comes from a fixed list in `_data`:
|
|
67
|
+
|
|
68
|
+
| Label | Plain meaning | In the office | List |
|
|
69
|
+
|---|---|---|---|
|
|
70
|
+
| **feature** | which part of the business | "this is Security work" | [{{ n_features }} features]({{ u_features }}) |
|
|
71
|
+
| **zone** | where it's happening | "I'm at the answer desk" | [{{ n_zones }} zones]({{ u_zones }}) |
|
|
72
|
+
| **action** | what was done | "I hashed it", "I returned it" | [{{ n_actions }} actions]({{ u_actions }}) |
|
|
73
|
+
| **state** | what condition it's in | "valid", "try", "catch" | [{{ n_states }} states]({{ u_states }}) |
|
|
74
|
+
| **intent** | why, or how it turned out | "good", "bad", "lawful" | [{{ n_intents }} intents]({{ u_intents }}) |
|
|
75
|
+
| **belief** | the stance the work is recorded under | "vedic" | [{{ n_beliefs }} beliefs]({{ u_beliefs }}) |
|
|
76
|
+
|
|
77
|
+
There's also a free-form **context** (`this.context(value, extra)`), whose display text comes from your own `vars.context`.
|
|
78
|
+
|
|
79
|
+
Writing a line is one call:
|
|
80
|
+
|
|
81
|
+
```javascript
|
|
82
|
+
this.state('valid', 'greet:42');
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
That call sets the Deva's current state to `valid`, builds a small record (`id`, `key`, `value`, `text`, `agent`, `client`, `created`), seals it with all three hashes, announces it on the intercom as `devacore:state`, and returns the record. The `text` is the label from the list plus whatever you passed as the second argument. When we ran it, the record's text was `✏️ Valid greet:42` (with our id in place of `42`).
|
|
86
|
+
|
|
87
|
+
Each list also has a plural reader, such as `this.states()`, `this.actions()` and `this.zones()`. It returns a sealed packet with the whole list under `value`.
|
|
88
|
+
|
|
89
|
+
One rule matters a lot: **if you use a word that isn't on the list, nothing happens.** `this.state('not_a_state')` returns `undefined`, writes nothing and announces nothing. There's no error. See the honest section below.
|
|
90
|
+
|
|
91
|
+
## Wax seals: hashing and fingerprints
|
|
92
|
+
|
|
93
|
+
**Hashing.** `this.hash(data, algo)` turns any object into a short base64 string using md5, sha256 or sha512. Change one character of the data and the hash changes completely. `_stamp(data)` presses all three seals onto an object, in order, each one over the object including the seals before it. `_unstamp(data)` removes them so the object can be resealed after a change. Most Core functions seal their record just before returning it.
|
|
94
|
+
|
|
95
|
+
**Fingerprints.** Every record gets an `id` made by `this.uid()`. That's not just a number. It's an object with the id value itself (`id.uid`, a 20-digit number by default, or a random UUID with `uid(true)`), several forms of the date, the license uid, and the sha256 seals of the client, the agent, the machine and the Core itself. Those are combined into a single **fingerprint**. So each record says, in effect, *who* it was for, *which* specialist made it, *on which machine*, *with which version of the Core*, and *when*. The id also carries its own three seals.
|
|
96
|
+
|
|
97
|
+
When you want the id value, use `packet.id.uid`, not `packet.id`.
|
|
98
|
+
|
|
99
|
+
## Starting up: the lifecycle
|
|
100
|
+
|
|
101
|
+
Opening the office for the day goes like this when you call `deva.init(client)`:
|
|
102
|
+
|
|
103
|
+
1. **Seal the Core.** The Core seals its own package data.
|
|
104
|
+
2. **Check the license.** `license_check(client.VLA, core.VLA)` compares sha256 seals of the two VLA objects. If the client has no VLA, `init` resolves with `❌ Bad Personal VLA`. If they don't match, it resolves with `❌ Invalid VLA Check`. Either way the Deva stays inactive and nothing else runs.
|
|
105
|
+
3. **Open the doors.** The Deva marks itself active, passes the intercom and shared tools to its child Devas, binds your methods and listeners, and tunes in to its own announcements.
|
|
106
|
+
4. **Learn the client.** It runs the **client feature chain**: `Client`, then `License`, `Error`, `Log`, `Data`, `Report`, `Legal`, `Security`, `Support`, `Services`, `Systems`, then `Done`. Each step copies that feature's settings from `client.features` into the Deva.
|
|
107
|
+
5. **The invoke chain.** It then calls `onInit` if you wrote one, otherwise `start`.
|
|
108
|
+
|
|
109
|
+
### The invoke chain
|
|
110
|
+
|
|
111
|
+
After `init`, the Deva walks through named steps. Each step does the same things: writes its own logbook lines, puts a timestamp on the data under its name (`data.start`, `data.ready`, ...), reseals the data, and announces `devacore:<step>` on the intercom. Then:
|
|
112
|
+
|
|
113
|
+
- if you wrote a hook for that step (`onStart`, `onReady`, ...), **your hook decides what happens next**. It must either call the next step or call `resolve(data)`;
|
|
114
|
+
- if you didn't, the Core moves on to the next step by itself.
|
|
115
|
+
|
|
116
|
+
| Step | Goes on to | Your hook |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| start | enter | `onStart` |
|
|
119
|
+
| enter | done | `onEnter` |
|
|
120
|
+
| done | ready | `onDone` |
|
|
121
|
+
| ready | (finished) | `onReady` |
|
|
122
|
+
| finish | complete | `onFinish` |
|
|
123
|
+
| complete | (finished) | `onComplete` |
|
|
124
|
+
| stop | close | `onStop` |
|
|
125
|
+
| close | leave | `onClose` |
|
|
126
|
+
| leave | exit | `onLeave` |
|
|
127
|
+
| exit | shutdown | `onExit` |
|
|
128
|
+
| shutdown | (finished) | `onShutdown` |
|
|
129
|
+
|
|
130
|
+
`ready` also seals your `vars`, `utils`, `listeners`, `modules`, `func` and `methods` into `config.hash[agent.key]` (a snapshot of how the office was set up) and starts each child Deva.
|
|
131
|
+
|
|
132
|
+
**`onReady` is the moment the office is open.** Do your work from there, or after hearing `devacore:ready`. Don't do it right after `await init()`. The section on limits explains why.
|
|
133
|
+
|
|
134
|
+
## Talking on the intercom: messaging
|
|
135
|
+
|
|
136
|
+
### Asking a specialist a question
|
|
137
|
+
|
|
138
|
+
`this.question(text)` is the front desk. It returns a Promise and looks at the first word:
|
|
139
|
+
|
|
140
|
+
| You say | Example | What happens |
|
|
141
|
+
|---|---|---|
|
|
142
|
+
| `/name ...` | `/greet world` | Runs this Deva's own `methods.greet`. `packet.q.text` is `world`. |
|
|
143
|
+
| `#key name ...` | `#helper shout hi there` | Asks the Deva whose key is `helper` to run its `shout` method, and waits for the reply. |
|
|
144
|
+
| plain words | `hello there` | Runs `methods.question` if you wrote one. |
|
|
145
|
+
|
|
146
|
+
A method can return a plain string or `{text, html, data}`. That becomes the answer.
|
|
147
|
+
|
|
148
|
+
If the method doesn't exist, you still get a packet back, and its answer text is `⛔️ METHOD NOT FOUND <agent> <method>`. If you `#ask` a key nobody's listening for, you get `⛔️ ASK TARGET NOT FOUND` straight away. If the other Deva hears but never replies, you get `⛔️ ASK TIMEOUT` after `config.timeout.ask` milliseconds (30000 by default, `0` turns the timeout off).
|
|
149
|
+
|
|
150
|
+
### Announcing and listening
|
|
151
|
+
|
|
152
|
+
- `this.talk(evt, packet)` makes an announcement. It returns `true` if anyone was listening and `false` if no one was.
|
|
153
|
+
- `this.listen(evt, fn)`, `this.once(evt, fn)` and `this.ignore(evt, fn)` tune in, tune in for one message, and tune out. You can also list listeners in the `listeners` option.
|
|
154
|
+
- `this.prompt(text)` makes a sealed `devacore:prompt` announcement. This is handy for showing messages in a command line or UI.
|
|
155
|
+
|
|
156
|
+
Every logbook line is also announced (`devacore:state`, `devacore:action`, and so on), so one listener can watch everything an office does. The full list of {{ site.data.events.DATA | size }} Core events is on the [Events]({{ "/core/events/" | relative_url }}) page.
|
|
157
|
+
|
|
158
|
+
## What a packet looks like
|
|
159
|
+
|
|
160
|
+
The answer to a `question()` is a **packet**, which is like a sealed envelope holding the question and the answer:
|
|
161
|
+
|
|
162
|
+
```text
|
|
163
|
+
packet: id, q, a, created, finish, complete, md5, sha256, sha512
|
|
164
|
+
q: id, agent, client, meta{key, method, params}, text, data, created, md5, sha256, sha512
|
|
165
|
+
a: id, agent, client, meta{key, method, params}, text, html, data, created, md5, sha256, sha512
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
- `q` is the question and `a` is the answer. Each half has its own seals, and so does the envelope as a whole.
|
|
169
|
+
- `a.text` is usually what you want. `a.meta.key` tells you which specialist answered.
|
|
170
|
+
- `agent` and `client` inside are sealed copies, so you can tell who was involved.
|
|
171
|
+
|
|
172
|
+
## Client features
|
|
173
|
+
|
|
174
|
+
The **client** is who the office works for. Its `features` object holds settings for each client feature: `license`, `error`, `log`, `data`, `report`, `legal`, `security`, `support`, `services`, `systems`. During `init`, each feature's settings are copied into the Deva and removed from the client copy.
|
|
175
|
+
|
|
176
|
+
Afterwards, each feature has a getter with the same name, such as `this.security()` or `this.support()`. It returns a copy of `{id, client_id, client_name, concerns, global, personal, created}`. Here `personal` holds the settings the client gave for this particular Deva (looked up by its agent key). Calling the shared helper with a name that isn't a feature returns `⛔️ INVALID FEATURE`.
|
|
177
|
+
|
|
178
|
+
The full list of {{ site.data.features.DATA | size }} features (including `init`, `agent` and `client`, which label Core work rather than having getters) is on the [Features]({{ "/core/features/" | relative_url }}) page.
|
|
179
|
+
|
|
180
|
+
**For vibe coders:** the client object has to have an entry for every one of those ten features. The easiest way is to start from the Core's own `tests/client.json` and change it carefully.
|
|
181
|
+
|
|
182
|
+
## Child Devas: specialists inside the office
|
|
183
|
+
|
|
184
|
+
Pass other Devas in `devas: {helper}` and they become children. At `init`, each child receives the parent's `events` (the same intercom), `lib` and `config`. At `ready`, the parent starts each child with the same client. Because they share one intercom, the parent can reach a child with `#helper method text`, and anyone can hear both of them.
|
|
185
|
+
|
|
186
|
+
You can also start or stop a child yourself with `this.load(key, client)` and `this.unload(key)`.
|
|
187
|
+
|
|
188
|
+
## When things go wrong: errors
|
|
189
|
+
|
|
190
|
+
All errors go through one door: `this.err(err, packet, reject)`. It writes `error` logbook lines and a `bad` intent, then announces a sealed `devacore:error` packet holding `error: {name, message, stack}` and the related data. Then:
|
|
191
|
+
|
|
192
|
+
- if you wrote `onError(err, packet, reject)`, the Core hands over to you, and **you own the outcome**. Call `reject(err)` if the caller should see a failure, or their promise may wait forever.
|
|
193
|
+
- if you didn't, it calls `reject(err)` itself.
|
|
194
|
+
|
|
195
|
+
Most calls on an office that's closed (not started, failed its license check, or shut down) return `⭕️ OFFLINE` instead of throwing.
|
|
196
|
+
|
|
197
|
+
The standard messages, such as `⭕️ OFFLINE` and `⛔️ ASK TIMEOUT`, are listed on the [Messages]({{ "/core/msgs/" | relative_url }}) page.
|
|
198
|
+
|
|
199
|
+
## Helpers
|
|
200
|
+
|
|
201
|
+
- `this.agent()` and `this.client()` return sealed copies of who the specialist is and who it's working for.
|
|
202
|
+
- `this.info()` and `this.core()` return sealed copies of your package info and the Core's.
|
|
203
|
+
- `this.status()` returns a sentence like `Hello Deva active since Sunday, November 1, 2026 - 7:14:42 PM`.
|
|
204
|
+
- `this.uid()` makes a new fingerprinted id. `this.hash(data, algo)` makes one seal.
|
|
205
|
+
- `this.lib` has small utilities, such as `copy` (a deep copy), `formatDate`, `formatCurrency`, `formatNumber` and `trimWords`.
|
|
206
|
+
- `this.help(msg, dir)` reads sections from `.feecting` help files. Feecting is Quinn's own language.
|
|
207
|
+
|
|
208
|
+
## Closing up: shutdown
|
|
209
|
+
|
|
210
|
+
`await deva.stop()` closes the office. It walks `stop`, `close`, `leave`, `exit` and `shutdown`, announcing each one. `exit` clears the client feature data. `shutdown` tunes out the listeners, cancels any pending asks, and clears `modules`, `listeners`, `events`, `_config` and the active flag. With no hooks, `stop()` resolves with a data object whose `key` is `'shutdown'`. After that, `status()` and most other calls return `⭕️ OFFLINE`.
|
|
211
|
+
|
|
212
|
+
## A safe minimal recipe
|
|
213
|
+
|
|
214
|
+
This is a complete, working two-Deva office. A parent (`office`) has one child (`helper`). We ran it against Core 1.62.92 from inside the Core's repo folder, so the paths point to the repo's own files. In your own project, import `@indra.ai/deva` and your own client file.
|
|
215
|
+
|
|
216
|
+
```javascript
|
|
217
|
+
import Deva from './index.js'; // '@indra.ai/deva' in your project
|
|
218
|
+
import Client from './tests/client.json' with {type: 'json'};
|
|
219
|
+
import pkg from './package.json' with {type: 'json'};
|
|
220
|
+
|
|
221
|
+
const client = Client.DATA; // carries the VLA and an entry for every client feature
|
|
222
|
+
|
|
223
|
+
const helper = new Deva({
|
|
224
|
+
info: {id: 'helper', name: 'Helper Deva', version: '0.0.1', dir: '.', VLA: pkg.VLA},
|
|
225
|
+
agent: {id: 'helper', key: 'helper', prompt: {emoji: '🛠', text: 'helper'}, profile: {name: 'Helper Deva'}},
|
|
226
|
+
config: {hash: {}}, // needed: ready() writes config.hash[agent.key]
|
|
227
|
+
vars: {context: {}}, // needed: context() looks things up here
|
|
228
|
+
methods: {
|
|
229
|
+
shout(packet) {
|
|
230
|
+
return Promise.resolve({text: packet.q.text.toUpperCase()});
|
|
231
|
+
},
|
|
232
|
+
},
|
|
233
|
+
});
|
|
234
|
+
|
|
235
|
+
const office = new Deva({
|
|
236
|
+
info: {id: 'office', name: 'Office Deva', version: '0.0.1', dir: '.', VLA: pkg.VLA},
|
|
237
|
+
agent: {id: 'office', key: 'office', prompt: {emoji: '🏢', text: 'office'}, profile: {name: 'Office Deva'}},
|
|
238
|
+
config: {hash: {}},
|
|
239
|
+
vars: {context: {}},
|
|
240
|
+
devas: {helper}, // the child shares this office's intercom
|
|
241
|
+
listeners: {
|
|
242
|
+
'devacore:error'(packet) {
|
|
243
|
+
console.log('error:', packet.error.message);
|
|
244
|
+
},
|
|
245
|
+
},
|
|
246
|
+
methods: {
|
|
247
|
+
greet(packet) {
|
|
248
|
+
return Promise.resolve({text: `hello ${packet.q.text}`});
|
|
249
|
+
},
|
|
250
|
+
},
|
|
251
|
+
async onReady(data, resolve) { // the office is open: do the work here
|
|
252
|
+
const local = await this.question('/greet world');
|
|
253
|
+
console.log('local:', local.a.text);
|
|
254
|
+
|
|
255
|
+
const asked = await this.question('#helper shout hi there');
|
|
256
|
+
console.log('asked:', asked.a.text, 'from', asked.a.meta.key);
|
|
257
|
+
|
|
258
|
+
const missing = await this.question('/nope');
|
|
259
|
+
console.log('missing:', missing.a.text);
|
|
260
|
+
|
|
261
|
+
const done = await this.stop();
|
|
262
|
+
console.log('stopped:', done.key, '| after:', this.status());
|
|
263
|
+
return resolve(data);
|
|
264
|
+
},
|
|
265
|
+
});
|
|
266
|
+
|
|
267
|
+
office.init(client);
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
What it printed:
|
|
271
|
+
|
|
272
|
+
```text
|
|
273
|
+
local: hello world
|
|
274
|
+
asked: HI THERE from helper
|
|
275
|
+
missing: ⛔️ METHOD NOT FOUND office nope
|
|
276
|
+
stopped: shutdown | after: ⭕️ OFFLINE
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
Why it's "safe":
|
|
280
|
+
|
|
281
|
+
- the work happens inside `onReady`, not after `await init()`;
|
|
282
|
+
- every method returns a Promise;
|
|
283
|
+
- `info`, `config: {hash: {}}` and `vars: {context: {}}` are all present;
|
|
284
|
+
- there's a `devacore:error` listener, so errors are visible;
|
|
285
|
+
- the client is the Core's tested client file, with a matching VLA and every feature filled in.
|
|
286
|
+
|
|
287
|
+
## Practical rules for vibe coding
|
|
288
|
+
|
|
289
|
+
1. **Do the work in `onReady`.** Treat that hook, or the `devacore:ready` event, as "the office is open."
|
|
290
|
+
2. **Every method returns a Promise.** If your AI assistant writes `return 'hi'`, change it to `return Promise.resolve('hi')` or make the method `async`.
|
|
291
|
+
3. **If you write a hook, finish it.** Every `on<Step>` hook must call the next step or `resolve(data)`. A hook that does neither leaves the chain hanging.
|
|
292
|
+
4. **Only use words from the lists.** Before calling `this.state('x')`, check that `x` is on the [States]({{ "/core/states/" | relative_url }}) page (likewise for actions, zones, intents and the rest). A misspelling writes nothing and raises no error.
|
|
293
|
+
5. **Always listen for `devacore:error`.** If you write `onError`, call `reject(err)` in it unless you really mean to swallow the error.
|
|
294
|
+
6. **Start from `tests/client.json`.** Don't let your assistant invent a client object from scratch.
|
|
295
|
+
7. **Use `packet.id.uid` for ids** and `packet.a.text` for answers.
|
|
296
|
+
8. **Watch the logbook while you build.** A listener on `devacore:state` or `devacore:action` that prints `packet.text` shows you what your code is really doing.
|
|
297
|
+
9. **Don't strip out the seals or the logbook calls** to make code "simpler." They're the point of the Core.
|
|
298
|
+
10. **Don't edit the Core's `_data` files or `index.js`.** Add your own zones, actions, states, intents, beliefs or messages through the `agent` option instead. They're merged in without overwriting Core names. And remember the license terms on modification.
|
|
299
|
+
11. **Call `stop()` when you're done**, so listeners and pending asks are cleaned up.
|
|
300
|
+
|
|
301
|
+
## Honest section: real strengths and current limits
|
|
302
|
+
|
|
303
|
+
### Genuine strengths (we checked these)
|
|
304
|
+
|
|
305
|
+
- **Everything leaves a trail.** In our runs, every question, answer, lifecycle step and logbook line was announced on the bus as a sealed record.
|
|
306
|
+
- **Tiered, cumulative seals.** Every packet, half-packet and record we inspected carried md5, sha256 and sha512, and each tier covers the ones before it.
|
|
307
|
+
- **Rich ids.** Each id ties the record to the license, client, agent, machine and Core version.
|
|
308
|
+
- **Clean asking between Devas.** `#key method` worked between parent and child. Asking a missing Deva failed fast with a clear message, and there's a timeout for silent ones.
|
|
309
|
+
- **Tidy shutdown.** `stop()` ran the whole chain and left the Deva answering `⭕️ OFFLINE`.
|
|
310
|
+
- **Small and self-contained.** One class, no runtime dependencies.
|
|
311
|
+
|
|
312
|
+
### Current limits (true at version 1.62.92)
|
|
313
|
+
|
|
314
|
+
- **`init()` resolves too early. A fix is planned for 1.63.** Right now the `init()` promise resolves with `undefined` as soon as the client step finishes, before `start`, `enter`, `done` and `ready` have run. In our recipe, `init resolved with: undefined` printed before `onReady` had done any work. Until the fix ships, wait for `onReady` or `devacore:ready`, and don't trust the `init` promise as a "ready" signal.
|
|
315
|
+
- **Errors during the client feature chain don't stop start-up.** Because of the same early resolve, if the client object is missing feature settings, each feature step announces a `devacore:error` (in our test: `Cannot read properties of undefined (reading 'license')`, and the same for the others), but `init` has already resolved and the Deva still reaches `onReady`. Listen for `devacore:error` so you notice.
|
|
316
|
+
- **Unknown names are silent.** A name that isn't in `_data` (or your agent's additions) makes `feature`, `zone`, `action`, `state`, `intent` and `belief` do nothing at all. That keeps the vocabulary strict, but a typo, or a name removed from `_data` in a later version, can quietly drop logbook lines. Check the lists after upgrading.
|
|
317
|
+
- **`npm test` has no assertions yet.** It runs a Deva through its lifecycle and passes as long as nothing throws. Assertion tests are planned. Until then, "tests pass" means "it didn't crash," not "it did the right thing."
|
|
318
|
+
- **The license-failure prompt isn't heard.** `init` calls `prompt()` with the license failure message, but the Deva isn't active yet, so no `devacore:prompt` is announced (we counted zero). Check the value `init` resolves with instead.
|
|
319
|
+
|
|
320
|
+
### Where documentation says more than the code does
|
|
321
|
+
|
|
322
|
+
At 1.62.92, these places in the docs don't match what the code does:
|
|
323
|
+
|
|
324
|
+
- The README's start-up section says a license mismatch resolves with `❌ The Provided Client License Is Invalid`. The code resolves with `❌ Invalid VLA Check` (or `❌ Bad Personal VLA` when there's no VLA).
|
|
325
|
+
- The README's method table says `license_check` returns "stamped approval or `false`." On failure it actually returns one of the message strings above, never `false`.
|
|
326
|
+
- The README says the feature chain stores settings "for each one that the client's `features` object defines." In fact every feature is expected, and a missing one raises an error (see above).
|
|
327
|
+
- The Events page says `devacore:finish` and `devacore:complete` close out a question asked of *another* Deva. They also fire for local `/command` answers.
|
|
328
|
+
|
|
329
|
+
## Questions to ask before relying on it
|
|
330
|
+
|
|
331
|
+
Ask these yourself, or paste them to your AI assistant:
|
|
332
|
+
|
|
333
|
+
- [ ] Have I read `LICENSE.md`, and is my use allowed under it (location, commercial use, modification)?
|
|
334
|
+
- [ ] Does my client object carry the VLA that matches the Core's `package.json`, and an entry for every client feature?
|
|
335
|
+
- [ ] Is all my real work inside `onReady` (or after `devacore:ready`), not after `await init()`?
|
|
336
|
+
- [ ] Does every method return a Promise, and does every hook call the next step or `resolve`?
|
|
337
|
+
- [ ] Is every feature, zone, action, state, intent and belief name I use actually on its list?
|
|
338
|
+
- [ ] Do I have a `devacore:error` listener, and does my `onError` (if any) call `reject`?
|
|
339
|
+
- [ ] Do I use `packet.id.uid` for ids?
|
|
340
|
+
- [ ] Have I checked the logbook output once by eye, to see it's recording what I expect?
|
|
341
|
+
- [ ] Do I have my own checks of the results, since `npm test` doesn't assert anything yet?
|
|
342
|
+
- [ ] After upgrading the Core, have I rechecked the lists and the changelog for renamed or removed names?
|
|
343
|
+
- [ ] Do I call `stop()` when finished?
|
|
344
|
+
|
|
345
|
+
## Glossary
|
|
346
|
+
|
|
347
|
+
- **Deva**: one specialist in the office. An instance of the `Deva` class with its own agent, methods and listeners.
|
|
348
|
+
- **Deva Core**: the `@indra.ai/deva` package. The single class every Deva is built from.
|
|
349
|
+
- **Agent**: who the Deva is: its `key` (name on the intercom), profile and prompt. `this.agent()` returns a sealed copy.
|
|
350
|
+
- **Client**: who the Deva works for. Carries the VLA and the client feature settings. `this.client()` returns a sealed copy.
|
|
351
|
+
- **Method**: a job a Deva can do, reached with `/name` or `#key name`. Returns a Promise.
|
|
352
|
+
- **Listener**: a function that runs when a certain announcement is heard.
|
|
353
|
+
- **Event bus**: the shared intercom (`this.events`, a Node.js EventEmitter). Core announcements start with `devacore:`.
|
|
354
|
+
- **talk / listen / ask**: make an announcement, tune in, and ask another Deva for an answer.
|
|
355
|
+
- **Packet**: the sealed envelope returned by `question()`, holding `q` (question) and `a` (answer).
|
|
356
|
+
- **Feature**: which part of the business a step belongs to, such as security or support. Client features also have getters.
|
|
357
|
+
- **Zone**: where in the office a step happens.
|
|
358
|
+
- **Action**: what was done.
|
|
359
|
+
- **State**: the condition the work is in.
|
|
360
|
+
- **Intent**: the purpose or outcome, such as good or bad.
|
|
361
|
+
- **Belief**: the stance the work is recorded under: vedic, american or other.
|
|
362
|
+
- **Context**: a free-form note about what's going on, labeled from your `vars.context`.
|
|
363
|
+
- **Diary labels / logbook**: the feature, zone, action, state, intent and belief lines every step writes and announces.
|
|
364
|
+
- **Hash / seal**: a short code computed from data. It changes completely if the data changes.
|
|
365
|
+
- **Hash tiers**: the three cumulative seals, md5, sha256 and sha512, each covering the ones before it.
|
|
366
|
+
- **Fingerprint**: a sha256 seal inside every id that combines the license, client, agent, machine and Core.
|
|
367
|
+
- **uid**: the id object made by `this.uid()`. Its `uid` field is the id value.
|
|
368
|
+
- **VLA**: the Vedic License Agreement. Also the license object a client must carry for a Deva to start.
|
|
369
|
+
- **license_check**: the start-up check that the client's VLA matches the Core's.
|
|
370
|
+
- **Invoke chain**: the named steps (start, enter, done, ready, and so on) a Deva walks through, each with an optional `on<Step>` hook.
|
|
371
|
+
- **Hook**: your own function for a step, such as `onReady`, which decides what happens next.
|
|
372
|
+
- **Child Deva**: a Deva listed in another's `devas`. It shares the parent's intercom, `lib` and `config` and starts at the parent's `ready`.
|
|
373
|
+
- **OFFLINE**: the `⭕️ OFFLINE` answer from a Deva that isn't running.
|
|
374
|
+
|
|
375
|
+
---
|
|
376
|
+
|
|
377
|
+
Copyright ©2000-2026 Quinn Arjuna America Michaels; All rights reserved.
|