@avowa/runtime 0.12.0 → 0.13.1
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 +27 -0
- package/avowa-runtime.js +354 -14
- package/cli.js +48 -8
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -87,6 +87,33 @@ request signed and single-use, and `AVOWA_DISABLE=1` turns it off entirely.
|
|
|
87
87
|
|
|
88
88
|
Licence: Apache-2.0.
|
|
89
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:
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
import { approval, toolOutcome, agentContext } from '@avowa/runtime'
|
|
99
|
+
|
|
100
|
+
await agentContext({ name: 'triage', customer: account.id }, async () => {
|
|
101
|
+
const resp = await client.messages.create({ ... })
|
|
102
|
+
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'
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
})
|
|
109
|
+
```
|
|
110
|
+
|
|
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.
|
|
116
|
+
|
|
90
117
|
## Wrap your client (observed, not asserted)
|
|
91
118
|
|
|
92
119
|
```js
|
package/avowa-runtime.js
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
// SPDX-License-Identifier: Apache-2.0
|
|
2
2
|
// Copyright 2026 Avowa, Inc.
|
|
3
|
+
import { createHash, createHmac } from 'node:crypto';
|
|
4
|
+
import { AsyncLocalStorage } from 'node:async_hooks';
|
|
3
5
|
const env = typeof process !== 'undefined' && process.env || {};
|
|
4
|
-
const VERSION = '0.
|
|
6
|
+
const VERSION = '0.13.1';
|
|
5
7
|
const SCHEMA = 'avowa.signal/1';
|
|
6
8
|
export const SDK_VERSION = VERSION;
|
|
7
9
|
let _subtle = null;
|
|
@@ -202,6 +204,197 @@ export function readToken(token) {
|
|
|
202
204
|
return null;
|
|
203
205
|
}
|
|
204
206
|
}
|
|
207
|
+
export const TOOL_OUTCOMES = ['ok', 'error', 'denied', 'timeout'];
|
|
208
|
+
export const APPROVER_TYPES = ['human', 'policy', 'system', 'unknown'];
|
|
209
|
+
const CALL_REF_LEN = 20;
|
|
210
|
+
const TOOL_CAP = 60;
|
|
211
|
+
const LABEL_RX = /^[A-Za-z0-9 _.:/-]{1,64}$/;
|
|
212
|
+
export function callRef(id) {
|
|
213
|
+
if (id === undefined || id === null || id === '') return null;
|
|
214
|
+
return createHash('sha256').update('avowa-call:' + String(id)).digest('hex').slice(0, CALL_REF_LEN);
|
|
215
|
+
}
|
|
216
|
+
const g = (o, k) => o === null || o === undefined ? undefined : o[k];
|
|
217
|
+
function toolCalls(resp) {
|
|
218
|
+
const out = [];
|
|
219
|
+
const add = (id, name) => {
|
|
220
|
+
const r = callRef(id);
|
|
221
|
+
if (r && name) out.push(r + ':' + String(name).slice(0, 64));
|
|
222
|
+
};
|
|
223
|
+
try {
|
|
224
|
+
for (const b of g(resp, 'content') || []) if (g(b, 'type') === 'tool_use') add(g(b, 'id'), g(b, 'name'));
|
|
225
|
+
const msg = g(g(g(resp, 'choices'), 0), 'message');
|
|
226
|
+
for (const tc of g(msg, 'tool_calls') || []) add(g(tc, 'id'), g(g(tc, 'function'), 'name') || g(tc, 'name'));
|
|
227
|
+
for (const it of Array.isArray(g(resp, 'output')) ? resp.output : []) {
|
|
228
|
+
if (['function_call', 'custom_tool_call'].includes(g(it, 'type'))) add(g(it, 'call_id') || g(it, 'id'), g(it, 'name'));
|
|
229
|
+
}
|
|
230
|
+
} catch {}
|
|
231
|
+
return out.slice(0, TOOL_CAP);
|
|
232
|
+
}
|
|
233
|
+
function toolResults(history) {
|
|
234
|
+
if (!Array.isArray(history)) return [];
|
|
235
|
+
let fresh = [];
|
|
236
|
+
for (const m of history) {
|
|
237
|
+
const role = g(m, 'role'),
|
|
238
|
+
typ = g(m, 'type');
|
|
239
|
+
if (role === 'assistant' || MODEL_ITEMS.has(typ)) {
|
|
240
|
+
fresh = [];
|
|
241
|
+
continue;
|
|
242
|
+
}
|
|
243
|
+
if (role === 'tool') {
|
|
244
|
+
const r = callRef(g(m, 'tool_call_id'));
|
|
245
|
+
if (r) fresh.push(r + ':returned');
|
|
246
|
+
continue;
|
|
247
|
+
}
|
|
248
|
+
if (typ === 'function_call_output' || typ === 'custom_tool_call_output') {
|
|
249
|
+
const r = callRef(g(m, 'call_id'));
|
|
250
|
+
if (r) fresh.push(r + ':returned');
|
|
251
|
+
continue;
|
|
252
|
+
}
|
|
253
|
+
const c = g(m, 'content');
|
|
254
|
+
if (Array.isArray(c)) {
|
|
255
|
+
for (const b of c) {
|
|
256
|
+
if (g(b, 'type') === 'tool_result') {
|
|
257
|
+
const r = callRef(g(b, 'tool_use_id'));
|
|
258
|
+
if (r) fresh.push(r + (g(b, 'is_error') === true ? ':error' : ':returned'));
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
return fresh.slice(0, TOOL_CAP);
|
|
264
|
+
}
|
|
265
|
+
function mcpFacts(params, resp) {
|
|
266
|
+
const f = {},
|
|
267
|
+
labels = [],
|
|
268
|
+
hosts = [],
|
|
269
|
+
ran = [],
|
|
270
|
+
hostOfLabel = {};
|
|
271
|
+
const note = (lb, h) => {
|
|
272
|
+
if (lb) labels.push(String(lb).slice(0, 64));
|
|
273
|
+
if (h) {
|
|
274
|
+
hosts.push(h);
|
|
275
|
+
if (lb) hostOfLabel[String(lb).slice(0, 64)] = h;
|
|
276
|
+
}
|
|
277
|
+
};
|
|
278
|
+
try {
|
|
279
|
+
for (const s of g(params, 'mcp_servers') || []) note(g(s, 'name'), hostOf(g(s, 'url')));
|
|
280
|
+
for (const t of g(params, 'tools') || []) {
|
|
281
|
+
if (g(t, 'type') === 'mcp') note(g(t, 'server_label'), hostOf(g(t, 'server_url')));
|
|
282
|
+
}
|
|
283
|
+
for (const b of g(resp, 'content') || []) {
|
|
284
|
+
if (g(b, 'type') === 'mcp_tool_use' && g(b, 'name')) ran.push(String(g(b, 'server_name') || '?').slice(0, 64) + '/' + String(b.name).slice(0, 64));
|
|
285
|
+
}
|
|
286
|
+
for (const it of Array.isArray(g(resp, 'output')) ? resp.output : []) {
|
|
287
|
+
if (g(it, 'type') === 'mcp_call' && g(it, 'name')) ran.push(String(g(it, 'server_label') || '?').slice(0, 64) + '/' + String(it.name).slice(0, 64));
|
|
288
|
+
}
|
|
289
|
+
} catch {}
|
|
290
|
+
const uniq = a => [...new Set(a)].sort().slice(0, TOOL_CAP);
|
|
291
|
+
if (labels.length) f.mcp_servers_offered = uniq(labels);
|
|
292
|
+
if (hosts.length) f.mcp_hosts = uniq(hosts);
|
|
293
|
+
if (labels.length || ran.length) {
|
|
294
|
+
f.mcp_tools_invoked = uniq(ran);
|
|
295
|
+
f.mcp_hosts_invoked = uniq(ran.map(r => hostOfLabel[r.split('/')[0]]).filter(Boolean));
|
|
296
|
+
}
|
|
297
|
+
return f;
|
|
298
|
+
}
|
|
299
|
+
function runKey(messages, secret) {
|
|
300
|
+
if (typeof messages === 'string') messages = [{
|
|
301
|
+
role: 'user',
|
|
302
|
+
content: messages
|
|
303
|
+
}];
|
|
304
|
+
if (!Array.isArray(messages)) return null;
|
|
305
|
+
for (const m of messages) {
|
|
306
|
+
if (g(m, 'role') !== 'user') continue;
|
|
307
|
+
let c = g(m, 'content');
|
|
308
|
+
if (Array.isArray(c)) c = c.map(b => b && typeof b === 'object' ? String(b.text || b.content || '') : '').join('');
|
|
309
|
+
c = String(c || '').trim();
|
|
310
|
+
if (!c) continue;
|
|
311
|
+
return (secret ? createHmac('sha256', String(secret)).update(c) : createHash('sha256').update(c)).digest('hex').slice(0, 12);
|
|
312
|
+
}
|
|
313
|
+
return null;
|
|
314
|
+
}
|
|
315
|
+
const MODEL_ITEMS = new Set(['function_call', 'custom_tool_call', 'mcp_call', 'computer_call', 'web_search_call', 'file_search_call', 'code_interpreter_call', 'local_shell_call', 'reasoning']);
|
|
316
|
+
const CALL_ITEMS = new Set(['function_call', 'custom_tool_call', 'mcp_call', 'computer_call', 'local_shell_call']);
|
|
317
|
+
const RESULT_ITEMS = new Set(['function_call_output', 'custom_tool_call_output', 'computer_call_output', 'local_shell_call_output', 'mcp_approval_response']);
|
|
318
|
+
function modelTurns(messages) {
|
|
319
|
+
const turns = [];
|
|
320
|
+
let cur = null;
|
|
321
|
+
for (const m of messages) {
|
|
322
|
+
const role = g(m, 'role'),
|
|
323
|
+
typ = g(m, 'type');
|
|
324
|
+
if (!(MODEL_ITEMS.has(typ) || role === 'assistant')) {
|
|
325
|
+
cur = null;
|
|
326
|
+
turns.push([false, false]);
|
|
327
|
+
continue;
|
|
328
|
+
}
|
|
329
|
+
let tools = CALL_ITEMS.has(typ);
|
|
330
|
+
if (role === 'assistant') {
|
|
331
|
+
if (Array.isArray(g(m, 'tool_calls')) && m.tool_calls.length) tools = true;
|
|
332
|
+
const c = g(m, 'content');
|
|
333
|
+
if (Array.isArray(c) && c.some(b => g(b, 'type') === 'tool_use')) tools = true;
|
|
334
|
+
}
|
|
335
|
+
if (role === 'assistant' && typ === undefined) {
|
|
336
|
+
cur = null;
|
|
337
|
+
turns.push([true, tools]);
|
|
338
|
+
continue;
|
|
339
|
+
}
|
|
340
|
+
if (!cur) {
|
|
341
|
+
cur = [true, false];
|
|
342
|
+
turns.push(cur);
|
|
343
|
+
}
|
|
344
|
+
cur[1] = cur[1] || tools;
|
|
345
|
+
}
|
|
346
|
+
return turns;
|
|
347
|
+
}
|
|
348
|
+
function autonomyDepth(messages) {
|
|
349
|
+
if (typeof messages === 'string') return 0;
|
|
350
|
+
if (!Array.isArray(messages)) return null;
|
|
351
|
+
try {
|
|
352
|
+
return modelTurns(messages).filter(([m, t]) => m && t).length;
|
|
353
|
+
} catch {
|
|
354
|
+
return null;
|
|
355
|
+
}
|
|
356
|
+
}
|
|
357
|
+
const CHAIN = new Map();
|
|
358
|
+
function chainPut(id, key, next) {
|
|
359
|
+
CHAIN.set(String(id), [key, next]);
|
|
360
|
+
while (CHAIN.size > 4096) CHAIN.delete(CHAIN.keys().next().value);
|
|
361
|
+
}
|
|
362
|
+
const AGENT = new AsyncLocalStorage();
|
|
363
|
+
export function agentContext({
|
|
364
|
+
name,
|
|
365
|
+
customer
|
|
366
|
+
} = {}, fn) {
|
|
367
|
+
let nm = name === undefined || name === null ? null : String(name).slice(0, 64);
|
|
368
|
+
if (nm !== null && !LABEL_RX.test(nm)) {
|
|
369
|
+
warnOnce('agentname', 'agentContext name must be letters, digits and _ . : / - (64 at most); the name was not recorded.');
|
|
370
|
+
nm = null;
|
|
371
|
+
}
|
|
372
|
+
return AGENT.run({
|
|
373
|
+
name: nm,
|
|
374
|
+
customer: customer === undefined || customer === null ? null : String(customer)
|
|
375
|
+
}, fn);
|
|
376
|
+
}
|
|
377
|
+
function customerRef(secret, customer) {
|
|
378
|
+
if (customer === undefined || customer === null || customer === '') return null;
|
|
379
|
+
const key = env.AVOWA_REF_KEY || secret;
|
|
380
|
+
if (!key) return null;
|
|
381
|
+
return createHmac('sha256', String(key)).update('avowa-customer:' + String(customer)).digest('hex').slice(0, 12);
|
|
382
|
+
}
|
|
383
|
+
let DEFAULT = null;
|
|
384
|
+
export function approval(callId, approved, approverRole, opts = {}) {
|
|
385
|
+
if (!DEFAULT) {
|
|
386
|
+
warnOnce('noruntime', 'approval() was called but no Avowa runtime is running; nothing was recorded.');
|
|
387
|
+
return Promise.resolve(null);
|
|
388
|
+
}
|
|
389
|
+
return DEFAULT.approval(callId, approved, approverRole, opts);
|
|
390
|
+
}
|
|
391
|
+
export function toolOutcome(callId, outcome) {
|
|
392
|
+
if (!DEFAULT) {
|
|
393
|
+
warnOnce('noruntime', 'toolOutcome() was called but no Avowa runtime is running; nothing was recorded.');
|
|
394
|
+
return Promise.resolve(null);
|
|
395
|
+
}
|
|
396
|
+
return DEFAULT.toolOutcome(callId, outcome);
|
|
397
|
+
}
|
|
205
398
|
export function createAvowa({
|
|
206
399
|
ingestKey,
|
|
207
400
|
ingestSecret,
|
|
@@ -216,6 +409,8 @@ export function createAvowa({
|
|
|
216
409
|
instrumentOpenAI: c => c,
|
|
217
410
|
instrumentAnthropic: c => c,
|
|
218
411
|
_wrapResource: () => undefined,
|
|
412
|
+
approval: noop,
|
|
413
|
+
toolOutcome: noop,
|
|
219
414
|
disabled: true
|
|
220
415
|
};
|
|
221
416
|
}
|
|
@@ -247,9 +442,14 @@ export function createAvowa({
|
|
|
247
442
|
if (evt.guardrail_blocked !== undefined && evt.guardrail_blocked !== null) {
|
|
248
443
|
payload.guardrail_blocked = !!evt.guardrail_blocked;
|
|
249
444
|
}
|
|
250
|
-
for (const k of ['guardrail', 'decision_logged', 'human_reviewed', 'rationale_present', 'ai_disclosed', 'uncertainty_flagged', 'fairness_checked', 'blocked_category', 'pii_redacted', 'grounded', 'refused', 'injection_blocked', 'output_validated', 'system_prompt_protected', 'rate_limited', 'tool_authorized', 'action_authorized', 'model_pinned', 'eval_score', 'agent_run', 'tool_called', 'autonomy_depth', 'action_class', 'approval_required', 'approved_by_human', 'action_blocked', 'action_logged', 'agent_run_key', 'tools_offered', 'tools_invoked', 'injection_suspected', 'pii_detected', 'error', 'fallback_model', 'retries', 'token_ceiling', 'provider_throttled', 'requested_model', 'stop_reason', 'structured_output', 'refusal_part', 'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'system_prompt_present', 'tool_choice', 'messages_user', 'messages_assistant', 'messages_tool', 'input_images', 'input_files', 'input_audio', 'streaming', 'response_format_type', 'prompt_chars', 'output_chars', 'client_max_retries', 'client_timeout_s', 'pii_families', 'injection_families', 'temperature', 'top_p', 'seed', 'choices_n', 'stop_sequences', 'parallel_tool_calls', 'store_requested', 'logprobs', 'service_tier_requested', 'metadata_present', 'end_user_id_present', 'reasoning_effort', 'thinking_enabled', 'system_fingerprint', 'service_tier', 'provider_filtered', 'provider_filter_categories', 'ttft_ms', 'http_status', 'provider_error_code', 'retry_after_s', 'provider_lib', 'node_version', 'app_region', 'app_region_source']) {
|
|
445
|
+
for (const k of ['guardrail', 'decision_logged', 'human_reviewed', 'rationale_present', 'ai_disclosed', 'uncertainty_flagged', 'fairness_checked', 'blocked_category', 'pii_redacted', 'grounded', 'refused', 'injection_blocked', 'output_validated', 'system_prompt_protected', 'rate_limited', 'tool_authorized', 'action_authorized', 'model_pinned', 'eval_score', 'agent_run', 'tool_called', 'autonomy_depth', 'action_class', 'approval_required', 'approved_by_human', 'action_blocked', 'action_logged', 'agent_run_key', 'tools_offered', 'tools_invoked', 'injection_suspected', 'pii_detected', 'error', 'fallback_model', 'retries', 'token_ceiling', 'provider_throttled', 'requested_model', 'stop_reason', 'structured_output', 'refusal_part', 'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'system_prompt_present', 'tool_choice', 'messages_user', 'messages_assistant', 'messages_tool', 'input_images', 'input_files', 'input_audio', 'streaming', 'response_format_type', 'prompt_chars', 'output_chars', 'client_max_retries', 'client_timeout_s', 'pii_families', 'injection_families', 'temperature', 'top_p', 'seed', 'choices_n', 'stop_sequences', 'parallel_tool_calls', 'store_requested', 'logprobs', 'service_tier_requested', 'metadata_present', 'end_user_id_present', 'reasoning_effort', 'thinking_enabled', 'system_fingerprint', 'service_tier', 'provider_filtered', 'provider_filter_categories', 'ttft_ms', 'http_status', 'provider_error_code', 'retry_after_s', 'provider_lib', 'node_version', 'app_region', 'app_region_source', 'tool_calls', 'tool_results', 'mcp_servers_offered', 'mcp_tools_invoked', 'mcp_hosts', 'mcp_hosts_invoked']) {
|
|
251
446
|
if (evt[k] !== undefined && evt[k] !== null) payload[k] = evt[k];
|
|
252
447
|
}
|
|
448
|
+
const ctx = AGENT.getStore() || {};
|
|
449
|
+
const name = evt.agent_name !== undefined && evt.agent_name !== null ? String(evt.agent_name).slice(0, 64) : ctx.name;
|
|
450
|
+
if (name) payload.agent_name = name;
|
|
451
|
+
const cref = customerRef(secret, evt.customer !== undefined && evt.customer !== null ? evt.customer : ctx.customer);
|
|
452
|
+
if (cref) payload.customer_ref = cref;
|
|
253
453
|
if (evt.endpoint) payload.endpoint = hostOf(evt.endpoint);
|
|
254
454
|
const scanP = evt.scanPrompt !== undefined && evt.scanPrompt !== null ? cap(evt.scanPrompt, 'tail') : null;
|
|
255
455
|
const scanO = evt.scanOutput !== undefined && evt.scanOutput !== null ? cap(evt.scanOutput, 'head') : null;
|
|
@@ -297,11 +497,58 @@ export function createAvowa({
|
|
|
297
497
|
const batch = pending.splice(0, BATCH_MAX);
|
|
298
498
|
if (pending.length) pendingTimer = setTimeout(flushPending, BATCH_WAIT_MS);
|
|
299
499
|
if (!batch.length) return;
|
|
300
|
-
sendEnvelope(batch.map(b => b.payload)).then(r => batch.forEach(b => b.resolve(r)), e => batch.forEach(b => b.reject(e)));
|
|
500
|
+
sendEnvelope(batch.filter(b => !b.payload._annotation).map(b => b.payload), batch.filter(b => b.payload._annotation).map(b => b.payload._annotation)).then(r => batch.forEach(b => b.resolve(r)), e => batch.forEach(b => b.reject(e)));
|
|
501
|
+
}
|
|
502
|
+
function annotate(ann) {
|
|
503
|
+
if (!key || !base) return Promise.resolve(null);
|
|
504
|
+
return enqueue({
|
|
505
|
+
_annotation: ann
|
|
506
|
+
}).catch(e => {
|
|
507
|
+
internalError('annotate', e);
|
|
508
|
+
return null;
|
|
509
|
+
});
|
|
301
510
|
}
|
|
302
|
-
|
|
511
|
+
const nowIso = () => new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
|
|
512
|
+
function approval(callId, approved, approverRole, {
|
|
513
|
+
approverType = 'unknown',
|
|
514
|
+
policyRef
|
|
515
|
+
} = {}) {
|
|
516
|
+
const ref = callRef(callId);
|
|
517
|
+
if (!ref) return Promise.resolve(null);
|
|
518
|
+
if (!APPROVER_TYPES.includes(approverType)) {
|
|
519
|
+
warnOnce('approvertype', `approval() approverType must be one of ${APPROVER_TYPES.join(', ')}; recorded as unknown.`);
|
|
520
|
+
approverType = 'unknown';
|
|
521
|
+
}
|
|
522
|
+
const ann = {
|
|
523
|
+
type: 'approval',
|
|
524
|
+
tool_call_ref: ref,
|
|
525
|
+
approved: !!approved,
|
|
526
|
+
approver_type: approverType,
|
|
527
|
+
at: nowIso()
|
|
528
|
+
};
|
|
529
|
+
const role = approverRole === undefined || approverRole === null ? null : String(approverRole).slice(0, 40);
|
|
530
|
+
if (role && LABEL_RX.test(role)) ann.approver_role = role;
|
|
531
|
+
const pol = policyRef === undefined || policyRef === null ? null : String(policyRef).slice(0, 64);
|
|
532
|
+
if (pol && LABEL_RX.test(pol)) ann.policy_ref = pol;
|
|
533
|
+
return annotate(ann);
|
|
534
|
+
}
|
|
535
|
+
function toolOutcome(callId, outcome) {
|
|
536
|
+
const ref = callRef(callId);
|
|
537
|
+
if (!ref) return Promise.resolve(null);
|
|
538
|
+
if (!TOOL_OUTCOMES.includes(outcome)) {
|
|
539
|
+
warnOnce('outcome', `toolOutcome() takes one of ${TOOL_OUTCOMES.join(', ')}; that outcome was not recorded.`);
|
|
540
|
+
return Promise.resolve(null);
|
|
541
|
+
}
|
|
542
|
+
return annotate({
|
|
543
|
+
type: 'outcome',
|
|
544
|
+
tool_call_ref: ref,
|
|
545
|
+
outcome,
|
|
546
|
+
at: nowIso()
|
|
547
|
+
});
|
|
548
|
+
}
|
|
549
|
+
async function sendEnvelope(events, annotations = []) {
|
|
303
550
|
const nonce = [...(globalThis.crypto && globalThis.crypto.getRandomValues ? globalThis.crypto.getRandomValues(new Uint8Array(12)) : (await import('node:crypto')).randomBytes(12))].map(b => b.toString(16).padStart(2, '0')).join('');
|
|
304
|
-
const
|
|
551
|
+
const envelope = {
|
|
305
552
|
schema: SCHEMA,
|
|
306
553
|
source: {
|
|
307
554
|
kind: 'runtime',
|
|
@@ -311,7 +558,9 @@ export function createAvowa({
|
|
|
311
558
|
sent_at: new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),
|
|
312
559
|
nonce,
|
|
313
560
|
events
|
|
314
|
-
}
|
|
561
|
+
};
|
|
562
|
+
if (annotations.length) envelope.annotations = annotations;
|
|
563
|
+
const body = JSON.stringify(envelope);
|
|
315
564
|
const headers = {
|
|
316
565
|
'Content-Type': 'application/json',
|
|
317
566
|
'X-Ingest-Key': key,
|
|
@@ -424,8 +673,12 @@ export function createAvowa({
|
|
|
424
673
|
audio: 0
|
|
425
674
|
};
|
|
426
675
|
let chars = 0;
|
|
676
|
+
try {
|
|
677
|
+
roles.assistant += modelTurns(msgs).filter(([mt]) => mt).length - msgs.filter(m => g(m, 'role') === 'assistant').length;
|
|
678
|
+
} catch {}
|
|
427
679
|
for (const m of msgs) {
|
|
428
680
|
if (!m) continue;
|
|
681
|
+
if (RESULT_ITEMS.has(m.type)) roles.tool++;
|
|
429
682
|
if (m.role === 'system' || m.role === 'developer') system = true;else if (m.role in roles) roles[m.role]++;
|
|
430
683
|
if (typeof m.content === 'string') chars += m.content.length;else if (Array.isArray(m.content)) {
|
|
431
684
|
for (const b of m.content) {
|
|
@@ -607,7 +860,7 @@ export function createAvowa({
|
|
|
607
860
|
if (n) invoked.push(String(n).slice(0, 64));
|
|
608
861
|
}
|
|
609
862
|
for (const it of resp.output || []) {
|
|
610
|
-
if (it && it.type === 'function_call' && it.name) invoked.push(String(it.name).slice(0, 64));
|
|
863
|
+
if (it && (it.type === 'function_call' || it.type === 'custom_tool_call') && it.name) invoked.push(String(it.name).slice(0, 64));
|
|
611
864
|
}
|
|
612
865
|
}
|
|
613
866
|
} catch {}
|
|
@@ -615,6 +868,48 @@ export function createAvowa({
|
|
|
615
868
|
f.tools_invoked = invoked;
|
|
616
869
|
seen.push('tools_invoked');
|
|
617
870
|
}
|
|
871
|
+
const calls = toolCalls(resp);
|
|
872
|
+
if (calls.length) {
|
|
873
|
+
f.tool_calls = calls;
|
|
874
|
+
seen.push('tool_calls');
|
|
875
|
+
}
|
|
876
|
+
const history = params && (Array.isArray(params.messages) ? params.messages : Array.isArray(params.input) || typeof params.input === 'string' ? params.input : null);
|
|
877
|
+
const results = toolResults(history);
|
|
878
|
+
if (results.length) {
|
|
879
|
+
f.tool_results = results;
|
|
880
|
+
seen.push('tool_results');
|
|
881
|
+
}
|
|
882
|
+
const mcp = mcpFacts(params, resp);
|
|
883
|
+
Object.assign(f, mcp);
|
|
884
|
+
seen.push(...Object.keys(mcp));
|
|
885
|
+
if (offered.length) {
|
|
886
|
+
let depth = autonomyDepth(history);
|
|
887
|
+
let rk = runKey(history, secret);
|
|
888
|
+
if (params.previous_response_id) {
|
|
889
|
+
const parent = CHAIN.get(String(params.previous_response_id));
|
|
890
|
+
if (!parent) {
|
|
891
|
+
depth = null;
|
|
892
|
+
rk = null;
|
|
893
|
+
} else {
|
|
894
|
+
rk = parent[0];
|
|
895
|
+
depth = parent[1] === null || depth === null ? null : parent[1] + depth;
|
|
896
|
+
}
|
|
897
|
+
} else if (params.conversation) {
|
|
898
|
+
depth = null;
|
|
899
|
+
rk = null;
|
|
900
|
+
}
|
|
901
|
+
if (depth !== null) {
|
|
902
|
+
f.autonomy_depth = depth;
|
|
903
|
+
seen.push('autonomy_depth');
|
|
904
|
+
}
|
|
905
|
+
if (rk) {
|
|
906
|
+
Object.assign(f, {
|
|
907
|
+
agent_run_key: rk
|
|
908
|
+
});
|
|
909
|
+
seen.push('agent_run_key');
|
|
910
|
+
}
|
|
911
|
+
if (resp.id && Array.isArray(resp.output)) chainPut(resp.id, rk, depth === null ? null : depth + (calls.length ? 1 : 0));
|
|
912
|
+
}
|
|
618
913
|
return [f, seen];
|
|
619
914
|
}
|
|
620
915
|
function outputText(resp, kind) {
|
|
@@ -631,6 +926,10 @@ export function createAvowa({
|
|
|
631
926
|
stop = null,
|
|
632
927
|
size = 0,
|
|
633
928
|
ttft = null;
|
|
929
|
+
let completed = null,
|
|
930
|
+
usage = null;
|
|
931
|
+
const chatCalls = new Map(),
|
|
932
|
+
blocks = [];
|
|
634
933
|
const started = Date.now();
|
|
635
934
|
const text = [];
|
|
636
935
|
const keep = t => {
|
|
@@ -647,12 +946,38 @@ export function createAvowa({
|
|
|
647
946
|
if (t === 'message_delta' && c.delta && c.delta.stop_reason) stop = c.delta.stop_reason;
|
|
648
947
|
if (t === 'content_block_delta' && c.delta && c.delta.text) keep(c.delta.text);
|
|
649
948
|
if (t.endsWith('output_text.delta') && typeof c.delta === 'string') keep(c.delta);
|
|
650
|
-
if (t === 'response.completed' && c.response
|
|
949
|
+
if (t === 'response.completed' && c.response) {
|
|
950
|
+
completed = c.response;
|
|
951
|
+
if (c.response.model) model = c.response.model;
|
|
952
|
+
}
|
|
953
|
+
if (t === 'content_block_start' && c.content_block && c.content_block.type === 'tool_use') blocks.push({
|
|
954
|
+
type: 'tool_use',
|
|
955
|
+
id: c.content_block.id,
|
|
956
|
+
name: c.content_block.name
|
|
957
|
+
});
|
|
958
|
+
if (t === 'message_start' && c.message && c.message.usage) usage = {
|
|
959
|
+
...(usage || {}),
|
|
960
|
+
input_tokens: c.message.usage.input_tokens
|
|
961
|
+
};
|
|
962
|
+
if (t === 'message_delta' && c.usage && c.usage.output_tokens != null) usage = {
|
|
963
|
+
...(usage || {}),
|
|
964
|
+
output_tokens: c.usage.output_tokens
|
|
965
|
+
};
|
|
651
966
|
if (!t && c.model) model = c.model;
|
|
967
|
+
if (!t && c.usage && c.usage.prompt_tokens != null) usage = {
|
|
968
|
+
prompt_tokens: c.usage.prompt_tokens,
|
|
969
|
+
completion_tokens: c.usage.completion_tokens
|
|
970
|
+
};
|
|
652
971
|
const ch = c.choices && c.choices[0];
|
|
653
972
|
if (ch) {
|
|
654
973
|
if (ch.finish_reason) stop = ch.finish_reason;
|
|
655
974
|
if (ch.delta && typeof ch.delta.content === 'string') keep(ch.delta.content);
|
|
975
|
+
for (const tc of ch.delta && ch.delta.tool_calls || []) {
|
|
976
|
+
const slot = chatCalls.get(tc.index || 0) || [null, null];
|
|
977
|
+
if (tc.id) slot[0] = tc.id;
|
|
978
|
+
if (tc.function && tc.function.name) slot[1] = tc.function.name;
|
|
979
|
+
chatCalls.set(tc.index || 0, slot);
|
|
980
|
+
}
|
|
656
981
|
}
|
|
657
982
|
} catch {}
|
|
658
983
|
};
|
|
@@ -661,20 +986,30 @@ export function createAvowa({
|
|
|
661
986
|
if (done) return;
|
|
662
987
|
done = true;
|
|
663
988
|
const all = text.join('');
|
|
664
|
-
const
|
|
989
|
+
const calls = [...chatCalls.entries()].sort((a, b) => a[0] - b[0]).filter(([, [, n]]) => n).map(([, [id, name]]) => ({
|
|
990
|
+
id,
|
|
991
|
+
type: 'function',
|
|
992
|
+
function: {
|
|
993
|
+
name
|
|
994
|
+
}
|
|
995
|
+
}));
|
|
996
|
+
const summary = completed ? completed : kind === 'anthropic' ? {
|
|
665
997
|
model,
|
|
666
998
|
stop_reason: stop,
|
|
999
|
+
usage,
|
|
667
1000
|
content: [{
|
|
668
1001
|
type: 'text',
|
|
669
1002
|
text: all
|
|
670
|
-
}]
|
|
1003
|
+
}, ...blocks]
|
|
671
1004
|
} : {
|
|
672
1005
|
model,
|
|
673
1006
|
output_text: all,
|
|
1007
|
+
usage,
|
|
674
1008
|
choices: [{
|
|
675
1009
|
finish_reason: stop,
|
|
676
1010
|
message: {
|
|
677
|
-
content: all
|
|
1011
|
+
content: all,
|
|
1012
|
+
tool_calls: calls.length ? calls : undefined
|
|
678
1013
|
}
|
|
679
1014
|
}]
|
|
680
1015
|
};
|
|
@@ -750,7 +1085,8 @@ export function createAvowa({
|
|
|
750
1085
|
facts.output_chars = out.length;
|
|
751
1086
|
seen.push('output_chars');
|
|
752
1087
|
}
|
|
753
|
-
|
|
1088
|
+
if (resp && typeof resp.model === 'string' && resp.model) seen.push('model');
|
|
1089
|
+
seen.push('endpoint', 'latency_ms');
|
|
754
1090
|
if (err) seen.push('error');
|
|
755
1091
|
if (opts.scan !== false) seen.push('pii_detected', 'injection_suspected', 'pii_families', 'injection_families');
|
|
756
1092
|
const prompt = kind === 'anthropic' ? textOfMessages(params.messages) : textOfMessages(params.messages || (Array.isArray(params.input) ? params.input : [params.input]));
|
|
@@ -823,12 +1159,16 @@ export function createAvowa({
|
|
|
823
1159
|
region
|
|
824
1160
|
}, original.bind(resource));
|
|
825
1161
|
}
|
|
826
|
-
|
|
1162
|
+
const api = {
|
|
827
1163
|
capture,
|
|
828
1164
|
track,
|
|
829
1165
|
instrumentOpenAI,
|
|
830
1166
|
instrumentAnthropic,
|
|
831
|
-
_wrapResource
|
|
1167
|
+
_wrapResource,
|
|
1168
|
+
approval,
|
|
1169
|
+
toolOutcome
|
|
832
1170
|
};
|
|
1171
|
+
if (!DEFAULT && key) DEFAULT = api;
|
|
1172
|
+
return api;
|
|
833
1173
|
}
|
|
834
1174
|
export default createAvowa;
|
package/cli.js
CHANGED
|
@@ -9,12 +9,14 @@
|
|
|
9
9
|
* init --dry-run show what init would do; changes nothing, uses no token
|
|
10
10
|
* status what is wired, what is covered, does the server know this key
|
|
11
11
|
* doctor the server check only (sends no signal)
|
|
12
|
+
* ref <tool-call-id> the reference Avowa shows for a provider tool call id (toolu_..., call_...)
|
|
13
|
+
* ref --find <ref> <file>... find the tool call behind a reference in your own logs (local only)
|
|
12
14
|
*/
|
|
13
15
|
import fs from 'node:fs'
|
|
14
16
|
import path from 'node:path'
|
|
15
17
|
import crypto from 'node:crypto'
|
|
16
18
|
import readline from 'node:readline'
|
|
17
|
-
import { checkedBase, makeToken, readToken, SDK_VERSION as VERSION } from './avowa-runtime.js'
|
|
19
|
+
import { checkedBase, makeToken, readToken, callRef, SDK_VERSION as VERSION } from './avowa-runtime.js'
|
|
18
20
|
import { loadEnv } from './env.js'
|
|
19
21
|
|
|
20
22
|
const REGISTER = '@avowa/runtime/register'
|
|
@@ -23,6 +25,8 @@ const USAGE = `usage: npx @avowa/runtime <command>
|
|
|
23
25
|
init <setup-token> [--api https://api.avowa.ai] [--dry-run] [--yes]
|
|
24
26
|
status
|
|
25
27
|
doctor
|
|
28
|
+
ref <tool-call-id>... the reference Avowa shows for a provider tool call id
|
|
29
|
+
ref --find <ref> <file>... find that call in your own logs ("-" reads stdin); nothing is sent
|
|
26
30
|
|
|
27
31
|
Generate the setup token in the Avowa console: Connections, Runtime SDK.
|
|
28
32
|
In production set two variables and change nothing else:
|
|
@@ -96,12 +100,22 @@ function ask(question) {
|
|
|
96
100
|
async function redeem(token, api) {
|
|
97
101
|
const [base, problem] = checkedBase(api)
|
|
98
102
|
if (problem) return [null, problem.replace('AVOWA_BASE_URL', '--api') + '.']
|
|
103
|
+
// One retry: in a container that has just started, the very first connection can fail once
|
|
104
|
+
// (seen 2026-11-17 in a fresh node:22-slim) and succeed a second later. The token is spent only
|
|
105
|
+
// by a request the server answers, so retrying a request that never arrived is safe.
|
|
99
106
|
let r
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
107
|
+
for (let attempt = 1; ; attempt++) {
|
|
108
|
+
try {
|
|
109
|
+
r = await fetch(base + '/public/sdk/setup', { method: 'POST', body: JSON.stringify({ token }),
|
|
110
|
+
headers: { 'Content-Type': 'application/json', 'User-Agent': 'avowa-runtime-js (+https://avowa.ai)' },
|
|
111
|
+
signal: AbortSignal.timeout(15000) })
|
|
112
|
+
break
|
|
113
|
+
} catch (e) {
|
|
114
|
+
if (attempt < 2) { await new Promise((ok) => setTimeout(ok, 1500)); continue }
|
|
115
|
+
const why = (e.cause && (e.cause.code || e.cause.message)) || e.name
|
|
116
|
+
return [null, `Could not reach ${base} (${why}). Check the address and that this machine can reach it, or pass --api with your Avowa API URL. The setup token was not used.`]
|
|
117
|
+
}
|
|
118
|
+
}
|
|
105
119
|
if (r.status === 404) return [null, 'That setup token is invalid, expired (24h) or already used. Generate a new one in the console.']
|
|
106
120
|
if (!r.ok) return [null, `${base} answered HTTP ${r.status}.`]
|
|
107
121
|
const creds = await r.json()
|
|
@@ -188,7 +202,7 @@ async function reportSetup(key, secret, base, pkg, isWired) {
|
|
|
188
202
|
if (!who.signature_ok) return 'server check : the secret did NOT verify. Run `npx @avowa/runtime status`.'
|
|
189
203
|
if (!who.capture_allowed) return "server check : key accepted, but this workspace's plan does not allow capture yet"
|
|
190
204
|
return 'server check : key and signature accepted (your console card now shows this step done)'
|
|
191
|
-
} catch (e) { return `server check : could not
|
|
205
|
+
} catch (e) { return `server check : could not reach ${base} (${e.name}). This is the address in your credential; AVOWA_BASE_URL overrides it. Run \`npx @avowa/runtime status\` for more.` }
|
|
192
206
|
}
|
|
193
207
|
|
|
194
208
|
// Asks the server who this key is. Sends no signal: a synthetic one would show on the trust
|
|
@@ -227,7 +241,7 @@ async function doctor() {
|
|
|
227
241
|
ok = ok && Math.abs(s) < 300
|
|
228
242
|
}
|
|
229
243
|
console.log(`last event : ${who.last_event_at || 'never'} (${who.events_total || 0} total)`)
|
|
230
|
-
console.log('\
|
|
244
|
+
console.log('\nThis check sent no signal.' + (ok ? '' : ' Fix the lines marked above, then run again.'))
|
|
231
245
|
return ok ? 0 : 1
|
|
232
246
|
}
|
|
233
247
|
|
|
@@ -246,10 +260,36 @@ async function status() {
|
|
|
246
260
|
return doctor()
|
|
247
261
|
}
|
|
248
262
|
|
|
263
|
+
// Avowa names a tool call by a hash of the provider's id. This goes the other way, locally: id ->
|
|
264
|
+
// reference, or a reference -> the line in your logs holding its id. Prints file:line and the id only.
|
|
265
|
+
async function ref(args) {
|
|
266
|
+
if (!args.length) { console.error('usage: npx @avowa/runtime ref <tool-call-id>... | ref --find <ref> <file>...'); return 2 }
|
|
267
|
+
if (args[0] !== '--find') { for (const id of args) console.log(`${callRef(id)} ${id}`); return 0 }
|
|
268
|
+
if (args.length < 3) { console.error('usage: npx @avowa/runtime ref --find <ref> <file>... ("-" reads stdin)'); return 2 }
|
|
269
|
+
const want = args[1].trim().toLowerCase()
|
|
270
|
+
const tok = /[A-Za-z0-9][A-Za-z0-9_-]{5,127}/g
|
|
271
|
+
let found = 0
|
|
272
|
+
for (const p of args.slice(2)) {
|
|
273
|
+
let stream
|
|
274
|
+
try { stream = p === '-' ? process.stdin : fs.createReadStream(p, { encoding: 'utf8' }) } catch (e) { console.error(`${p}: ${e.message}`); continue }
|
|
275
|
+
const rl = readline.createInterface({ input: stream, crlfDelay: Infinity })
|
|
276
|
+
let n = 0
|
|
277
|
+
try {
|
|
278
|
+
for await (const line of rl) {
|
|
279
|
+
n++
|
|
280
|
+
for (const t of new Set(line.match(tok) || [])) if (callRef(t) === want) { console.log(`${p}:${n} ${t}`); found++ }
|
|
281
|
+
}
|
|
282
|
+
} catch (e) { console.error(`${p}: ${e.message}`) }
|
|
283
|
+
}
|
|
284
|
+
if (!found) console.error(`no tool call id in those files has reference ${want}`)
|
|
285
|
+
return found ? 0 : 1
|
|
286
|
+
}
|
|
287
|
+
|
|
249
288
|
const [cmd, ...rest] = process.argv.slice(2)
|
|
250
289
|
let code
|
|
251
290
|
if (cmd === 'init') code = await init(rest)
|
|
252
291
|
else if (cmd === 'status') code = await status()
|
|
253
292
|
else if (cmd === 'doctor') code = await doctor()
|
|
293
|
+
else if (cmd === 'ref') code = await ref(rest)
|
|
254
294
|
else { console.error(USAGE); code = cmd && !['-h', '--help', 'help'].includes(cmd) ? 2 : (cmd ? 0 : 2) }
|
|
255
295
|
process.exitCode = code
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@avowa/runtime",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.13.1",
|
|
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",
|