@avowa/runtime 0.13.1 → 0.13.2
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 +65 -83
- package/avowa-runtime.js +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,132 +1,114 @@
|
|
|
1
1
|
# @avowa/runtime
|
|
2
2
|
|
|
3
|
-
The
|
|
4
|
-
|
|
3
|
+
The Node.js half of the [Avowa Runtime SDK](https://github.com/Avowa-AI/avowa-runtime-sdk). Keeps an
|
|
4
|
+
independent record of what your AI does in production: which model answered, where it ran, which tools
|
|
5
|
+
your agents called, and who approved them.
|
|
6
|
+
|
|
7
|
+
It reads **metadata only**. It never sends prompts, completions, tool arguments or tool output, never
|
|
8
|
+
changes a request or response, and never blocks a call. If Avowa is unreachable your app carries on.
|
|
9
|
+
`AVOWA_DISABLE=1` turns it off. Node 18.18+ or 20.6+, server-side only. Apache-2.0, no dependencies.
|
|
10
|
+
|
|
11
|
+
**Documentation: [avowa.ai/docs](https://avowa.ai/docs/)**
|
|
5
12
|
|
|
6
13
|
## Install
|
|
7
14
|
|
|
8
|
-
|
|
9
|
-
|
|
15
|
+
In your project folder. Generate the setup token in the Avowa console under **Connections, Runtime
|
|
16
|
+
SDK**; it works once.
|
|
10
17
|
|
|
11
18
|
```bash
|
|
12
19
|
npm install @avowa/runtime
|
|
13
|
-
npx @avowa/runtime init <setup-token>
|
|
20
|
+
npx @avowa/runtime init <setup-token>
|
|
14
21
|
```
|
|
15
22
|
|
|
16
|
-
`init`
|
|
17
|
-
|
|
23
|
+
`init` writes `avowa.env` (one line, `AVOWA_TOKEN`), adds it to `.gitignore`, and offers to add the
|
|
24
|
+
preload to your `start` script, showing the change first (`init --dry-run` changes nothing):
|
|
18
25
|
|
|
19
26
|
```
|
|
20
27
|
from: node server.js
|
|
21
28
|
to: node --import @avowa/runtime/register server.js
|
|
22
29
|
```
|
|
23
30
|
|
|
24
|
-
|
|
25
|
-
`npx @avowa/runtime status` shows what is covered and
|
|
26
|
-
|
|
31
|
+
Start your app the way you always do and send one request that calls the model. Then
|
|
32
|
+
`npx @avowa/runtime status` shows what is covered and whether the server knows this key. It sends no
|
|
33
|
+
signal.
|
|
27
34
|
|
|
28
|
-
**In production** set two
|
|
35
|
+
**In production** set two variables and change nothing else:
|
|
29
36
|
|
|
30
37
|
```bash
|
|
31
|
-
AVOWA_TOKEN
|
|
32
|
-
NODE_OPTIONS=--import @avowa/runtime/register
|
|
38
|
+
AVOWA_TOKEN=<the value in avowa.env>
|
|
39
|
+
NODE_OPTIONS=--import @avowa/runtime/register
|
|
33
40
|
```
|
|
34
41
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
### What the preload covers
|
|
42
|
+
## What the preload covers
|
|
38
43
|
|
|
39
|
-
|
|
40
|
-
is covered whoever builds it: your code, a framework, or a dependency. ES modules and CommonJS both
|
|
41
|
-
work.
|
|
42
|
-
|
|
43
|
-
| Library | Covered |
|
|
44
|
+
| Library | Coverage |
|
|
44
45
|
|---|---|
|
|
45
46
|
| `openai` (OpenAI, Azure OpenAI, any OpenAI-compatible host) | `chat.completions.create`, `responses.create`, streams included |
|
|
46
47
|
| `@anthropic-ai/sdk` | `messages.create`, streams included |
|
|
47
|
-
|
|
|
48
|
-
|
|
49
|
-
Two limits to know about:
|
|
50
|
-
|
|
51
|
-
- **Bundled server code.** A bundler (Next.js, esbuild, webpack) that compiles the provider SDK into
|
|
52
|
-
its own output file carries a private copy the preload never meets. Keep the provider SDK external
|
|
53
|
-
to the bundle (Next.js: `serverExternalPackages`), or wrap the client once as shown below.
|
|
54
|
-
- **Node version.** `--import` needs Node 18.18+ or 20.6+.
|
|
48
|
+
| Bedrock, Gemini, Vercel AI SDK, raw `fetch` | not yet: use `capture()` or `track()` |
|
|
55
49
|
|
|
56
|
-
|
|
50
|
+
ES modules and CommonJS both work. The wrappers hand back the provider's own promise and stream objects,
|
|
51
|
+
so `.withResponse()`, `.tee()` and `instanceof` behave as without Avowa.
|
|
57
52
|
|
|
58
|
-
|
|
59
|
-
|
|
53
|
+
**Bundled server code.** A bundler (Next.js, esbuild, webpack) that compiles the provider SDK into its
|
|
54
|
+
own output carries a private copy the preload never meets. Keep the provider SDK external to the bundle
|
|
55
|
+
(Next.js: `serverExternalPackages`), or wrap the client once:
|
|
60
56
|
|
|
61
57
|
```js
|
|
62
|
-
import
|
|
63
|
-
|
|
64
|
-
const avowa = createAvowa() // reads AVOWA_TOKEN from the environment
|
|
65
|
-
|
|
66
|
-
// record a call you already made
|
|
67
|
-
avowa.capture({ model: 'claude-opus-4-8', train_on_data: false })
|
|
58
|
+
import OpenAI from 'openai'
|
|
59
|
+
import { createAvowa } from '@avowa/runtime'
|
|
68
60
|
|
|
69
|
-
|
|
70
|
-
const
|
|
61
|
+
const avowa = createAvowa() // reads AVOWA_TOKEN
|
|
62
|
+
const openai = avowa.instrumentOpenAI(new OpenAI())
|
|
63
|
+
// const anthropic = avowa.instrumentAnthropic(new Anthropic())
|
|
71
64
|
```
|
|
72
65
|
|
|
73
|
-
|
|
74
|
-
rather not use the token, and the three separate variables (`AVOWA_RUNTIME_KEY`,
|
|
75
|
-
`AVOWA_RUNTIME_SECRET`, `AVOWA_BASE_URL`) still work. To read `avowa.env` without the preload:
|
|
76
|
-
`import { loadEnv } from '@avowa/runtime/env'; loadEnv()`.
|
|
66
|
+
## Agents: runs, approvals, outcomes
|
|
77
67
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
**Never in your way.** Capture is fire-and-forget and never rejects: if Avowa is unreachable your
|
|
82
|
-
call still returns, uploads time out after 5 s, and at most 64 are in flight (past that they are
|
|
83
|
-
dropped, with one warning). The wrappers hand back the provider's own promise and stream objects
|
|
84
|
-
(`.withResponse()`, `.tee()` and `instanceof` all behave as without Avowa). HTTPS only, every
|
|
85
|
-
request signed and single-use, and `AVOWA_DISABLE=1` turns it off entirely.
|
|
86
|
-
`track()` re-throws whatever your function threw, after recording that it was blocked.
|
|
87
|
-
|
|
88
|
-
Licence: Apache-2.0.
|
|
89
|
-
|
|
90
|
-
## Agents: approvals, outcomes and who ran it (0.13)
|
|
91
|
-
|
|
92
|
-
The wrappers read each tool call the model proposed and each result your app handed back, by a hash
|
|
93
|
-
of the provider's call id (the id never leaves your process), plus the run key and step depth, the
|
|
94
|
-
same as the Python SDK. A human approval or a tool's outcome happens after the call, so record it on
|
|
95
|
-
its own:
|
|
68
|
+
The wrappers record each tool call the model proposed and each result your app handed back, by a hash
|
|
69
|
+
of the provider's call id, with the step depth and a run key. Three calls add what they cannot see:
|
|
96
70
|
|
|
97
71
|
```js
|
|
98
|
-
import { approval, toolOutcome
|
|
72
|
+
import { agentContext, approval, toolOutcome } from '@avowa/runtime'
|
|
99
73
|
|
|
100
|
-
await agentContext({ name: '
|
|
74
|
+
await agentContext({ name: 'incident-agent', customer: account.id }, async () => {
|
|
101
75
|
const resp = await client.messages.create({ ... })
|
|
102
76
|
for (const b of resp.content) {
|
|
103
|
-
if (b.type === 'tool_use'
|
|
104
|
-
|
|
105
|
-
|
|
77
|
+
if (b.type === 'tool_use') {
|
|
78
|
+
const ok = await askOnCall(b) // your approval step
|
|
79
|
+
approval(b.id, ok, 'on-call SRE', { approverType: 'human' }) // a role, never a name
|
|
80
|
+
// a rule instead: approval(b.id, true, null, { approverType: 'policy', policyRef: 'read-only-tools' })
|
|
81
|
+
toolOutcome(b.id, ok ? 'ok' : 'denied') // or 'error', 'timeout'
|
|
106
82
|
}
|
|
107
83
|
}
|
|
108
84
|
})
|
|
109
85
|
```
|
|
110
86
|
|
|
111
|
-
`approverType` is `'human'`, `'policy'
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
87
|
+
`approverType` is `'human'`, `'policy'`, `'system'` or `'unknown'` (the default); only `'human'` counts
|
|
88
|
+
as human approval. The customer id is sent only as a keyed hash. Findings name the run, step and a call
|
|
89
|
+
reference; `npx @avowa/runtime ref --find <ref> <logfile>` finds that call in your own logs.
|
|
90
|
+
|
|
91
|
+
Guide: [avowa.ai/docs/agents.html](https://avowa.ai/docs/agents.html).
|
|
116
92
|
|
|
117
|
-
##
|
|
93
|
+
## Recording what your app enforces
|
|
118
94
|
|
|
119
95
|
```js
|
|
120
|
-
|
|
121
|
-
import { createAvowa } from '@avowa/runtime'
|
|
96
|
+
avowa.capture({ model: 'claude-opus-4-8', train_on_data: false })
|
|
122
97
|
|
|
123
|
-
|
|
124
|
-
const
|
|
125
|
-
// const anthropic = avowa.instrumentAnthropic(new Anthropic()) // messages.create — streams included
|
|
98
|
+
// or wrap a call: times it and records whether it was blocked
|
|
99
|
+
const resp = await avowa.track({ model: 'claude-opus-4-8' }, () => client.messages.create(...))
|
|
126
100
|
```
|
|
127
101
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
102
|
+
These are signed in transit and graded as your application's word, never as observed. `track()`
|
|
103
|
+
re-throws whatever your function threw. Uploads time out after 5 seconds and at most 64 are in flight;
|
|
104
|
+
past that they are dropped, with one warning.
|
|
105
|
+
|
|
106
|
+
## More
|
|
107
|
+
|
|
108
|
+
- What leaves your process, field by field: [avowa.ai/docs/data.html](https://avowa.ai/docs/data.html)
|
|
109
|
+
- Security review: [avowa.ai/docs/security.html](https://avowa.ai/docs/security.html)
|
|
110
|
+
- Commands and environment variables: [avowa.ai/docs/reference.html](https://avowa.ai/docs/reference.html)
|
|
111
|
+
- Troubleshooting: [avowa.ai/docs/troubleshooting.html](https://avowa.ai/docs/troubleshooting.html)
|
|
112
|
+
- Changelog: [avowa.ai/docs/changelog.html](https://avowa.ai/docs/changelog.html)
|
|
113
|
+
|
|
114
|
+
Support: support@avowa.ai. Licence: Apache-2.0.
|
package/avowa-runtime.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
import { createHash, createHmac } from 'node:crypto';
|
|
4
4
|
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
5
5
|
const env = typeof process !== 'undefined' && process.env || {};
|
|
6
|
-
const VERSION = '0.13.
|
|
6
|
+
const VERSION = '0.13.2';
|
|
7
7
|
const SCHEMA = 'avowa.signal/1';
|
|
8
8
|
export const SDK_VERSION = VERSION;
|
|
9
9
|
let _subtle = null;
|
|
@@ -592,7 +592,7 @@ export function createAvowa({
|
|
|
592
592
|
const j = await r.clone().json();
|
|
593
593
|
if (j && j.sdk_fields && secret && remoteOn()) await acceptFields(j.sdk_fields, secret);
|
|
594
594
|
if (j && typeof j.sdk_latest === 'string' && /^\d+\.\d+\.\d+$/.test(j.sdk_latest)) {
|
|
595
|
-
warnOnce('latest', `@avowa/runtime ${j.sdk_latest} is available (this is ${VERSION}). Nothing is wrong — upgrade when convenient.`);
|
|
595
|
+
warnOnce('latest', `@avowa/runtime ${j.sdk_latest} is available (this is ${VERSION}). Nothing is wrong — upgrade when convenient: npm install @avowa/runtime@latest.`);
|
|
596
596
|
}
|
|
597
597
|
} catch {}
|
|
598
598
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@avowa/runtime",
|
|
3
|
-
"version": "0.13.
|
|
3
|
+
"version": "0.13.2",
|
|
4
4
|
"description": "Avowa Runtime SDK \u2014 emit live AI-inference signals as observed evidence. Metadata only; never prompts or completions.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "avowa-runtime.js",
|