@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 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.12.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
- async function sendEnvelope(events) {
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 body = JSON.stringify({
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 && c.response.model) model = c.response.model;
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 summary = kind === 'anthropic' ? {
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
- seen.push('model', 'endpoint', 'latency_ms');
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
- return {
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
- try {
101
- r = await fetch(base + '/public/sdk/setup', { method: 'POST', body: JSON.stringify({ token }),
102
- headers: { 'Content-Type': 'application/json', 'User-Agent': 'avowa-runtime-js (+https://avowa.ai)' },
103
- signal: AbortSignal.timeout(15000) })
104
- } catch (e) { return [null, `Could not reach ${base} (${e.name}). Pass --api with your Avowa API URL.`] }
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 confirm (${e.name}). Run \`npx @avowa/runtime status\` to see why.` }
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('\nNo signal was sent.' + (ok ? '' : ' Fix the lines marked above, then run again.'))
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.12.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",