melchizedek-agents 1.8.0 → 1.10.0

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.
Files changed (51) hide show
  1. package/CHANGELOG.md +131 -1
  2. package/DOCUMENTATION.md +66 -4
  3. package/README.md +2 -0
  4. package/config/agents/syndicate.schema.json +69 -0
  5. package/config/agents/syndicateSchema.yaml +17 -0
  6. package/db/hardening.sql +3 -1
  7. package/db/migrations/0016_span_tree.sql +52 -0
  8. package/db/migrations/0017_cache_pricing.sql +146 -0
  9. package/db/migrations/0018_queue_view.sql +82 -0
  10. package/db/telemetry.sql +36 -8
  11. package/dist/lib/a2a/app.d.ts +26 -4
  12. package/dist/lib/a2a/app.js +41 -6
  13. package/dist/lib/a2a/executor.d.ts +28 -1
  14. package/dist/lib/a2a/executor.js +65 -2
  15. package/dist/lib/a2a/feedback.d.ts +121 -0
  16. package/dist/lib/a2a/feedback.js +219 -0
  17. package/dist/lib/a2a/policy.d.ts +55 -5
  18. package/dist/lib/a2a/policy.js +56 -12
  19. package/dist/lib/compile.d.ts +2 -0
  20. package/dist/lib/compile.js +2 -0
  21. package/dist/lib/compileNative.js +2 -0
  22. package/dist/lib/index.d.ts +5 -2
  23. package/dist/lib/index.js +1 -0
  24. package/dist/lib/loadSyndicate.d.ts +14 -0
  25. package/dist/lib/loadSyndicate.js +19 -1
  26. package/dist/lib/memory/providers.js +7 -3
  27. package/dist/lib/observability/lineage.d.ts +19 -0
  28. package/dist/lib/observability/lineage.js +31 -0
  29. package/dist/lib/observability/metadata.d.ts +69 -0
  30. package/dist/lib/observability/metadata.js +153 -0
  31. package/dist/lib/observability/otlpFilter.js +1 -0
  32. package/dist/lib/observability/supabaseSpanExporter.d.ts +31 -2
  33. package/dist/lib/observability/supabaseSpanExporter.js +45 -6
  34. package/dist/lib/observability/tracer.d.ts +17 -1
  35. package/dist/lib/observability/tracer.js +61 -3
  36. package/dist/lib/project.js +1 -1
  37. package/dist/lib/runtime/native/compaction.js +7 -3
  38. package/dist/lib/runtime/native/request.d.ts +2 -0
  39. package/dist/lib/runtime/native/step.js +1 -1
  40. package/dist/lib/runtime/native/telemetry.d.ts +10 -3
  41. package/dist/lib/runtime/native/telemetry.js +49 -4
  42. package/dist/lib/runtime/syndicateTurn.js +5 -1
  43. package/dist/lib/storage/postgres/index.d.ts +10 -0
  44. package/dist/lib/storage/postgres/index.js +6 -1
  45. package/dist/lib/syndicateSchema.d.ts +5 -0
  46. package/dist/lib/syndicateSchema.js +13 -0
  47. package/dist/lib/tools/taskTools.d.ts +6 -0
  48. package/dist/lib/tools/taskTools.js +24 -5
  49. package/dist/lib/workflow/toolNode.d.ts +1 -0
  50. package/dist/lib/workflow/toolNode.js +1 -1
  51. package/package.json +5 -4
@@ -0,0 +1,69 @@
1
+ /**
2
+ * lib/observability/metadata.ts — labels a turn carries into the ledger as
3
+ * `meta.<key>` root-span attributes (ADR 0141): static ones from the YAML
4
+ * (`metadata:` on the syndicate, and on an agent as `meta.agent.<key>` on its
5
+ * agent span), and per-request ones an A2A caller sends (the message's
6
+ * `metadata` object and the `X-Melch-Meta-*` headers).
7
+ *
8
+ * The limits are one set wherever metadata comes from: a key is letters,
9
+ * digits and `_ . : -` (at most 64, not starting with a punctuation mark), a
10
+ * value is a string (at most 256 characters), a finite number or a boolean,
11
+ * and a turn carries at most 32 keys. A value shaped like a credential
12
+ * (REDACTION_PATTERNS.secret) is never kept: metadata is a label, and a key
13
+ * pasted into one is dropped with a warning that names the key, never the
14
+ * value. String values then pass through the telemetry redactor in force.
15
+ */
16
+ import type { Redactor } from './redact.ts';
17
+ export type MetadataValue = string | number | boolean;
18
+ export type Metadata = Record<string, MetadataValue>;
19
+ /** The attribute prefix: `meta.<key>` on the root span, `meta.agent.<key>` on an agent span. */
20
+ export declare const META_PREFIX = "meta.";
21
+ export declare const META_AGENT_PREFIX = "meta.agent.";
22
+ export declare const MAX_META_KEYS = 32;
23
+ export declare const MAX_META_KEY_CHARS = 64;
24
+ export declare const MAX_META_VALUE_CHARS = 256;
25
+ /** A metadata key: the same rule the desktop app's filters check before a key reaches SQL. */
26
+ export declare const META_KEY: RegExp;
27
+ /** The request header family: `X-Melch-Meta-<key>: <value>` (Node lowercases header names, so the key arrives lowercase). */
28
+ export declare const META_HEADER_PREFIX = "x-melch-meta-";
29
+ /** True when the value looks like a credential (the redactor's `secret` pattern). */
30
+ export declare function isSecretShaped(value: string): boolean;
31
+ /** Why one entry is not metadata, or undefined when it is. Never quotes the value. */
32
+ export declare function metadataEntryProblem(key: string, value: unknown): string | undefined;
33
+ /**
34
+ * The entries whose value looks like a credential, dropped: the rest, and
35
+ * one warning per dropped key (`where` names the place, e.g. a file and key path).
36
+ */
37
+ export declare function dropSecretMetadata(meta: Metadata | undefined, where: string, warn: (message: string) => void): Metadata | undefined;
38
+ /** Metadata as span attributes under `prefix`, string values through the telemetry redactor in force. */
39
+ export declare function metaAttributes(meta: Metadata | undefined, prefix?: string, redactor?: Redactor | undefined): Record<string, MetadataValue>;
40
+ /**
41
+ * The `X-Melch-Meta-*` headers as metadata, or why the request is refused.
42
+ * A header is an explicit act of this API, so a malformed one is refused
43
+ * rather than dropped (as X-Surface is): a key outside the rule, a value
44
+ * over the limit, more than 32 of them. A credential-shaped value is
45
+ * dropped, its key listed in `dropped`, for the caller to warn about once
46
+ * the request is authenticated (an anonymous request must not write logs).
47
+ */
48
+ export declare function headerMetadata(headers: Record<string, string | string[] | undefined>): {
49
+ meta?: Metadata;
50
+ dropped?: string[];
51
+ error?: string;
52
+ };
53
+ /** The warning for a header `headerMetadata` dropped: the key, never the value. */
54
+ export declare const droppedHeaderWarning: (key: string) => string;
55
+ /**
56
+ * A request's metadata from its sources, in precedence order (the first to
57
+ * name a key wins): only scalar entries that pass the rules, never a key in
58
+ * `reserved` (the YAML's own: a caller cannot relabel an operator's
59
+ * metadata), never one starting `agent.`, at most `room` keys. A2A's
60
+ * `Message.metadata` is shared by protocol extensions, so an entry that is
61
+ * not metadata (a nested object, a long value, a key outside the rule) is
62
+ * skipped, not refused; the warning counts what was skipped and names valid
63
+ * keys only.
64
+ */
65
+ export declare function requestMetadata(sources: ReadonlyArray<unknown>, options?: {
66
+ reserved?: ReadonlySet<string>;
67
+ room?: number;
68
+ warn?: (message: string) => void;
69
+ }): Metadata;
@@ -0,0 +1,153 @@
1
+ /**
2
+ * lib/observability/metadata.ts — labels a turn carries into the ledger as
3
+ * `meta.<key>` root-span attributes (ADR 0141): static ones from the YAML
4
+ * (`metadata:` on the syndicate, and on an agent as `meta.agent.<key>` on its
5
+ * agent span), and per-request ones an A2A caller sends (the message's
6
+ * `metadata` object and the `X-Melch-Meta-*` headers).
7
+ *
8
+ * The limits are one set wherever metadata comes from: a key is letters,
9
+ * digits and `_ . : -` (at most 64, not starting with a punctuation mark), a
10
+ * value is a string (at most 256 characters), a finite number or a boolean,
11
+ * and a turn carries at most 32 keys. A value shaped like a credential
12
+ * (REDACTION_PATTERNS.secret) is never kept: metadata is a label, and a key
13
+ * pasted into one is dropped with a warning that names the key, never the
14
+ * value. String values then pass through the telemetry redactor in force.
15
+ */
16
+ import { REDACTION_PATTERNS, telemetryRedactor } from './redact.js';
17
+ /** The attribute prefix: `meta.<key>` on the root span, `meta.agent.<key>` on an agent span. */
18
+ export const META_PREFIX = 'meta.';
19
+ export const META_AGENT_PREFIX = 'meta.agent.';
20
+ export const MAX_META_KEYS = 32;
21
+ export const MAX_META_KEY_CHARS = 64;
22
+ export const MAX_META_VALUE_CHARS = 256;
23
+ /** A metadata key: the same rule the desktop app's filters check before a key reaches SQL. */
24
+ export const META_KEY = /^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}$/;
25
+ /** The request header family: `X-Melch-Meta-<key>: <value>` (Node lowercases header names, so the key arrives lowercase). */
26
+ export const META_HEADER_PREFIX = 'x-melch-meta-';
27
+ /** True when the value looks like a credential (the redactor's `secret` pattern). */
28
+ export function isSecretShaped(value) {
29
+ // A fresh, non-global copy: the shared pattern carries the `g` flag, whose lastIndex would make .test() stateful.
30
+ return new RegExp(REDACTION_PATTERNS.secret.source).test(value);
31
+ }
32
+ /** Why one entry is not metadata, or undefined when it is. Never quotes the value. */
33
+ export function metadataEntryProblem(key, value) {
34
+ if (!META_KEY.test(key))
35
+ return `a metadata key is letters, digits and _ . : - (at most ${MAX_META_KEY_CHARS}, not starting with . : -)`;
36
+ if (typeof value === 'string') {
37
+ if (value.length > MAX_META_VALUE_CHARS)
38
+ return `metadata.${key} is longer than ${MAX_META_VALUE_CHARS} characters`;
39
+ return undefined;
40
+ }
41
+ if (typeof value === 'number')
42
+ return Number.isFinite(value) ? undefined : `metadata.${key} is not a finite number`;
43
+ if (typeof value === 'boolean')
44
+ return undefined;
45
+ return `metadata.${key} must be a string, a number or a boolean`;
46
+ }
47
+ /**
48
+ * The entries whose value looks like a credential, dropped: the rest, and
49
+ * one warning per dropped key (`where` names the place, e.g. a file and key path).
50
+ */
51
+ export function dropSecretMetadata(meta, where, warn) {
52
+ if (!meta)
53
+ return meta;
54
+ let out;
55
+ for (const [key, value] of Object.entries(meta)) {
56
+ if (typeof value === 'string' && isSecretShaped(value)) {
57
+ out ??= { ...meta };
58
+ delete out[key];
59
+ warn(`⚠ ${where}.${key} looks like a key or token and is dropped: metadata is a label, never a credential.`);
60
+ }
61
+ }
62
+ return out ?? meta;
63
+ }
64
+ /** Metadata as span attributes under `prefix`, string values through the telemetry redactor in force. */
65
+ export function metaAttributes(meta, prefix = META_PREFIX, redactor = telemetryRedactor()) {
66
+ const out = {};
67
+ for (const [key, value] of Object.entries(meta ?? {})) {
68
+ if (metadataEntryProblem(key, value) || (typeof value === 'string' && isSecretShaped(value)))
69
+ continue;
70
+ out[`${prefix}${key}`] = typeof value === 'string' && redactor ? redactor(value) : value;
71
+ }
72
+ return out;
73
+ }
74
+ /**
75
+ * The `X-Melch-Meta-*` headers as metadata, or why the request is refused.
76
+ * A header is an explicit act of this API, so a malformed one is refused
77
+ * rather than dropped (as X-Surface is): a key outside the rule, a value
78
+ * over the limit, more than 32 of them. A credential-shaped value is
79
+ * dropped, its key listed in `dropped`, for the caller to warn about once
80
+ * the request is authenticated (an anonymous request must not write logs).
81
+ */
82
+ export function headerMetadata(headers) {
83
+ const meta = {};
84
+ const dropped = [];
85
+ let count = 0;
86
+ for (const [name, raw] of Object.entries(headers)) {
87
+ if (!name.toLowerCase().startsWith(META_HEADER_PREFIX) || raw === undefined)
88
+ continue;
89
+ const key = name.slice(META_HEADER_PREFIX.length).toLowerCase();
90
+ const value = Array.isArray(raw) ? raw.join(', ') : raw;
91
+ const problem = metadataEntryProblem(key, value);
92
+ if (problem)
93
+ return { error: `Invalid X-Melch-Meta-* header: ${problem.replace(/^metadata\.[^ ]+/, 'its value')}` };
94
+ if (key.startsWith('agent.'))
95
+ return { error: 'Invalid X-Melch-Meta-* header: keys starting "agent." are reserved for agent spans' };
96
+ if (++count > MAX_META_KEYS)
97
+ return { error: `Too many X-Melch-Meta-* headers: at most ${MAX_META_KEYS}` };
98
+ if (isSecretShaped(value)) {
99
+ dropped.push(key);
100
+ continue;
101
+ }
102
+ meta[key] = value;
103
+ }
104
+ return count ? { meta, ...(dropped.length ? { dropped } : {}) } : {};
105
+ }
106
+ /** The warning for a header `headerMetadata` dropped: the key, never the value. */
107
+ export const droppedHeaderWarning = (key) => `⚠ X-Melch-Meta-${key} looks like a key or token and is dropped: metadata is a label, never a credential.`;
108
+ /**
109
+ * A request's metadata from its sources, in precedence order (the first to
110
+ * name a key wins): only scalar entries that pass the rules, never a key in
111
+ * `reserved` (the YAML's own: a caller cannot relabel an operator's
112
+ * metadata), never one starting `agent.`, at most `room` keys. A2A's
113
+ * `Message.metadata` is shared by protocol extensions, so an entry that is
114
+ * not metadata (a nested object, a long value, a key outside the rule) is
115
+ * skipped, not refused; the warning counts what was skipped and names valid
116
+ * keys only.
117
+ */
118
+ export function requestMetadata(sources, options = {}) {
119
+ const room = Math.max(0, Math.min(MAX_META_KEYS, options.room ?? MAX_META_KEYS));
120
+ const out = {};
121
+ let kept = 0;
122
+ let skipped = 0;
123
+ let overflow = 0;
124
+ for (const source of sources) {
125
+ if (!source || typeof source !== 'object' || Array.isArray(source))
126
+ continue;
127
+ for (const [key, value] of Object.entries(source)) {
128
+ if (Object.prototype.hasOwnProperty.call(out, key))
129
+ continue;
130
+ if (options.reserved?.has(key))
131
+ continue;
132
+ if (metadataEntryProblem(key, value) || key.startsWith('agent.')) {
133
+ skipped++;
134
+ continue;
135
+ }
136
+ if (typeof value === 'string' && isSecretShaped(value)) {
137
+ options.warn?.(`⚠ Request metadata ${key} looks like a key or token and is dropped: metadata is a label, never a credential.`);
138
+ continue;
139
+ }
140
+ if (kept >= room) {
141
+ overflow++;
142
+ continue;
143
+ }
144
+ out[key] = value;
145
+ kept++;
146
+ }
147
+ }
148
+ if (skipped)
149
+ options.warn?.(`Request metadata: ${skipped} entr${skipped === 1 ? 'y is' : 'ies are'} not metadata (a key outside [A-Za-z0-9_.:-]{1,64}, a value that is not a short string, number or boolean) and skipped.`);
150
+ if (overflow)
151
+ options.warn?.(`Request metadata: ${overflow} key(s) over the limit of ${MAX_META_KEYS} per turn skipped.`);
152
+ return out;
153
+ }
@@ -27,6 +27,7 @@ export const CONTENT_ATTRIBUTES = new Set([
27
27
  'llm.thinking',
28
28
  'llm.error_message',
29
29
  'tool.args',
30
+ 'tool.result',
30
31
  'tool.data_gathered',
31
32
  ]);
32
33
  const CONTENT_PREFIXES = ['llm.payload.'];
@@ -13,7 +13,11 @@
13
13
  * tool calls WITH their responses, the ids that join it to
14
14
  * the session (session_id, invocation_id) and the task,
15
15
  * and provenance (config_hash, engine_version).
16
- * adk_telemetry one row per span — llm.request and root spans, raw.
16
+ * adk_telemetry one row per span the ledger keeps — the turn's root, each
17
+ * agent run, model step and provider call, tool call,
18
+ * script run and call, workflow walk and node run — each
19
+ * with its parent among them and its kind, so a turn's
20
+ * span tree is stored (ADR 0139).
17
21
  * adk_payloads full request/response per model call, captured by
18
22
  * POLICY and expiring. ADK's own call_llm spans carry the
19
23
  * assembled prompt and raw response, and the native
@@ -37,6 +41,7 @@
37
41
  * payloads or none, and a re-run of the same policy keeps the same set.
38
42
  */
39
43
  import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
44
+ import type { LedgerSpanKind } from './lineage.ts';
40
45
  /** Row shape for adk_telemetry (raw spans). */
41
46
  export interface TelemetryRow {
42
47
  ts: string;
@@ -50,11 +55,19 @@ export interface TelemetryRow {
50
55
  input_tokens: number | null;
51
56
  output_tokens: number | null;
52
57
  thinking_tokens: number | null;
58
+ /** The parts of input_tokens read from and written to the provider's prompt cache; null when unreported. */
59
+ cache_read_tokens: number | null;
60
+ cache_write_tokens: number | null;
53
61
  latency_ms: number;
54
62
  session_id: string | null;
55
63
  user_id: string | null;
56
64
  task_id: string | null;
57
65
  invocation_id: string | null;
66
+ /** The nearest ancestor span the ledger keeps (ADR 0139); null for a span with no parent. */
67
+ parent_span_id: string | null;
68
+ kind: LedgerSpanKind | null;
69
+ /** The span failed: an error status, an error code, a tool's error response. */
70
+ error: boolean;
58
71
  schema_version: number;
59
72
  span: Record<string, unknown>;
60
73
  }
@@ -87,6 +100,9 @@ export interface TurnRow {
87
100
  input_tokens: number | null;
88
101
  output_tokens: number | null;
89
102
  thinking_tokens: number | null;
103
+ /** Cache tokens summed over the turn's calls (a provider bills each call's). */
104
+ cache_read_tokens: number | null;
105
+ cache_write_tokens: number | null;
90
106
  latency_ms: number;
91
107
  model_ms: number | null;
92
108
  tool_ms: number | null;
@@ -144,13 +160,26 @@ export interface TurnFacts {
144
160
  }
145
161
  /** Which payloads of a turn to keep, given the policy and the turn's outcome. */
146
162
  export declare function payloadDecision(policy: PayloadPolicy, traceId: string, facts: TurnFacts): PayloadReason | null;
163
+ /**
164
+ * The spans that get an adk_telemetry row: every span ledgerSpanKind names
165
+ * (ADR 0139). A model step's row (`model.call`) leaves its payload to
166
+ * adk_payloads (spanJson drops `llm.payload.*`) and its tokens to its
167
+ * llm.request rows, so a trace's rows sum without counting a call twice. A
168
+ * script's own spans (ADR 0137 item 16) carry its run, its calls' kinds,
169
+ * names, sequence and status, never an argument or a result.
170
+ */
171
+ export declare function isLedgerSpan(span: ReadableSpan): boolean;
147
172
  export declare function isRootSpan(span: ReadableSpan): boolean;
148
173
  export declare function isPayloadSpan(span: ReadableSpan): boolean;
149
174
  /** `syndicate.input` is JSON.stringify of either a string or A2A parts. */
150
175
  export declare function parseInputText(raw: unknown): string;
176
+ /** The span's parent in the ledger: the ancestor the tracer recorded at start, else its direct parent. */
177
+ export declare function ledgerParentOf(span: ReadableSpan): string | null;
178
+ /** Whether a span failed: its status, an error code it records, or a tool's error response. */
179
+ export declare function spanFailed(span: ReadableSpan): boolean;
151
180
  /** Span attributes minus the payload capture (`llm.payload.*`). */
152
181
  export declare function withoutPayloadAttributes(attrs: Record<string, unknown>): Record<string, unknown>;
153
- /** Flatten an llm.request or root span into one adk_telemetry row. */
182
+ /** Flatten a span the ledger keeps (isLedgerSpan) into one adk_telemetry row. */
154
183
  export declare function toTelemetryRow(span: ReadableSpan): TelemetryRow;
155
184
  /** Project a root span into the adk_turns system-of-record row. */
156
185
  export declare function toTurnRow(span: ReadableSpan): TurnRow;
@@ -13,7 +13,11 @@
13
13
  * tool calls WITH their responses, the ids that join it to
14
14
  * the session (session_id, invocation_id) and the task,
15
15
  * and provenance (config_hash, engine_version).
16
- * adk_telemetry one row per span — llm.request and root spans, raw.
16
+ * adk_telemetry one row per span the ledger keeps — the turn's root, each
17
+ * agent run, model step and provider call, tool call,
18
+ * script run and call, workflow walk and node run — each
19
+ * with its parent among them and its kind, so a turn's
20
+ * span tree is stored (ADR 0139).
17
21
  * adk_payloads full request/response per model call, captured by
18
22
  * POLICY and expiring. ADK's own call_llm spans carry the
19
23
  * assembled prompt and raw response, and the native
@@ -41,7 +45,7 @@ import { join } from 'node:path';
41
45
  import core from '@opentelemetry/core';
42
46
  const { ExportResultCode } = core;
43
47
  import { hasSupabaseCredentials } from '../persistence/supabaseProvider.js';
44
- import { TELEMETRY_SCHEMA_VERSION, isModelCallSpan } from './lineage.js';
48
+ import { LEDGER_PARENT_ATTRIBUTE, TELEMETRY_SCHEMA_VERSION, isModelCallSpan, ledgerSpanKind } from './lineage.js';
45
49
  import { redactRow, telemetryRedactor } from './redact.js';
46
50
  import { outputsDir } from '../paths.js';
47
51
  /**
@@ -81,8 +85,17 @@ export function payloadDecision(policy, traceId, facts) {
81
85
  }
82
86
  // ── Span → row mapping (pure; tested offline) ───────────────────────────────
83
87
  const ROOT_PREFIX = 'Syndicate Execution: ';
84
- // A script's own spans (ADR 0137 item 16) carry its run, its calls' kinds, names, sequence and status, never an argument or a result.
85
- const EXPORTED_SPAN_NAMES = /^(llm\.request$|Syndicate Execution: |script\.(invoke|call) )/;
88
+ /**
89
+ * The spans that get an adk_telemetry row: every span ledgerSpanKind names
90
+ * (ADR 0139). A model step's row (`model.call`) leaves its payload to
91
+ * adk_payloads (spanJson drops `llm.payload.*`) and its tokens to its
92
+ * llm.request rows, so a trace's rows sum without counting a call twice. A
93
+ * script's own spans (ADR 0137 item 16) carry its run, its calls' kinds,
94
+ * names, sequence and status, never an argument or a result.
95
+ */
96
+ export function isLedgerSpan(span) {
97
+ return ledgerSpanKind(span.name) !== null;
98
+ }
86
99
  function attrsOf(span) {
87
100
  return span.attributes;
88
101
  }
@@ -169,6 +182,25 @@ function spanJson(span) {
169
182
  status: span.status,
170
183
  };
171
184
  }
185
+ /** The span's parent in the ledger: the ancestor the tracer recorded at start, else its direct parent. */
186
+ export function ledgerParentOf(span) {
187
+ const recorded = attrsOf(span)[LEDGER_PARENT_ATTRIBUTE];
188
+ if (typeof recorded === 'string' && recorded)
189
+ return recorded;
190
+ const s = span;
191
+ const parent = s.parentSpanContext?.spanId ?? s.parentSpanId;
192
+ return typeof parent === 'string' && parent ? parent : null;
193
+ }
194
+ /** Whether a span failed: its status, an error code it records, or a tool's error response. */
195
+ export function spanFailed(span) {
196
+ const attrs = attrsOf(span);
197
+ return (span.status?.code === 2 || // SpanStatusCode.ERROR
198
+ !!str(attrs, 'llm.error_code') ||
199
+ !!str(attrs, 'syndicate.error.code') ||
200
+ attrs['tool.error'] === true ||
201
+ attrs['script.call.status'] === 'error' ||
202
+ attrs['adk.node.status'] === 'failed');
203
+ }
172
204
  /** Span attributes minus the payload capture (`llm.payload.*`). */
173
205
  export function withoutPayloadAttributes(attrs) {
174
206
  const out = {};
@@ -177,7 +209,7 @@ export function withoutPayloadAttributes(attrs) {
177
209
  out[k] = v;
178
210
  return out;
179
211
  }
180
- /** Flatten an llm.request or root span into one adk_telemetry row. */
212
+ /** Flatten a span the ledger keeps (isLedgerSpan) into one adk_telemetry row. */
181
213
  export function toTelemetryRow(span) {
182
214
  const attrs = attrsOf(span);
183
215
  return {
@@ -192,11 +224,16 @@ export function toTelemetryRow(span) {
192
224
  input_tokens: num(attrs, 'llm.tokens.input') ?? num(attrs, 'syndicate.tokens.input'),
193
225
  output_tokens: num(attrs, 'llm.tokens.output') ?? num(attrs, 'syndicate.tokens.output'),
194
226
  thinking_tokens: num(attrs, 'llm.tokens.thinking') ?? num(attrs, 'syndicate.tokens.thinking'),
227
+ cache_read_tokens: num(attrs, 'llm.tokens.cache_read') ?? num(attrs, 'syndicate.tokens.cache_read'),
228
+ cache_write_tokens: num(attrs, 'llm.tokens.cache_write') ?? num(attrs, 'syndicate.tokens.cache_write'),
195
229
  latency_ms: durationMs(span),
196
230
  session_id: str(attrs, 'session.id'),
197
231
  user_id: str(attrs, 'user.id'),
198
232
  task_id: str(attrs, 'a2a.task_id'),
199
233
  invocation_id: str(attrs, 'adk.invocation_id'),
234
+ parent_span_id: ledgerParentOf(span),
235
+ kind: ledgerSpanKind(span.name),
236
+ error: spanFailed(span),
200
237
  schema_version: TELEMETRY_SCHEMA_VERSION,
201
238
  span: spanJson(span),
202
239
  };
@@ -241,6 +278,8 @@ export function toTurnRow(span) {
241
278
  input_tokens: num(attrs, 'syndicate.tokens.input'),
242
279
  output_tokens: num(attrs, 'syndicate.tokens.output'),
243
280
  thinking_tokens: num(attrs, 'syndicate.tokens.thinking'),
281
+ cache_read_tokens: num(attrs, 'syndicate.tokens.cache_read'),
282
+ cache_write_tokens: num(attrs, 'syndicate.tokens.cache_write'),
244
283
  latency_ms: durationMs(span),
245
284
  model_ms: num(attrs, 'syndicate.latency.model_ms'),
246
285
  tool_ms: num(attrs, 'syndicate.latency.tool_ms'),
@@ -371,7 +410,7 @@ export class SupabaseSpanExporter {
371
410
  const turnRows = [];
372
411
  const payloadRows = [];
373
412
  for (const span of spans) {
374
- if (EXPORTED_SPAN_NAMES.test(span.name))
413
+ if (isLedgerSpan(span))
375
414
  telemetryRows.push(toTelemetryRow(span));
376
415
  if (isRootSpan(span)) {
377
416
  const turn = toTurnRow(span);
@@ -2,7 +2,7 @@ import type { Context, Span, SpanContext, SpanOptions } from '@opentelemetry/api
2
2
  import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
3
3
  import type { LlmResponse } from '../models/genaiMapping.ts';
4
4
  import type { TurnEvent as Event } from '../runtime/events.ts';
5
- import type { ModelRequest } from '../models/contract.ts';
5
+ import type { ModelRequest, ModelResponse } from '../models/contract.ts';
6
6
  import type { ExporterOptions, LedgerClient } from './supabaseSpanExporter.ts';
7
7
  /**
8
8
  * Optional OTLP export for a live trace viewer (Phoenix, Langfuse, Grafana
@@ -45,6 +45,9 @@ interface TraceStats {
45
45
  toolMs: number;
46
46
  llmCalls: number;
47
47
  models: Set<string>;
48
+ /** Cache tokens summed over every call (`syndicate.tokens.cache_read` / `.cache_write`). */
49
+ cacheRead: number;
50
+ cacheWrite: number;
48
51
  /** Each model's calls and tokens, input summed per call (what a provider bills), for `syndicate.usage` (ADR 0136). */
49
52
  usage: Map<string, ModelUsage>;
50
53
  startedAt: number;
@@ -52,9 +55,13 @@ interface TraceStats {
52
55
  /** One model's share of a turn: what the ledger prices it from (model_pricing, ADR 0136). */
53
56
  export interface ModelUsage {
54
57
  calls: number;
58
+ /** Every input token, the cache's included (the contract's meaning, lib/models/contract.ts). */
55
59
  input: number;
56
60
  output: number;
57
61
  thinking: number;
62
+ /** The parts of `input` read from and written to the provider's prompt cache, priced at their own rates (ADR 0139). */
63
+ cache_read: number;
64
+ cache_write: number;
58
65
  }
59
66
  /** Read-and-forget the stats for a finished trace. */
60
67
  export declare function takeTraceStats(traceId: string): TraceStats | undefined;
@@ -171,6 +178,15 @@ export interface LlmCallMeta {
171
178
  * for an adapter written before the model contract.
172
179
  */
173
180
  llmRequest?: unknown;
181
+ /**
182
+ * The contract response a yielded LlmResponse was mapped from, when the
183
+ * caller holds it (the native step, the summarizer, the memory extractor).
184
+ * The span reads what an LlmResponse cannot carry from it: the cache
185
+ * write count and the contract's finish reason. Without it the span
186
+ * records the cache reads Gemini's usage names and no finish reason
187
+ * unless the call failed.
188
+ */
189
+ source?: (response: LlmResponse) => ModelResponse | undefined;
174
190
  }
175
191
  /**
176
192
  * Wraps one adapter `generateContentAsync` invocation in an `llm.request`
@@ -1,6 +1,6 @@
1
1
  import { trace, context, defaultTextMapGetter, ROOT_CONTEXT, INVALID_SPAN_CONTEXT } from '@opentelemetry/api';
2
2
  import { createRequire } from 'node:module';
3
- import { ADK_SPAN_SCOPE, RUNTIME_SPAN_SCOPE, TELEMETRY_SCHEMA_VERSION, agentOfSpanName, engineVersion, isModelCallSpan, isToolSpanName } from './lineage.js';
3
+ import { ADK_SPAN_SCOPE, LEDGER_PARENT_ATTRIBUTE, RUNTIME_SPAN_SCOPE, TELEMETRY_SCHEMA_VERSION, agentOfSpanName, engineVersion, isModelCallSpan, isToolSpanName, ledgerSpanKind } from './lineage.js';
4
4
  import { FilteringSpanExporter, otlpContentMode } from './otlpFilter.js';
5
5
  import { telemetryRedactor } from './redact.js';
6
6
  import { chargeLlmCall, chargeTokens, turnUntraced } from '../runtime/turnControl.js';
@@ -194,7 +194,7 @@ const TRACE_STATS_TTL_MS = 60 * 60 * 1000;
194
194
  function statsFor(traceId) {
195
195
  let s = traceStats.get(traceId);
196
196
  if (!s) {
197
- s = { modelMs: 0, toolMs: 0, llmCalls: 0, models: new Set(), usage: new Map(), startedAt: Date.now() };
197
+ s = { modelMs: 0, toolMs: 0, llmCalls: 0, models: new Set(), cacheRead: 0, cacheWrite: 0, usage: new Map(), startedAt: Date.now() };
198
198
  traceStats.set(traceId, s);
199
199
  if (traceStats.size > 2_000) {
200
200
  const cutoff = Date.now() - TRACE_STATS_TTL_MS;
@@ -219,6 +219,15 @@ class SpanLineageProcessor {
219
219
  const ctx = span.spanContext();
220
220
  const parent = span.parentSpanContext?.spanId ?? span.parentSpanId ?? undefined;
221
221
  spanLineage.set(ctx.spanId, { name: span.name, parent });
222
+ // The ledger's parent is the nearest ancestor it keeps a row for, read
223
+ // now: an ancestor's entry is gone once it ends, and the exporter sees
224
+ // the span only after that (ADR 0139). Recorded only when it differs
225
+ // from the direct parent, which the span carries itself.
226
+ if (ledgerSpanKind(span.name) !== null) {
227
+ const ledgerParent = ledgerAncestor(parent);
228
+ if (ledgerParent && ledgerParent !== parent)
229
+ span.setAttribute(LEDGER_PARENT_ATTRIBUTE, ledgerParent);
230
+ }
222
231
  // The model-call span (the loop's model.call, ADK's call_llm before 1.0.0: the one
223
232
  // carrying the full request/response payloads) learns its agent the same
224
233
  // way llm.request does, so a payload row can be attributed without
@@ -250,13 +259,21 @@ class SpanLineageProcessor {
250
259
  const v = span.attributes[key];
251
260
  return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0;
252
261
  };
253
- const u = s.usage.get(model) ?? { calls: 0, input: 0, output: 0, thinking: 0 };
262
+ const u = s.usage.get(model) ?? { calls: 0, input: 0, output: 0, thinking: 0, cache_read: 0, cache_write: 0 };
254
263
  u.calls += 1;
255
264
  u.input += tokens('llm.tokens.input');
256
265
  u.output += tokens('llm.tokens.output');
257
266
  u.thinking += tokens('llm.tokens.thinking');
267
+ u.cache_read += tokens('llm.tokens.cache_read');
268
+ u.cache_write += tokens('llm.tokens.cache_write');
258
269
  s.usage.set(model, u);
259
270
  }
271
+ const cache = (key) => {
272
+ const v = span.attributes[key];
273
+ return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0;
274
+ };
275
+ s.cacheRead += cache('llm.tokens.cache_read');
276
+ s.cacheWrite += cache('llm.tokens.cache_write');
260
277
  }
261
278
  else if (isToolSpanName(span.name)) {
262
279
  statsFor(traceId).toolMs += spanDurationMs(span);
@@ -265,6 +282,23 @@ class SpanLineageProcessor {
265
282
  shutdown() { return Promise.resolve(); }
266
283
  forceFlush() { return Promise.resolve(); }
267
284
  }
285
+ /**
286
+ * The nearest of `spanId` and its ancestors that the ledger keeps a row for
287
+ * (ledgerSpanKind), or `spanId` itself when the chain leaves the lineage
288
+ * (a remote parent, an evicted entry) or holds no such span.
289
+ */
290
+ function ledgerAncestor(spanId) {
291
+ let cursor = spanId;
292
+ for (let depth = 0; cursor && depth < 32; depth++) {
293
+ const entry = spanLineage.get(cursor);
294
+ if (!entry)
295
+ return depth === 0 ? spanId : cursor;
296
+ if (ledgerSpanKind(entry.name) !== null)
297
+ return cursor;
298
+ cursor = entry.parent;
299
+ }
300
+ return spanId;
301
+ }
268
302
  /** Name of the agent of the nearest enclosing agent span (ADK's `invoke_agent`, the loop's `agent.invoke`), or null. */
269
303
  export function agentForSpan(spanId) {
270
304
  let cursor = spanId;
@@ -557,6 +591,9 @@ export async function* traceAgentRun(stream, metadata) {
557
591
  span.setAttribute('syndicate.latency.tool_ms', Math.round(stats.toolMs));
558
592
  span.setAttribute('syndicate.llm_calls', stats.llmCalls);
559
593
  span.setAttribute('syndicate.models', [...stats.models].sort().join(','));
594
+ // Summed over every call, as a provider bills them (adk_turns.cache_read_tokens / cache_write_tokens).
595
+ span.setAttribute('syndicate.tokens.cache_read', stats.cacheRead);
596
+ span.setAttribute('syndicate.tokens.cache_write', stats.cacheWrite);
560
597
  // The ledger prices the turn from this, per model (melchizedek_usage_cost, ADR 0136).
561
598
  span.setAttribute('syndicate.usage', JSON.stringify(Object.fromEntries([...stats.usage].sort(([a], [b]) => a.localeCompare(b)))));
562
599
  }
@@ -673,6 +710,9 @@ export async function* traceLlmGeneration(meta, inner) {
673
710
  let inputTokens = 0;
674
711
  let outputTokens = 0;
675
712
  let thinkingTokens = 0;
713
+ let cacheRead;
714
+ let cacheWrite;
715
+ let finishReason;
676
716
  let thinkingPreview = '';
677
717
  let errorCode = '';
678
718
  let errorMessage = '';
@@ -689,6 +729,15 @@ export async function* traceLlmGeneration(meta, inner) {
689
729
  inputTokens = resp.usageMetadata.promptTokenCount ?? inputTokens;
690
730
  outputTokens = resp.usageMetadata.candidatesTokenCount ?? outputTokens;
691
731
  thinkingTokens = resp.usageMetadata.thoughtsTokenCount ?? thinkingTokens;
732
+ cacheRead = resp.usageMetadata.cachedContentTokenCount ?? cacheRead;
733
+ }
734
+ const source = meta.source?.(resp);
735
+ if (source && !source.partial) {
736
+ finishReason = source.finishReason;
737
+ if (source.usage?.cacheReadTokens !== undefined)
738
+ cacheRead = source.usage.cacheReadTokens;
739
+ if (source.usage?.cacheWriteTokens !== undefined)
740
+ cacheWrite = source.usage.cacheWriteTokens;
692
741
  }
693
742
  if (resp.errorCode) {
694
743
  errorCode = String(resp.errorCode);
@@ -733,6 +782,15 @@ export async function* traceLlmGeneration(meta, inner) {
733
782
  span.setAttribute('llm.tokens.input', inputTokens);
734
783
  span.setAttribute('llm.tokens.output', outputTokens);
735
784
  span.setAttribute('llm.tokens.thinking', thinkingTokens);
785
+ // Parts of llm.tokens.input, set only when the provider reported them (ADR 0139).
786
+ if (cacheRead !== undefined)
787
+ span.setAttribute('llm.tokens.cache_read', cacheRead);
788
+ if (cacheWrite !== undefined)
789
+ span.setAttribute('llm.tokens.cache_write', cacheWrite);
790
+ if (errorCode)
791
+ finishReason = 'error';
792
+ if (finishReason)
793
+ span.setAttribute('llm.finish_reason', finishReason);
736
794
  span.setAttribute('gen_ai.usage.input_tokens', inputTokens);
737
795
  span.setAttribute('gen_ai.usage.output_tokens', outputTokens);
738
796
  // llm.latency_ms mirrors the span duration for the flat adk_telemetry row.
@@ -39,7 +39,7 @@ const syndicateRecord = z
39
39
  export const projectManifestSchema = z
40
40
  .object({
41
41
  manifest: z.number().int().min(1),
42
- engine: z.string().regex(/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/, 'must be an exact version, e.g. 1.8.0'),
42
+ engine: z.string().regex(/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/, 'must be an exact version, e.g. 1.10.0'),
43
43
  agents: relPath,
44
44
  ignore: z.array(z.string().min(1)).optional(),
45
45
  tests: relPath.optional(),
@@ -144,11 +144,15 @@ export async function summarize(events, adapter, model, options = {}) {
144
144
  const startTime = events[0].timestamp;
145
145
  const endTime = events[events.length - 1].timestamp;
146
146
  const request = summaryRequest(events, model, options.signal);
147
+ const sources = new WeakMap();
147
148
  async function* inner() {
148
- for await (const response of adapter.generate(request))
149
- yield modelResponseToLlmResponse(response);
149
+ for await (const response of adapter.generate(request)) {
150
+ const mapped = modelResponseToLlmResponse(response);
151
+ sources.set(mapped, response);
152
+ yield mapped;
153
+ }
150
154
  }
151
- const responses = traceLlmGeneration({ provider: adapter.provider, model, request }, inner());
155
+ const responses = traceLlmGeneration({ provider: adapter.provider, model, request, source: (r) => sources.get(r) }, inner());
152
156
  // As ADK: the first response must carry text; nothing after a failure is read.
153
157
  const first = await responses.next();
154
158
  const head = first.done ? undefined : first.value.content?.parts?.[0]?.text;
@@ -112,6 +112,8 @@ export interface NativeAgent {
112
112
  mode?: 'task';
113
113
  /** The session-state key the agent's final answer is saved under (the loop writes it, lib/runtime/native/agentLoop.ts). */
114
114
  outputKey?: string;
115
+ /** The YAML's `metadata:` (ADR 0141): `meta.agent.<key>` attributes on the agent's `agent.invoke` span. */
116
+ metadata?: Record<string, string | number | boolean>;
115
117
  /** `fallback_model:`: answers a provider-side failure of the agent's model (ADR 0044). The loop calls it as its own leaf adapter. */
116
118
  fallbackModel?: string;
117
119
  /** `context:` (ADR 0033): compact the history into a summary past a token threshold. The loop runs it before each step (compaction.ts). */
@@ -218,7 +218,7 @@ export async function runModelStep(options) {
218
218
  return { ...result, event: stored, error: { code, message, retryable: false } };
219
219
  }
220
220
  async function readResponses() {
221
- for await (const traced of traceLlmGeneration({ provider: adapter.provider, model: request.model, request }, inner())) {
221
+ for await (const traced of traceLlmGeneration({ provider: adapter.provider, model: request.model, request, source: (r) => sources.get(r) }, inner())) {
222
222
  if (signal?.aborted)
223
223
  return { ...result, stopped: stopOf() };
224
224
  const source = sources.get(traced);