@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 CHANGED
@@ -1,132 +1,114 @@
1
1
  # @avowa/runtime
2
2
 
3
- The JavaScript/TypeScript half of the [Avowa Runtime SDK](https://github.com/Avowa-AI/avowa-runtime-sdk) — emits live AI-inference
4
- signals to Avowa as **observed** evidence. Node 18+, server-side only — the signing secret must never ship to a browser, and the ingest API does not accept browser origins.
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
- **Two lines, in your project folder.** Your code stays as it is. (The setup token comes from
9
- Connections → Runtime SDK → *Generate setup token*.)
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> # writes avowa.env with one value: AVOWA_TOKEN
20
+ npx @avowa/runtime init <setup-token>
14
21
  ```
15
22
 
16
- `init` also offers to add the preload to your `start` script, and shows the change before it makes
17
- it (`init --dry-run` changes nothing at all):
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
- Then start your app the way you always do and send one real request that calls the model.
25
- `npx @avowa/runtime status` shows what is covered and asks the server whether it knows this key. It
26
- sends no signal.
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 environment variables and change nothing else:
35
+ **In production** set two variables and change nothing else:
29
36
 
30
37
  ```bash
31
- AVOWA_TOKEN=avw1_... # the value in avowa.env
32
- NODE_OPTIONS=--import @avowa/runtime/register # any start command, Docker, Kubernetes
38
+ AVOWA_TOKEN=<the value in avowa.env>
39
+ NODE_OPTIONS=--import @avowa/runtime/register
33
40
  ```
34
41
 
35
- `AVOWA_DISABLE=1` switches everything off. One dependency-free package, Apache-2.0.
36
-
37
- ### What the preload covers
42
+ ## What the preload covers
38
43
 
39
- `@avowa/runtime/register` patches the provider SDKs' own classes as your app loads, so every client
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
- | anything else (Bedrock, Gemini, Vercel AI SDK, raw `fetch`) | not yet: use `capture()` / `track()` below |
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
- ## Use it in code instead
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
- Nothing below is needed when the preload is on. It is for the cases above, and for recording what
59
- your app enforces.
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 createAvowa from '@avowa/runtime'
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
- // or wrap one: times it, and records whether it was blocked
70
- const resp = await avowa.track({ model: 'claude-opus-4-8' }, () => client.messages.create(...))
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
- `createAvowa({ ingestKey, ingestSecret, baseUrl, region })` takes the values explicitly if you would
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
- **Metadata only.** Model id, host, region, latency, counts and the flags you pass. Never prompts,
79
- completions, tool arguments or customer data.
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, agentContext } from '@avowa/runtime'
72
+ import { agentContext, approval, toolOutcome } from '@avowa/runtime'
99
73
 
100
- await agentContext({ name: 'triage', customer: account.id }, async () => {
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' && needsSignOff(b)) {
104
- approval(b.id, await askAHuman(b), 'finance_ops', { approverType: 'human' }) // a role label, never a name
105
- toolOutcome(b.id, 'ok') // or 'error', 'denied', 'timeout'
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'` (with `policyRef`), `'system'` or `'unknown'` (the default); only
112
- `'human'` counts as human approval, and Avowa does not claim the decision came before the tool ran.
113
- Call references are 20 hex characters of a hash of the provider's id: a correlation label, not
114
- anonymisation. The customer id is sent only as a keyed hash; set `AVOWA_REF_KEY` (read only in your
115
- process, never sent) and nobody else can test a guess. Rotating it starts a new correlation period.
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
- ## Wrap your client (observed, not asserted)
93
+ ## Recording what your app enforces
118
94
 
119
95
  ```js
120
- import OpenAI from 'openai'
121
- import { createAvowa } from '@avowa/runtime'
96
+ avowa.capture({ model: 'claude-opus-4-8', train_on_data: false })
122
97
 
123
- const avowa = createAvowa() // AVOWA_TOKEN from the env
124
- const openai = avowa.instrumentOpenAI(new OpenAI()) // chat.completions.create, responses.create — streams included
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
- The wrapper reads the requested and served model, the provider's finish/stop code, the tools
129
- offered and the tools the model invoked, and scans the prompt and output text locally; only counts
130
- leave. It sends those facts as they are — Avowa evaluates them on its side — and each signal names
131
- the fields the wrapper read, so they grade as observed rather than as your app's word. `capture()` and `track()` remain for anything else,
132
- graded as self-reported.
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.1';
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.1",
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",