@indra.ai/deva 1.64.56 → 1.64.92
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/_config.yml +2 -2
- package/_data/guide.json +119 -0
- package/_data/msgs.json +4 -0
- package/_includes/header.html +1 -1
- package/guide/index.md +47 -0
- package/guide/step-1.md +99 -0
- package/guide/step-2.md +253 -0
- package/guide/step-3.md +159 -0
- package/guide/step-4.md +173 -0
- package/guide/step-5.md +222 -0
- package/guide/step-6.md +281 -0
- package/guide/step-7.md +247 -0
- package/guide/troubleshooting.md +116 -0
- package/index.js +2305 -2295
- package/package.json +1 -1
- package/tests/client.json +1 -0
- package/tests/index.js +3 -3
- package/tests/suite/01-init.test.js +3 -3
- package/tests/suite/09-ready-hash.test.js +1 -1
- package/vibe.md +2 -2
package/guide/step-6.md
ADDED
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
---
|
|
2
|
+
layout: page
|
|
3
|
+
title: "Step 6: Bring it to life"
|
|
4
|
+
permalink: /guide/step-6/
|
|
5
|
+
description: Call init(client), watch the Deva reach ready, ask it a question, and read the stamped packet that comes back.
|
|
6
|
+
image: /assets/banner.png
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
{% assign guide = site.data.guide.DATA %}
|
|
10
|
+
{% assign step = guide.steps | where: "step", 6 | first %}
|
|
11
|
+
{% assign next = guide.steps | where: "step", 7 | first %}
|
|
12
|
+
|
|
13
|
+
{{ step.describe }}
|
|
14
|
+
|
|
15
|
+
In Step 5 your Deva had its skills, but it was still offline. In this step you'll start it with `init(client)`. When it reaches ready, it will answer `/hello Quinn` with the method and func you wrote, your listener will hear the question, and you'll check the three hashes stamped on the answer.
|
|
16
|
+
|
|
17
|
+
This step needs `{{ guide.package }}` version 1.64.70 or newer. To see which version you have installed, run:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm ls {{ guide.package }}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 1. Give the client a profile id
|
|
24
|
+
|
|
25
|
+
Open `data/client.json` and add an `id` as the first entry in `profile`. Use the same value as the client's `DATA.id`:
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
"profile": {
|
|
29
|
+
"id": "00000000000000000001",
|
|
30
|
+
"name": "You",
|
|
31
|
+
"fullname": "Your Full Name",
|
|
32
|
+
"email": "you@example.com",
|
|
33
|
+
"company": "Your Company",
|
|
34
|
+
"describe": "The person talking to Hello Deva.",
|
|
35
|
+
"lang": "en",
|
|
36
|
+
"locale": "en-US",
|
|
37
|
+
"currency": "USD"
|
|
38
|
+
},
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The client's id now lives in two places, and each place has its own job:
|
|
42
|
+
|
|
43
|
+
- **`DATA.id`** is the id the Deva uses when it checks the client's data.
|
|
44
|
+
- **`DATA.profile.id`** travels with the client inside its profile. When a packet is signed, the signature's token is built from the client's profile, including this id. In the custom Devas you'll build later, this same id is the one that matches the Deva's VLA uid.
|
|
45
|
+
|
|
46
|
+
Nothing in this step reads the profile id yet, so you won't see it in the output. Adding it now means your client file is complete before the Deva starts.
|
|
47
|
+
|
|
48
|
+
## 2. Two licenses, two checks
|
|
49
|
+
|
|
50
|
+
You now have two VLAs in play. They do different jobs, so keep them separate:
|
|
51
|
+
|
|
52
|
+
- **The client's VLA** is `DATA.VLA` in `client.json`. The core checks it the moment you call `init(client)`, by comparing it with the VLA that ships with Deva Core. If they match, the client gets access to the core and the Deva starts. If they don't, the Deva stays offline.
|
|
53
|
+
- **The agent's VLA** is `Agent.VLA`, which you put into `info` in Step 4. Starting the Deva doesn't check it. It belongs to the Deva itself, and custom Devas compare it later, in their own `onInit`, when something accesses them. Your Hello Deva doesn't do that comparison.
|
|
54
|
+
|
|
55
|
+
## 3. What happens when you call init(client)
|
|
56
|
+
|
|
57
|
+
`init(client)` returns a Promise. Between the call and ready, the core does this, in order:
|
|
58
|
+
|
|
59
|
+
1. It checks the client's VLA, as described above.
|
|
60
|
+
2. It marks the Deva active, so `status()` stops answering `⭕️ OFFLINE`.
|
|
61
|
+
3. It binds your func, methods and listeners to the Deva, so `this` inside them is the Deva, and it connects your listeners to the event bus. This is the start-up that Step 5 told you about.
|
|
62
|
+
4. It reads the client's `features`, the block you wrote in Step 2.
|
|
63
|
+
5. It runs the start-up steps `start`, `enter`, `done` and `ready`, one after another.
|
|
64
|
+
|
|
65
|
+
**Ready** is the last start-up step. It means the Deva is fully started: it's active, its skills are bound, its listeners are connected, and it can answer questions. If you add an `onReady` hook, the core calls it at ready, and `init()` doesn't finish until the hook calls `resolve(data)`. That makes `onReady` the right place to do the Deva's first piece of work.
|
|
66
|
+
|
|
67
|
+
## 4. Add onReady
|
|
68
|
+
|
|
69
|
+
Add `onReady` to `new Deva()`, right after the `listeners` block:
|
|
70
|
+
|
|
71
|
+
```javascript
|
|
72
|
+
onReady(data, resolve) {
|
|
73
|
+
const {key} = this.agent();
|
|
74
|
+
console.log(this.status());
|
|
75
|
+
console.log('ready hash:', this._config.hash[key]);
|
|
76
|
+
this.question('/hello Quinn').then(packet => {
|
|
77
|
+
console.log('answer:', packet.a.text);
|
|
78
|
+
console.log('md5:', packet.md5);
|
|
79
|
+
console.log('sha256:', packet.sha256);
|
|
80
|
+
console.log('sha512:', packet.sha512);
|
|
81
|
+
|
|
82
|
+
const check = this.lib.copy(packet);
|
|
83
|
+
for (const algo of ['md5', 'sha256', 'sha512']) delete check[algo];
|
|
84
|
+
for (const algo of ['md5', 'sha256', 'sha512']) {
|
|
85
|
+
check[algo] = this.hash(check, algo);
|
|
86
|
+
console.log(`${algo} matches:`, check[algo] === packet[algo]);
|
|
87
|
+
}
|
|
88
|
+
return resolve(data);
|
|
89
|
+
});
|
|
90
|
+
},
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The next three sections explain what each part does.
|
|
94
|
+
|
|
95
|
+
## 5. The ready hash
|
|
96
|
+
|
|
97
|
+
At ready, the core takes a sha256 hash of each of these parts of the Deva: `vars`, `utils`, `listeners`, `modules`, `func` and `methods`. For `func`, `methods`, `listeners` and `utils`, it hashes the source code of your functions as you wrote them. It stores the results under the agent's key, which is why the code reads `this._config.hash[key]`.
|
|
98
|
+
|
|
99
|
+
The ready hash is a **runtime marker**. It records what the Deva's skills looked like at the moment it became ready, so a later change can be detected by comparing against it. It is **not** an identity. Two Devas with exactly the same functions get exactly the same ready hash, and that is intended.
|
|
100
|
+
|
|
101
|
+
Anything added after ready isn't part of the ready hash. That's deliberate: the marker describes the Deva as it started.
|
|
102
|
+
|
|
103
|
+
Because the hash comes from your source code and vars, it stays the same every time you run the file. It changes only when you change one of those parts, even by a single space.
|
|
104
|
+
|
|
105
|
+
## 6. Ask a question
|
|
106
|
+
|
|
107
|
+
`this.question('/hello Quinn')` asks your Deva a question. The `/` at the start means "run my own method", so the core runs `methods.hello` with `Quinn` as `packet.q.text`. Along the way:
|
|
108
|
+
|
|
109
|
+
- The core sends the `devacore:question` event, so your listener prints `👂 heard: Quinn`.
|
|
110
|
+
- Your method calls your func, and the answer's text is `Hello World, and hello to Quinn.`
|
|
111
|
+
|
|
112
|
+
`question()` returns a Promise of the finished packet. The question is in `packet.q` and the answer is in `packet.a`.
|
|
113
|
+
|
|
114
|
+
## 7. Read and check the stamps
|
|
115
|
+
|
|
116
|
+
Every packet is stamped with three hashes: `md5`, `sha256` and `sha512`. Each hash is a base64 digest of the packet written out as JSON. The question (`packet.q`) and the answer (`packet.a`) each carry their own three stamps, and the whole packet carries three more. The code prints the whole packet's stamps.
|
|
117
|
+
|
|
118
|
+
The three tiers are deliberate, and each has its own use:
|
|
119
|
+
|
|
120
|
+
- **md5** is the fast, everyday check, for civilian verification.
|
|
121
|
+
- **sha256** is the stronger check, for government and authority verification.
|
|
122
|
+
- **sha512** is the strongest check, for military, agency and legal high-security use.
|
|
123
|
+
|
|
124
|
+
The stamps are added in that order, and each one covers the ones before it. md5 is taken over the packet. sha256 is taken over the packet with md5 already in it. sha512 is taken over the packet with md5 and sha256 already in it.
|
|
125
|
+
|
|
126
|
+
The second half of `onReady` checks the stamps the same way. It makes a clean copy of the packet with `this.lib.copy()`, removes the three stamps from the copy, and then rebuilds them one at a time in the same order with `this.hash()`. If the packet hasn't been changed since it was stamped, all three match.
|
|
127
|
+
|
|
128
|
+
Every packet has its own ids and times, so these hashes are different on every run. That's expected.
|
|
129
|
+
|
|
130
|
+
## 8. Start the Deva
|
|
131
|
+
|
|
132
|
+
Replace the six `console.log` lines at the bottom of the Step 5 file with these:
|
|
133
|
+
|
|
134
|
+
```javascript
|
|
135
|
+
console.log(hello.status());
|
|
136
|
+
await hello.init(client);
|
|
137
|
+
console.log(hello.status());
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The first line shows the Deva is offline before it starts. `await hello.init(client)` starts it and waits until `onReady` calls `resolve(data)`. The last line shows it's still active afterward.
|
|
141
|
+
|
|
142
|
+
## The whole file
|
|
143
|
+
|
|
144
|
+
```javascript
|
|
145
|
+
import Deva from '{{ guide.package }}';
|
|
146
|
+
import pkg from './package.json' with {type:'json'};
|
|
147
|
+
import Agent from './data/agent.json' with {type:'json'};
|
|
148
|
+
import Client from './data/client.json' with {type:'json'};
|
|
149
|
+
|
|
150
|
+
const agent = Agent.DATA;
|
|
151
|
+
const client = Client.DATA;
|
|
152
|
+
|
|
153
|
+
const info = {
|
|
154
|
+
id: pkg.id,
|
|
155
|
+
name: pkg.name,
|
|
156
|
+
describe: pkg.description,
|
|
157
|
+
version: pkg.version,
|
|
158
|
+
copyright: pkg.copyright,
|
|
159
|
+
dir: import.meta.dirname,
|
|
160
|
+
VLA: Agent.VLA,
|
|
161
|
+
};
|
|
162
|
+
|
|
163
|
+
const hello = new Deva({
|
|
164
|
+
info,
|
|
165
|
+
agent: {
|
|
166
|
+
id: agent.id,
|
|
167
|
+
key: agent.key,
|
|
168
|
+
prompt: agent.prompt,
|
|
169
|
+
profile: agent.profile,
|
|
170
|
+
},
|
|
171
|
+
vars: agent.vars,
|
|
172
|
+
func: {
|
|
173
|
+
greet(name) {
|
|
174
|
+
if (!name) return `${this.vars.greeting}.`;
|
|
175
|
+
return `${this.vars.greeting}, and hello to ${name}.`;
|
|
176
|
+
},
|
|
177
|
+
},
|
|
178
|
+
methods: {
|
|
179
|
+
hello(packet) {
|
|
180
|
+
this.context('hello', packet.q.text);
|
|
181
|
+
return new Promise(resolve => {
|
|
182
|
+
const text = this.func.greet(packet.q.text);
|
|
183
|
+
return resolve({
|
|
184
|
+
text,
|
|
185
|
+
html: `<p>${text}</p>`,
|
|
186
|
+
data: {
|
|
187
|
+
greeting: this.vars.greeting,
|
|
188
|
+
name: packet.q.text,
|
|
189
|
+
},
|
|
190
|
+
});
|
|
191
|
+
});
|
|
192
|
+
},
|
|
193
|
+
},
|
|
194
|
+
listeners: {
|
|
195
|
+
'devacore:question'(packet) {
|
|
196
|
+
console.log(`👂 heard: ${packet.q.text}`);
|
|
197
|
+
},
|
|
198
|
+
},
|
|
199
|
+
onReady(data, resolve) {
|
|
200
|
+
const {key} = this.agent();
|
|
201
|
+
console.log(this.status());
|
|
202
|
+
console.log('ready hash:', this._config.hash[key]);
|
|
203
|
+
this.question('/hello Quinn').then(packet => {
|
|
204
|
+
console.log('answer:', packet.a.text);
|
|
205
|
+
console.log('md5:', packet.md5);
|
|
206
|
+
console.log('sha256:', packet.sha256);
|
|
207
|
+
console.log('sha512:', packet.sha512);
|
|
208
|
+
|
|
209
|
+
const check = this.lib.copy(packet);
|
|
210
|
+
for (const algo of ['md5', 'sha256', 'sha512']) delete check[algo];
|
|
211
|
+
for (const algo of ['md5', 'sha256', 'sha512']) {
|
|
212
|
+
check[algo] = this.hash(check, algo);
|
|
213
|
+
console.log(`${algo} matches:`, check[algo] === packet[algo]);
|
|
214
|
+
}
|
|
215
|
+
return resolve(data);
|
|
216
|
+
});
|
|
217
|
+
},
|
|
218
|
+
});
|
|
219
|
+
|
|
220
|
+
console.log(hello.status());
|
|
221
|
+
await hello.init(client);
|
|
222
|
+
console.log(hello.status());
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Run it:
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
{{ guide.run }}
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
You should see something like this:
|
|
232
|
+
|
|
233
|
+
```
|
|
234
|
+
⭕️ OFFLINE
|
|
235
|
+
Hello Deva active since Friday, November 13, 2026 - 9:42:47 PM
|
|
236
|
+
ready hash: {
|
|
237
|
+
vars: 'rDSWWf9z7T32eW+iR+hmpovAlKg00WLgPZHL5lX8Jiw=',
|
|
238
|
+
utils: 'RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=',
|
|
239
|
+
listeners: 'ai+uM2sU+GbXlo68vVrH8JGVJ8rkSiBm5DI//ggURGg=',
|
|
240
|
+
modules: 'RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=',
|
|
241
|
+
func: 'OjSeCqlVjcdUbiGmeGrNh5Hv90nk+nQ6KCxTUjR3+FI=',
|
|
242
|
+
methods: '2YKySno+VMvwOxFVjNfhq7IOROUVA6sDqadLWSanDps='
|
|
243
|
+
}
|
|
244
|
+
👂 heard: Quinn
|
|
245
|
+
answer: Hello World, and hello to Quinn.
|
|
246
|
+
md5: Q7x+PAHoCAhSd906szu7tg==
|
|
247
|
+
sha256: vPMMSg4EEQ+6spWyx7mBshcAA/j0jM6MckHlabHyQpQ=
|
|
248
|
+
sha512: uSlWv/ndZ9M+2TQiuQKvTMCyGh57NbvFrH9EbwiWQ6WqaogQD0TQcyPzR/YYo5HWpLAD8CES7r5AZnprgB49Vg==
|
|
249
|
+
md5 matches: true
|
|
250
|
+
sha256 matches: true
|
|
251
|
+
sha512 matches: true
|
|
252
|
+
Hello Deva active since Friday, November 13, 2026 - 9:42:47 PM
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Some of this will be different for you:
|
|
256
|
+
|
|
257
|
+
- **The date and time** after `active since` are when you started the Deva.
|
|
258
|
+
- **The md5, sha256 and sha512 values** change on every run, because every packet has its own ids and times.
|
|
259
|
+
- **The ready hash** stays the same from run to run. It matches the values above only if your vars and your func, methods and listeners are exactly the same as on this page, down to the spacing. `utils` and `modules` show the same value because both are empty.
|
|
260
|
+
|
|
261
|
+
These lines should always be the same: `⭕️ OFFLINE` first, `👂 heard: Quinn`, `answer: Hello World, and hello to Quinn.`, and `true` on all three `matches` lines.
|
|
262
|
+
|
|
263
|
+
## If something goes wrong
|
|
264
|
+
|
|
265
|
+
| You see | What it means |
|
|
266
|
+
|---|---|
|
|
267
|
+
| `Cannot read properties of undefined (reading 'hash')` | Your installed `{{ guide.package }}` is older than 1.64.70. This step needs version 1.64.70 or newer. Check with `npm ls {{ guide.package }}`. |
|
|
268
|
+
| `Cannot create property 'created' on boolean 'false'` | `info` is missing from `new Deva()`. Make sure `info,` is the first entry. |
|
|
269
|
+
| `Cannot read properties of undefined (reading 'warning')` | `agent` is the whole agent file instead of what's inside it. It should be `const agent = Agent.DATA;`. |
|
|
270
|
+
| Only two `⭕️ OFFLINE` lines, and nothing else | The client's VLA didn't pass the check at `init(client)`, so the Deva never started. To see why, change the line to `console.log(await hello.init(client));`. `❌ Bad Personal VLA` means the client file has no `VLA`. `❌ Invalid VLA Check` means the client's VLA doesn't exactly match the one that ships with Deva Core. Copy it again as shown in Step 2. |
|
|
271
|
+
| The program ends without `👂 heard: Quinn` or `answer:` | `onReady` is missing or misspelled. It must be named exactly `onReady`. |
|
|
272
|
+
| A `matches` line says `false` | The packet was changed after it was stamped, or the stamps were rebuilt in a different order. Rebuild them in the order md5, sha256, sha512. |
|
|
273
|
+
|
|
274
|
+
## What you did
|
|
275
|
+
|
|
276
|
+
{% for item in step.learn %}- {{ item }}
|
|
277
|
+
{% endfor %}
|
|
278
|
+
|
|
279
|
+
## Next
|
|
280
|
+
|
|
281
|
+
In **[Step {{ next.step }}: {{ next.title }}]({{ next.permalink }})** you'll stop the Deva cleanly with `stop()` and see what it answers once it's offline.
|
package/guide/step-7.md
ADDED
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
---
|
|
2
|
+
layout: page
|
|
3
|
+
title: "Step 7: Shut it down"
|
|
4
|
+
permalink: /guide/step-7/
|
|
5
|
+
description: Stop the Deva cleanly with stop() and see what it answers once it is offline.
|
|
6
|
+
image: /assets/banner.png
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
{% assign guide = site.data.guide.DATA %}
|
|
10
|
+
{% assign step = guide.steps | where: "step", 7 | first %}
|
|
11
|
+
{% assign life = guide.steps | where: "step", 6 | first %}
|
|
12
|
+
|
|
13
|
+
{{ step.describe }}
|
|
14
|
+
|
|
15
|
+
In Step {{ life.step }} your Deva started, answered `/hello Quinn`, and handed back a stamped packet. A Deva that starts cleanly should also stop cleanly. In this step you'll stop {{ guide.deva }} with `stop()`, add a hook that runs as it stops, and check three things afterward: it reports offline, its listeners are off the event bus, and it answers questions with `⭕️ OFFLINE`.
|
|
16
|
+
|
|
17
|
+
Like Step {{ life.step }}, this step needs `{{ guide.package }}` version 1.64.70 or newer.
|
|
18
|
+
|
|
19
|
+
## 1. What stop() does
|
|
20
|
+
|
|
21
|
+
`stop()` takes no arguments and returns a Promise. It runs five shutdown steps, one after another:
|
|
22
|
+
|
|
23
|
+
1. **stop** collects the agent and client hashes into a stop record.
|
|
24
|
+
2. **close** comes next.
|
|
25
|
+
3. **leave** comes after that.
|
|
26
|
+
4. **exit** clears the client's feature data, which the Deva read from your client file's `features` block when it started.
|
|
27
|
+
5. **shutdown** takes every listener this Deva put on the event bus off the bus, answers any question still waiting for another Deva with `⭕️ OFFLINE`, and marks the Deva inactive. It also clears its `modules`, `listeners`, `events` and config.
|
|
28
|
+
|
|
29
|
+
Each step writes its own time into the stop record, re-stamps the record with md5, sha256 and sha512, and sends its own event, from `devacore:stop` through `devacore:shutdown`. When the last step is done, `stop()` resolves with the record. The record's `key` is `shutdown`, the name of the last step.
|
|
30
|
+
|
|
31
|
+
If any child Devas are loaded, `stop()` stops them first, so none are left running. {{ guide.deva }} has none.
|
|
32
|
+
|
|
33
|
+
## 2. Add an onStop hook
|
|
34
|
+
|
|
35
|
+
Each shutdown step has a hook, just like `onReady` at start-up: `onStop`, `onClose`, `onLeave`, `onExit` and `onShutdown`. A hook is optional. If you add one, the core calls it with `(data, resolve)` and the hook decides what happens next.
|
|
36
|
+
|
|
37
|
+
Add `onStop` to `new Deva()`, right after `onReady`:
|
|
38
|
+
|
|
39
|
+
```javascript
|
|
40
|
+
onStop(data, resolve) {
|
|
41
|
+
console.log('stopping:', this.status());
|
|
42
|
+
return this.close(data, resolve);
|
|
43
|
+
},
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`onStop` runs at the very start of the shutdown, while the Deva is still active, so `this.status()` still says it's active. This is the place for your own clean-up, such as closing a database connection.
|
|
47
|
+
|
|
48
|
+
`return this.close(data, resolve);` hands the shutdown on to the next step. This line matters. A hook replaces the core's own move to the next step, so if `onStop` doesn't call `this.close(data, resolve)`, the shutdown stops there and the Deva stays active. The other hooks work the same way: `onClose` calls `this.leave(data, resolve)`, `onLeave` calls `this.exit(data, resolve)`, `onExit` calls `this.shutdown(data, resolve)`, and `onShutdown` ends with `resolve(data)`. By the time `onShutdown` runs, the Deva is already inactive.
|
|
49
|
+
|
|
50
|
+
## 3. Stop the Deva and check it
|
|
51
|
+
|
|
52
|
+
Add these lines at the bottom of the file, after the last `console.log(hello.status());`:
|
|
53
|
+
|
|
54
|
+
```javascript
|
|
55
|
+
const bus = hello.events;
|
|
56
|
+
console.log('on the bus:', bus.eventNames().length);
|
|
57
|
+
console.log('question listeners:', bus.listenerCount('devacore:question'));
|
|
58
|
+
|
|
59
|
+
const stopped = await hello.stop();
|
|
60
|
+
console.log('stopped:', stopped.key);
|
|
61
|
+
console.log(hello.status());
|
|
62
|
+
console.log('on the bus:', bus.eventNames().length);
|
|
63
|
+
console.log('question listeners:', bus.listenerCount('devacore:question'));
|
|
64
|
+
console.log('talk:', hello.talk('devacore:question'));
|
|
65
|
+
console.log('answer:', await hello.question('/hello Quinn'));
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Here's what each part does:
|
|
69
|
+
|
|
70
|
+
- **`const bus = hello.events;`** keeps a reference to the Deva's event bus. Shutdown sets `hello.events` to `false`, so you need this reference to look at the bus afterward.
|
|
71
|
+
- **`bus.eventNames().length`** counts the events that have a listener on the bus. Before the stop, that's your `devacore:question` listener plus the listeners the core added for the Deva's own states when it started.
|
|
72
|
+
- **`bus.listenerCount('devacore:question')`** counts the listeners on the event you added in Step 5. It's `1` while the Deva runs.
|
|
73
|
+
- **`await hello.stop()`** runs the five shutdown steps. `stopped.key` shows the last step that ran.
|
|
74
|
+
- **After the stop**, `hello.status()` answers `⭕️ OFFLINE`, and both counts are `0` because every listener is off the bus.
|
|
75
|
+
- **`hello.talk('devacore:question')`** answers `⭕️ OFFLINE`. A stopped Deva has no event bus, so it can't send events. `listen()`, `once()` and `ignore()` answer the same way after a stop.
|
|
76
|
+
- **`/hello Quinn`** answers `⭕️ OFFLINE`, because a stopped Deva doesn't answer questions.
|
|
77
|
+
|
|
78
|
+
## The whole file
|
|
79
|
+
|
|
80
|
+
```javascript
|
|
81
|
+
import Deva from '{{ guide.package }}';
|
|
82
|
+
import pkg from './package.json' with {type:'json'};
|
|
83
|
+
import Agent from './data/agent.json' with {type:'json'};
|
|
84
|
+
import Client from './data/client.json' with {type:'json'};
|
|
85
|
+
|
|
86
|
+
const agent = Agent.DATA;
|
|
87
|
+
const client = Client.DATA;
|
|
88
|
+
|
|
89
|
+
const info = {
|
|
90
|
+
id: pkg.id,
|
|
91
|
+
name: pkg.name,
|
|
92
|
+
describe: pkg.description,
|
|
93
|
+
version: pkg.version,
|
|
94
|
+
copyright: pkg.copyright,
|
|
95
|
+
dir: import.meta.dirname,
|
|
96
|
+
VLA: Agent.VLA,
|
|
97
|
+
};
|
|
98
|
+
|
|
99
|
+
const hello = new Deva({
|
|
100
|
+
info,
|
|
101
|
+
agent: {
|
|
102
|
+
id: agent.id,
|
|
103
|
+
key: agent.key,
|
|
104
|
+
prompt: agent.prompt,
|
|
105
|
+
profile: agent.profile,
|
|
106
|
+
},
|
|
107
|
+
vars: agent.vars,
|
|
108
|
+
func: {
|
|
109
|
+
greet(name) {
|
|
110
|
+
if (!name) return `${this.vars.greeting}.`;
|
|
111
|
+
return `${this.vars.greeting}, and hello to ${name}.`;
|
|
112
|
+
},
|
|
113
|
+
},
|
|
114
|
+
methods: {
|
|
115
|
+
hello(packet) {
|
|
116
|
+
this.context('hello', packet.q.text);
|
|
117
|
+
return new Promise(resolve => {
|
|
118
|
+
const text = this.func.greet(packet.q.text);
|
|
119
|
+
return resolve({
|
|
120
|
+
text,
|
|
121
|
+
html: `<p>${text}</p>`,
|
|
122
|
+
data: {
|
|
123
|
+
greeting: this.vars.greeting,
|
|
124
|
+
name: packet.q.text,
|
|
125
|
+
},
|
|
126
|
+
});
|
|
127
|
+
});
|
|
128
|
+
},
|
|
129
|
+
},
|
|
130
|
+
listeners: {
|
|
131
|
+
'devacore:question'(packet) {
|
|
132
|
+
console.log(`👂 heard: ${packet.q.text}`);
|
|
133
|
+
},
|
|
134
|
+
},
|
|
135
|
+
onReady(data, resolve) {
|
|
136
|
+
const {key} = this.agent();
|
|
137
|
+
console.log(this.status());
|
|
138
|
+
console.log('ready hash:', this._config.hash[key]);
|
|
139
|
+
this.question('/hello Quinn').then(packet => {
|
|
140
|
+
console.log('answer:', packet.a.text);
|
|
141
|
+
console.log('md5:', packet.md5);
|
|
142
|
+
console.log('sha256:', packet.sha256);
|
|
143
|
+
console.log('sha512:', packet.sha512);
|
|
144
|
+
|
|
145
|
+
const check = this.lib.copy(packet);
|
|
146
|
+
for (const algo of ['md5', 'sha256', 'sha512']) delete check[algo];
|
|
147
|
+
for (const algo of ['md5', 'sha256', 'sha512']) {
|
|
148
|
+
check[algo] = this.hash(check, algo);
|
|
149
|
+
console.log(`${algo} matches:`, check[algo] === packet[algo]);
|
|
150
|
+
}
|
|
151
|
+
return resolve(data);
|
|
152
|
+
});
|
|
153
|
+
},
|
|
154
|
+
onStop(data, resolve) {
|
|
155
|
+
console.log('stopping:', this.status());
|
|
156
|
+
return this.close(data, resolve);
|
|
157
|
+
},
|
|
158
|
+
});
|
|
159
|
+
|
|
160
|
+
console.log(hello.status());
|
|
161
|
+
await hello.init(client);
|
|
162
|
+
console.log(hello.status());
|
|
163
|
+
|
|
164
|
+
const bus = hello.events;
|
|
165
|
+
console.log('on the bus:', bus.eventNames().length);
|
|
166
|
+
console.log('question listeners:', bus.listenerCount('devacore:question'));
|
|
167
|
+
|
|
168
|
+
const stopped = await hello.stop();
|
|
169
|
+
console.log('stopped:', stopped.key);
|
|
170
|
+
console.log(hello.status());
|
|
171
|
+
console.log('on the bus:', bus.eventNames().length);
|
|
172
|
+
console.log('question listeners:', bus.listenerCount('devacore:question'));
|
|
173
|
+
console.log('talk:', hello.talk('devacore:question'));
|
|
174
|
+
console.log('answer:', await hello.question('/hello Quinn'));
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Run it:
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
{{ guide.run }}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
You should see something like this:
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
⭕️ OFFLINE
|
|
187
|
+
Hello Deva active since Saturday, November 14, 2026 - 9:26:59 AM
|
|
188
|
+
ready hash: {
|
|
189
|
+
vars: 'rDSWWf9z7T32eW+iR+hmpovAlKg00WLgPZHL5lX8Jiw=',
|
|
190
|
+
utils: 'RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=',
|
|
191
|
+
listeners: 'ai+uM2sU+GbXlo68vVrH8JGVJ8rkSiBm5DI//ggURGg=',
|
|
192
|
+
modules: 'RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=',
|
|
193
|
+
func: 'OjSeCqlVjcdUbiGmeGrNh5Hv90nk+nQ6KCxTUjR3+FI=',
|
|
194
|
+
methods: '2YKySno+VMvwOxFVjNfhq7IOROUVA6sDqadLWSanDps='
|
|
195
|
+
}
|
|
196
|
+
👂 heard: Quinn
|
|
197
|
+
answer: Hello World, and hello to Quinn.
|
|
198
|
+
md5: F5btSbM4pnX3FtbTL10dmg==
|
|
199
|
+
sha256: 6jZOnkot+ZlZavu/w8R8ekqP3VfCcJ3nM2HGzbzX7jQ=
|
|
200
|
+
sha512: Xc/30QmT4F8jhtMCuobJkRGyE6rzyEKbLgCbYr2uu7l1ZjJ1c6VwUy2ptv0YUS3+BkG3bnMW5dkw47jQEzBpqQ==
|
|
201
|
+
md5 matches: true
|
|
202
|
+
sha256 matches: true
|
|
203
|
+
sha512 matches: true
|
|
204
|
+
Hello Deva active since Saturday, November 14, 2026 - 9:26:59 AM
|
|
205
|
+
on the bus: 23
|
|
206
|
+
question listeners: 1
|
|
207
|
+
stopping: Hello Deva active since Saturday, November 14, 2026 - 9:26:59 AM
|
|
208
|
+
stopped: shutdown
|
|
209
|
+
⭕️ OFFLINE
|
|
210
|
+
on the bus: 0
|
|
211
|
+
question listeners: 0
|
|
212
|
+
talk: ⭕️ OFFLINE
|
|
213
|
+
answer: ⭕️ OFFLINE
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
The program ends by itself as soon as the last line prints. Nothing is left running, because the shutdown took every listener off the bus.
|
|
217
|
+
|
|
218
|
+
Some of this will be different for you:
|
|
219
|
+
|
|
220
|
+
- **The date and time** after `active since` are when you started the Deva.
|
|
221
|
+
- **The md5, sha256 and sha512 values** change on every run, as in Step {{ life.step }}.
|
|
222
|
+
- **The ready hash** stays the same from run to run. It matches the values above only if your vars and your func, methods and listeners are exactly the same as on this page, down to the spacing.
|
|
223
|
+
- **The first `on the bus` number** counts the core's own state listeners as well as yours, so it can be different with a different version of Deva Core. The second `on the bus` number should always be `0`.
|
|
224
|
+
|
|
225
|
+
## If something goes wrong
|
|
226
|
+
|
|
227
|
+
| You see | What it means |
|
|
228
|
+
|---|---|
|
|
229
|
+
| `Cannot read properties of undefined (reading 'hash')` | Your installed `{{ guide.package }}` is older than 1.64.70. This step needs version 1.64.70 or newer. Check with `npm ls {{ guide.package }}`. |
|
|
230
|
+
| `stopped: stop`, the Deva is still active, and then `TypeError: Cannot read properties of undefined (reading 'text')` | `onStop` didn't hand the shutdown on, so the Deva never stopped. Its listener was still on the bus, and the `talk` line reached it without a question packet. `onStop` must end with `return this.close(data, resolve);`. |
|
|
231
|
+
| `TypeError: hello.events.eventNames is not a function` | The code read `hello.events` after the stop. Shutdown sets `hello.events` to `false`, so keep a reference with `const bus = hello.events;` before calling `stop()`, and use `bus` afterward. |
|
|
232
|
+
| `⭕️ OFFLINE` from a second `hello.stop()` | This isn't an error. Stopping a Deva that's already stopped answers `⭕️ OFFLINE`. |
|
|
233
|
+
|
|
234
|
+
## What you did
|
|
235
|
+
|
|
236
|
+
{% for item in step.learn %}- {{ item }}
|
|
237
|
+
{% endfor %}
|
|
238
|
+
|
|
239
|
+
## Where to go next
|
|
240
|
+
|
|
241
|
+
That's the whole life of a Deva. Over these seven steps you wrote a client file and an agent file, wired them into `index.js`, gave {{ guide.deva }} a func, a method and a listener, started it with `init(client)`, asked it a question, checked the stamps on its answer, and shut it down cleanly.
|
|
242
|
+
|
|
243
|
+
Every Deva is built from these same parts. License Deva is a good next one to read. It uses funcs for its database work and methods for its public commands, just as {{ guide.deva }} does. It also does something {{ guide.deva }} doesn't: in its own `onInit`, it compares the agent's VLA, the one in `info`, before it lets itself start. The client's VLA is still checked by the core at `init(client)`, exactly as it was for {{ guide.deva }}.
|
|
244
|
+
|
|
245
|
+
For the full list of options, events and functions in Deva Core, see the [Docs](/docs/).
|
|
246
|
+
|
|
247
|
+
For troubleshooting please see [Troubleshooting](/guide/troubleshooting).
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
---
|
|
2
|
+
layout: page
|
|
3
|
+
title: "Troubleshooting"
|
|
4
|
+
permalink: /guide/troubleshooting/
|
|
5
|
+
description: Every error and warning message from the Hello Deva guide, what causes it, and how to fix it.
|
|
6
|
+
image: /assets/banner.png
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
{% assign guide = site.data.guide.DATA %}
|
|
10
|
+
{% assign s1 = guide.steps | where: "step", 1 | first %}
|
|
11
|
+
{% assign s2 = guide.steps | where: "step", 2 | first %}
|
|
12
|
+
{% assign s3 = guide.steps | where: "step", 3 | first %}
|
|
13
|
+
{% assign s4 = guide.steps | where: "step", 4 | first %}
|
|
14
|
+
{% assign s5 = guide.steps | where: "step", 5 | first %}
|
|
15
|
+
{% assign s6 = guide.steps | where: "step", 6 | first %}
|
|
16
|
+
{% assign s7 = guide.steps | where: "step", 7 | first %}
|
|
17
|
+
|
|
18
|
+
{{ page.description }}
|
|
19
|
+
|
|
20
|
+
This page collects every problem covered in the guide in one place. Each row tells you what you'll see, why it happens, and how to fix it, and links to the step that explains it in full.
|
|
21
|
+
|
|
22
|
+
## How to read an error
|
|
23
|
+
|
|
24
|
+
When Node.js stops with an error, it prints several lines. Here's a real one from Step {{ s6.step }}, shortened to its first `at` line. The path will show your own project folder:
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
file:///home/you/hello-deva/node_modules/@indra.ai/deva/index.js:2119
|
|
28
|
+
const warning = this._agent.profile.warning || this._messages.warning; // agent or default warning
|
|
29
|
+
^
|
|
30
|
+
|
|
31
|
+
TypeError: Cannot read properties of undefined (reading 'warning')
|
|
32
|
+
at Deva.uid (file:///home/you/hello-deva/node_modules/@indra.ai/deva/index.js:2119:39)
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
- **The first line** is the file and line number where the error happened. It's often inside Deva Core, in `node_modules`, even when the mistake is in your own file. Line numbers can change from one version to the next, so don't search for them.
|
|
36
|
+
- **The line with `^`** points at the exact spot in that line.
|
|
37
|
+
- **The line that starts with an error name**, such as `TypeError` or `SyntaxError`, is the message. This is the line to look up in the tables below.
|
|
38
|
+
- **Lines that start with `at`** come after the message. They show the path the code took to get there, and you can usually ignore them. Node prints several of them; the example shows only the first.
|
|
39
|
+
|
|
40
|
+
Not every message is a crash. Messages that start with `❌`, `⛔️` or `⭕️` are Deva Core's own answers. They mean the Deva did something on purpose, such as refusing to start or answering while it's offline.
|
|
41
|
+
|
|
42
|
+
## Check your version first
|
|
43
|
+
|
|
44
|
+
Steps {{ s6.step }} and {{ s7.step }} need `{{ guide.package }}` version 1.64.70 or newer. To see which version you have installed, run this in your project folder:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm ls {{ guide.package }}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
| You see | Why | Fix |
|
|
51
|
+
|---|---|---|
|
|
52
|
+
| `TypeError: Cannot read properties of undefined (reading 'hash')` when the Deva starts | Your installed Deva Core is older than 1.64.70. | Install version 1.64.70 or newer. See [Step {{ s6.step }}]({{ s6.permalink }}). |
|
|
53
|
+
|
|
54
|
+
## The client and agent files (Steps {{ s2.step }} and {{ s3.step }})
|
|
55
|
+
|
|
56
|
+
| You see | Why | Fix |
|
|
57
|
+
|---|---|---|
|
|
58
|
+
| `SyntaxError` with the path to `agent.json` or `client.json`, such as `Expected double-quoted property name in JSON` | The JSON isn't valid. A missing quote, an extra comma or a missing bracket is enough. | Run the JSON check from [Step {{ s2.step }}]({{ s2.permalink }}) or [Step {{ s3.step }}]({{ s3.permalink }}). It names the line and column of the problem. |
|
|
59
|
+
| `❌ Bad Personal VLA` | The client file has no `VLA`. | Add the VLA to the client's `DATA`, as shown in [Step {{ s2.step }}]({{ s2.permalink }}). |
|
|
60
|
+
| `❌ Invalid VLA Check` | The client's `VLA` was changed or only partly copied, so it doesn't exactly match the one that ships with Deva Core. | Copy it again, unchanged, as shown in [Step {{ s2.step }}]({{ s2.permalink }}). |
|
|
61
|
+
|
|
62
|
+
Both VLA messages are about the **client's** VLA, which the core checks when the Deva starts. The agent's VLA, at the top of `agent.json`, isn't checked at start-up.
|
|
63
|
+
|
|
64
|
+
Missing client settings don't stop the Deva. It fills them in with default messages, which you'll see in a feature's data, for example in `hello.license()` while the Deva is running:
|
|
65
|
+
|
|
66
|
+
| Default message | What's missing from `client.json` |
|
|
67
|
+
|---|---|
|
|
68
|
+
| `⛔️ NO NAME PROVIDED` | `profile.name` |
|
|
69
|
+
| `⛔️ NO CONCERNS PROVIDED` | a feature's `concerns` |
|
|
70
|
+
| `⛔️ NO GLOBAL PROVIDED` | a feature's `global` |
|
|
71
|
+
| `⛔️ NO DEVAS PROVIDED` | a feature's `devas` |
|
|
72
|
+
|
|
73
|
+
[Step {{ s2.step }}]({{ s2.permalink }}) shows the full client file with every setting in place.
|
|
74
|
+
|
|
75
|
+
## Wiring it together (Step {{ s4.step }})
|
|
76
|
+
|
|
77
|
+
| You see | Why | Fix |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| `needs an import attribute of "type: json"` | An import of a JSON file is missing `with {type:'json'}`. | Add `with {type:'json'}` to the end of the import. See [Step {{ s4.step }}]({{ s4.permalink }}). |
|
|
80
|
+
| `Cannot find module` for `agent.json` or `client.json` | The import path is wrong. | The files live in `data/`, so the imports should be `./data/agent.json` and `./data/client.json`. |
|
|
81
|
+
| `undefined` instead of `Hello World` | `vars: agent.vars` is missing from `new Deva()`. | Add `vars: agent.vars,` after the `agent` block. See [Step {{ s4.step }}]({{ s4.permalink }}). |
|
|
82
|
+
| `TypeError: Cannot read properties of undefined (reading 'greeting')` | `agent` is the whole agent file instead of what's inside it, so `agent.vars` doesn't exist. | It should be `const agent = Agent.DATA;`. The same message in Step {{ s5.step }} has a different cause, listed in the next section. |
|
|
83
|
+
|
|
84
|
+
## Skills (Step {{ s5.step }})
|
|
85
|
+
|
|
86
|
+
Some of these only show up once the Deva starts and runs your method, which first happens in [Step {{ s6.step }}]({{ s6.permalink }}).
|
|
87
|
+
|
|
88
|
+
| You see | Why | Fix |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| `TypeError: Cannot read properties of undefined (reading 'greeting')` | `hello.func.greet()` was called directly before the Deva started. Before start-up, `this` inside a func isn't the Deva yet. | Use the check from section 5 of [Step {{ s5.step }}]({{ s5.permalink }}) instead. |
|
|
91
|
+
| `TypeError: Cannot read properties of undefined (reading 'vars')` | A func, method or listener was written as an arrow function, such as `greet: (name) => {}`. An arrow function can't be bound to the Deva. | Write it as a normal function, such as `greet(name) {}`. See [Step {{ s5.step }}]({{ s5.permalink }}). |
|
|
92
|
+
| `.then is not a function`, in a line that starts with `TypeError` | A method returned a plain value instead of a Promise. | Return a Promise, as the `hello` method does with `new Promise(resolve => {})`. See [Step {{ s5.step }}]({{ s5.permalink }}). |
|
|
93
|
+
| `⛔️ METHOD NOT FOUND hello hi` | The command doesn't match a method name. `/hi` looks for `methods.hi`. | Ask with the method's exact name, such as `/hello`. |
|
|
94
|
+
| `SyntaxError: Unexpected token '{'` | A listener's event name is missing its quotes. | Write the name in quotes, such as `'devacore:question'(packet)`. |
|
|
95
|
+
|
|
96
|
+
## Bring it to life (Step {{ s6.step }})
|
|
97
|
+
|
|
98
|
+
| You see | Why | Fix |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| `TypeError: Cannot create property 'created' on boolean 'false'` | `info` is missing from `new Deva()`. | Make `info,` the first entry in `new Deva()`. See [Step {{ s4.step }}]({{ s4.permalink }}). |
|
|
101
|
+
| `TypeError: Cannot read properties of undefined (reading 'warning')` | `agent` is the whole agent file instead of what's inside it. | It should be `const agent = Agent.DATA;`. |
|
|
102
|
+
| Only two `⭕️ OFFLINE` lines, and nothing else | The client's VLA didn't pass the check at `init(client)`, so the Deva never started. | To see why, change the line to `console.log(await hello.init(client));`. It prints `❌ Bad Personal VLA` or `❌ Invalid VLA Check`, both covered above. |
|
|
103
|
+
| The program ends without `👂 heard: Quinn` or `answer:` | `onReady` is missing or misspelled. | Name it exactly `onReady`. See [Step {{ s6.step }}]({{ s6.permalink }}). |
|
|
104
|
+
| A `matches` line says `false` | The packet was changed after it was stamped, or the stamps were rebuilt in a different order. | Rebuild them in the order md5, sha256, sha512. See [Step {{ s6.step }}]({{ s6.permalink }}). |
|
|
105
|
+
|
|
106
|
+
## Shut it down (Step {{ s7.step }})
|
|
107
|
+
|
|
108
|
+
| You see | Why | Fix |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| `stopped: stop`, the Deva is still active, and then `TypeError: Cannot read properties of undefined (reading 'text')` | `onStop` didn't hand the shutdown on, so the Deva never stopped. Its listener was still on the bus, and the `talk` line reached it without a question packet. | End `onStop` with `return this.close(data, resolve);`. See [Step {{ s7.step }}]({{ s7.permalink }}). |
|
|
111
|
+
| `TypeError: hello.events.eventNames is not a function` | The code read `hello.events` after the stop. Shutdown sets `hello.events` to `false`. | Keep a reference with `const bus = hello.events;` before calling `stop()`, and use `bus` afterward. |
|
|
112
|
+
| `⭕️ OFFLINE` from a second `hello.stop()` | This isn't an error. Stopping a Deva that's already stopped answers `⭕️ OFFLINE`. | Nothing to fix. |
|
|
113
|
+
|
|
114
|
+
## Still stuck?
|
|
115
|
+
|
|
116
|
+
Go back to the step where the problem started and compare your `index.js` with that step's whole-file block, line by line. Every whole-file block in the guide was run exactly as written.
|