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,219 @@
1
+ /**
2
+ * lib/a2a/feedback.ts — end-user feedback on a served turn (ADR 0140):
3
+ * `POST /feedback` and `POST /<agentId>/feedback`.
4
+ *
5
+ * POST /feedback
6
+ * { "traceId": "4bf9…", "score": "down", "comment": "Wrong refund policy", "userId": "u-123" }
7
+ *
8
+ * The body names the turn by exactly one of `taskId` (the A2A task) or
9
+ * `traceId` (the ledger's), a `score` of 'up' | 'down' or an integer 1–5,
10
+ * and optionally a `comment` (≤ 4,000 characters) and the product's own
11
+ * `userId`. It lands in the ledger as one `adk_labels` row:
12
+ *
13
+ * ref = trace_id = the turn's trace id, labeler = 'end-user',
14
+ * fields = { score, userId } (userId null when none was sent),
15
+ * note = the comment through the telemetry redactor (null when none)
16
+ *
17
+ * The route sits behind the same bearer check, authenticator, failed-auth
18
+ * limiter and task rate limit as the A2A routes, with its own body limit
19
+ * (32 KB). A caller rates only turns it could have run: the turn's
20
+ * `user_id` must be the caller's scope (or one beneath a scope that owns
21
+ * nested ones), unless the caller holds an operator credential; anything
22
+ * else answers the same 404 as a turn that does not exist. One label per
23
+ * (turn, userId) per minute, per process; without a userId the caller's
24
+ * scope stands in. Answers never repeat what was sent.
25
+ */
26
+ import { createHash } from 'node:crypto';
27
+ import express from 'express';
28
+ import { z } from 'zod';
29
+ import { REDACTION_PATTERNS, telemetryRedactor } from '../observability/redact.js';
30
+ /** The labeler every end-user feedback row carries. */
31
+ export const END_USER_LABELER = 'end-user';
32
+ /** The route's own JSON body limit. */
33
+ export const FEEDBACK_BODY_LIMIT = '32kb';
34
+ /** The longest comment accepted, in characters. */
35
+ export const FEEDBACK_COMMENT_MAX = 4_000;
36
+ /** One label per (turn, user) in this window. */
37
+ export const FEEDBACK_WINDOW_MS = 60_000;
38
+ const ID = /^[A-Za-z0-9._:-]{1,128}$/;
39
+ const USER_ID = /^[A-Za-z0-9._@:+/-]{1,128}$/;
40
+ const bodySchema = z.strictObject({
41
+ taskId: z.string().regex(ID).optional(),
42
+ traceId: z.string().regex(ID).optional(),
43
+ score: z.union([z.enum(['up', 'down']), z.number().int().min(1).max(5)]),
44
+ comment: z.string().max(FEEDBACK_COMMENT_MAX).optional(),
45
+ userId: z.string().regex(USER_ID).optional(),
46
+ });
47
+ /** Field-level messages that name the field and the rule, never the value sent. */
48
+ const MESSAGES = {
49
+ taskId: 'taskId must be 1–128 characters of [A-Za-z0-9._:-].',
50
+ traceId: 'traceId must be 1–128 characters of [A-Za-z0-9._:-].',
51
+ score: "score must be 'up', 'down' or an integer from 1 to 5.",
52
+ comment: `comment must be a string of at most ${FEEDBACK_COMMENT_MAX.toLocaleString('en-US')} characters.`,
53
+ userId: 'userId must be 1–128 characters of [A-Za-z0-9._@:+/-].',
54
+ };
55
+ /** Validates a feedback body. The error names the rule broken, never the value. */
56
+ export function parseFeedback(body) {
57
+ if (!body || typeof body !== 'object' || Array.isArray(body))
58
+ return { ok: false, error: 'Send a JSON object body (Content-Type: application/json).' };
59
+ const r = bodySchema.safeParse(body);
60
+ if (!r.success) {
61
+ const issue = r.error.issues[0];
62
+ if (issue.code === 'unrecognized_keys')
63
+ return { ok: false, error: 'Unknown field; the body takes taskId or traceId, score, comment and userId.' };
64
+ const field = String(issue.path[0] ?? '');
65
+ return { ok: false, error: MESSAGES[field] ?? 'Invalid feedback body.' };
66
+ }
67
+ const { taskId, traceId, score, comment, userId } = r.data;
68
+ if ((taskId === undefined) === (traceId === undefined))
69
+ return { ok: false, error: 'Name the turn with exactly one of taskId or traceId.' };
70
+ if (userId && new RegExp(REDACTION_PATTERNS.secret.source).test(userId))
71
+ return { ok: false, error: 'userId looks like a credential; send the product’s own user id.' };
72
+ return {
73
+ ok: true,
74
+ value: {
75
+ ref: taskId !== undefined ? { taskId } : { traceId: traceId },
76
+ score: score,
77
+ comment: comment && comment.trim() ? comment : null,
78
+ userId: userId ?? null,
79
+ },
80
+ };
81
+ }
82
+ /** The row a parsed request writes for a turn, the comment through `redactor` (none: kept as sent). */
83
+ export function feedbackRow(traceId, f, redactor) {
84
+ return {
85
+ ref: traceId,
86
+ trace_id: traceId,
87
+ labeler: END_USER_LABELER,
88
+ fields: { score: f.score, userId: f.userId },
89
+ note: f.comment === null ? null : redactor ? redactor(f.comment) : f.comment,
90
+ };
91
+ }
92
+ /** May this caller rate a turn that ran under `turnUserId`? */
93
+ export function mayRate(ctx, turnUserId) {
94
+ if (ctx.operator)
95
+ return true;
96
+ if (!turnUserId)
97
+ return false;
98
+ return turnUserId === ctx.scopeKey || (!!ctx.ownsNested && turnUserId.startsWith(`${ctx.scopeKey}/`));
99
+ }
100
+ /** One label per key per window, in this process. Keys are hashes; the map is swept as it grows. */
101
+ export function feedbackLimiter(windowMs = FEEDBACK_WINDOW_MS, now = Date.now) {
102
+ const until = new Map();
103
+ const sweep = () => {
104
+ const t = now();
105
+ for (const [k, v] of until)
106
+ if (v <= t)
107
+ until.delete(k);
108
+ };
109
+ return {
110
+ /** Reserves the key; the ms to wait when it is taken. */
111
+ take(key) {
112
+ const t = now();
113
+ const held = until.get(key);
114
+ if (held !== undefined && held > t)
115
+ return { ok: false, retryAfterMs: held - t };
116
+ if (until.size >= 10_000)
117
+ sweep();
118
+ until.set(key, t + windowMs);
119
+ return { ok: true };
120
+ },
121
+ /** Gives a reservation back (the write failed). */
122
+ release(key) {
123
+ until.delete(key);
124
+ },
125
+ };
126
+ }
127
+ /** The JSON parser for the feedback routes: 32 KB, and its errors answered as JSON without the body. */
128
+ export function feedbackBodyParser() {
129
+ const parse = express.json({ limit: FEEDBACK_BODY_LIMIT });
130
+ return (req, res, next) => {
131
+ parse(req, res, (err) => {
132
+ if (!err)
133
+ return next();
134
+ const e = err;
135
+ if (e.type === 'entity.too.large' || e.status === 413) {
136
+ res.status(413).json({ error: `The feedback body is over ${FEEDBACK_BODY_LIMIT.toUpperCase()}.` });
137
+ return;
138
+ }
139
+ res.status(400).json({ error: 'The body is not valid JSON.' });
140
+ });
141
+ };
142
+ }
143
+ /** The route handler; mount it after authentication, with its body parsed by feedbackBodyParser(). */
144
+ export function feedbackHandler(opts) {
145
+ const limiter = opts.limiter ?? feedbackLimiter();
146
+ return async (req, res) => {
147
+ const agentId = typeof req.params?.agentId === 'string' ? req.params.agentId : undefined;
148
+ if (agentId !== undefined && opts.agentServed && !opts.agentServed(agentId)) {
149
+ res.status(404).json({ error: 'Unknown agent.' });
150
+ return;
151
+ }
152
+ if (!opts.store) {
153
+ res.status(501).json({ error: 'Feedback needs the telemetry ledger; this server has none configured.' });
154
+ return;
155
+ }
156
+ const ctx = opts.context();
157
+ if (!ctx) {
158
+ res.status(401).json({ error: 'No authentication context.' });
159
+ return;
160
+ }
161
+ const parsed = parseFeedback(req.body);
162
+ if (!parsed.ok) {
163
+ res.status(400).json({ error: parsed.error });
164
+ return;
165
+ }
166
+ const f = parsed.value;
167
+ let turn;
168
+ try {
169
+ turn = await opts.store.turn(f.ref);
170
+ }
171
+ catch (err) {
172
+ opts.warn?.(`Feedback: the ledger could not be read (${err instanceof Error ? err.message : String(err)}).`);
173
+ res.status(503).json({ error: 'The ledger is unavailable; retry shortly.' });
174
+ return;
175
+ }
176
+ // Not found and not yours answer alike: a caller cannot probe for other people's turns.
177
+ if (!turn || !mayRate(ctx, turn.userId)) {
178
+ res.status(404).json({ error: 'No turn with that id (a turn reaches the ledger a few seconds after it ends).' });
179
+ return;
180
+ }
181
+ const who = f.userId !== null ? `user:${f.userId}` : `scope:${ctx.scopeKey}`;
182
+ const key = createHash('sha256').update(`${turn.traceId}\u0000${who}`).digest('hex');
183
+ const slot = limiter.take(key);
184
+ if (!slot.ok) {
185
+ res.setHeader('Retry-After', String(Math.ceil(slot.retryAfterMs / 1000)));
186
+ res.status(429).json({ error: 'Feedback on this turn from this user was just recorded; one per minute.' });
187
+ return;
188
+ }
189
+ try {
190
+ await opts.store.add(feedbackRow(turn.traceId, f, telemetryRedactor()));
191
+ }
192
+ catch (err) {
193
+ limiter.release(key);
194
+ opts.warn?.(`Feedback: the label was not written (${err instanceof Error ? err.message : String(err)}).`);
195
+ res.status(503).json({ error: 'The feedback could not be stored; retry shortly.' });
196
+ return;
197
+ }
198
+ opts.log?.(`Feedback on trace ${turn.traceId.slice(0, 8)}: ${typeof f.score === 'number' ? `${f.score}/5` : f.score}${f.comment !== null ? ', with a comment' : ''}`);
199
+ res.status(201).json({ ok: true, traceId: turn.traceId });
200
+ };
201
+ }
202
+ /** Matches the feedback routes' paths, so the server-wide JSON parser leaves their bodies to feedbackBodyParser. */
203
+ export const isFeedbackPath = (path) => path === '/feedback' || /^\/[^/]+\/feedback$/.test(path);
204
+ /** A FeedbackStore over a Postgres pool holding the ledger (db/telemetry.sql). */
205
+ export function postgresFeedbackStore(pool) {
206
+ return {
207
+ async turn(ref) {
208
+ const byTask = 'taskId' in ref;
209
+ const { rows } = await pool.query(
210
+ // A dispatch task has a classifier turn beside its answer: the answer is the one rated.
211
+ `SELECT trace_id, user_id FROM adk_turns WHERE ${byTask ? "task_id = $1 AND stage IS DISTINCT FROM 'classify'" : 'trace_id = $1'} ORDER BY ts DESC LIMIT 1`, [byTask ? ref.taskId : ref.traceId]);
212
+ const r = rows[0];
213
+ return r ? { traceId: String(r.trace_id), userId: r.user_id == null ? null : String(r.user_id) } : null;
214
+ },
215
+ async add(row) {
216
+ await pool.query('INSERT INTO adk_labels (ref, trace_id, labeler, fields, note) VALUES ($1, $2, $3, $4::jsonb, $5)', [row.ref, row.trace_id, row.labeler, JSON.stringify(row.fields), row.note]);
217
+ },
218
+ };
219
+ }
@@ -95,16 +95,66 @@ export type BudgetConfig = z.infer<typeof budgetsSchema>;
95
95
  export declare function parseBudgets(json: string): BudgetConfig;
96
96
  /** A scope as a counter subject: hashed, so the usage table holds no user identifier. */
97
97
  export declare const scopeSubject: (scopeKey: string) => string;
98
+ /** Where a subject stands against its limits today. */
99
+ export type BudgetLevel = 'ok' | 'warn' | 'over';
100
+ /**
101
+ * One subject's standing, as `onBudgetState` reports it: after every task
102
+ * it recorded (cause 'record'), and when a task arrives over a limit
103
+ * (cause 'admit'; `stopped` says whether it was refused). Counts only,
104
+ * never user text; the scope is its hash.
105
+ */
106
+ export interface BudgetState {
107
+ /** `caller:<name>` or `scope:<SHA-256 prefix>` (scopeSubject). */
108
+ subject: string;
109
+ /** The UTC day counted (YYYY-MM-DD). */
110
+ day: string;
111
+ /** The subject's totals for the day, this task included. */
112
+ usage: DailyUsage;
113
+ /** The limits that apply to the subject; undefined when none do. */
114
+ limits?: BudgetLimits;
115
+ /** 'over' at or past any limit, 'warn' at or past `warnAt` of one, else 'ok'. */
116
+ level: BudgetLevel;
117
+ /** The limit reached, as the refusal names it ('2,000,000 tokens'), when over. */
118
+ reached?: string;
119
+ cause: 'record' | 'admit';
120
+ /** The agent id the task was sent to ('' or 'default' for the boot syndicate). */
121
+ agentId: string;
122
+ /** With cause 'admit': true when the task was refused, false when it went ahead over the limit (hardStop: false). */
123
+ stopped?: boolean;
124
+ }
125
+ /**
126
+ * A stop decided outside the daily limits, at admission: return a reason to
127
+ * refuse the task with it, or undefined to admit it. Throwing refuses (fail
128
+ * closed). A desktop app serving locally passes its own month's spend check.
129
+ */
130
+ export type HardStop = (subject: PolicySubject) => string | undefined | Promise<string | undefined>;
131
+ export interface BudgetOptions {
132
+ store?: UsageStore;
133
+ now?: () => Date;
134
+ /**
135
+ * Called with each subject's standing after a task is recorded, and when
136
+ * a task arrives over a limit, so a consumer can mirror a deployment's spend. Errors are
137
+ * swallowed; it never delays or fails a task beyond its own runtime.
138
+ */
139
+ onBudgetState?: (state: BudgetState) => void | Promise<void>;
140
+ /** The share of a limit at which the level is 'warn'. Default 0.8. */
141
+ warnAt?: number;
142
+ /**
143
+ * true (default): a subject at a limit is refused. false: the limits only
144
+ * report ('over' through onBudgetState) and tasks go ahead. A function:
145
+ * the limits refuse, and the function is asked as well (HardStop).
146
+ */
147
+ hardStop?: boolean | HardStop;
148
+ }
98
149
  /**
99
150
  * Daily budgets per caller and per scope. A request is refused when the
100
151
  * caller or its scope has reached any limit today (UTC); the message says
101
152
  * which and when it resets. A store failure refuses (fail closed) — a
102
- * budget that cannot be read is not a budget.
153
+ * budget that cannot be read is not a budget. `onBudgetState` mirrors each
154
+ * subject's standing; `hardStop` makes the limits advisory, or adds an
155
+ * outside stop (BudgetOptions).
103
156
  */
104
- export declare function budgets(config: BudgetConfig, opts?: {
105
- store?: UsageStore;
106
- now?: () => Date;
107
- }): Policy & {
157
+ export declare function budgets(config: BudgetConfig, opts?: BudgetOptions): Policy & {
108
158
  store: UsageStore;
109
159
  };
110
160
  export {};
@@ -137,42 +137,86 @@ function over(limits, u) {
137
137
  return `${limits.tokens.toLocaleString('en-US')} tokens`;
138
138
  return undefined;
139
139
  }
140
+ function levelOf(limits, u, warnAt) {
141
+ if (!limits)
142
+ return 'ok';
143
+ if (over(limits, u))
144
+ return 'over';
145
+ const near = (used, limit) => limit !== undefined && used >= limit * warnAt;
146
+ return near(u.tasks, limits.tasks) || near(u.llmCalls, limits.llmCalls) || near(tokensOf(u), limits.tokens) ? 'warn' : 'ok';
147
+ }
140
148
  /**
141
149
  * Daily budgets per caller and per scope. A request is refused when the
142
150
  * caller or its scope has reached any limit today (UTC); the message says
143
151
  * which and when it resets. A store failure refuses (fail closed) — a
144
- * budget that cannot be read is not a budget.
152
+ * budget that cannot be read is not a budget. `onBudgetState` mirrors each
153
+ * subject's standing; `hardStop` makes the limits advisory, or adds an
154
+ * outside stop (BudgetOptions).
145
155
  */
146
156
  export function budgets(config, opts = {}) {
147
157
  const store = opts.store ?? memoryUsageStore();
148
158
  const now = opts.now ?? (() => new Date());
159
+ const warnAt = opts.warnAt !== undefined && opts.warnAt > 0 && opts.warnAt <= 1 ? opts.warnAt : 0.8;
160
+ const enforce = opts.hardStop !== false;
161
+ const outsideStop = typeof opts.hardStop === 'function' ? opts.hardStop : undefined;
149
162
  const callerLimits = (caller) => (caller && config.callers?.[caller]) || config.perCaller;
163
+ const subjectsOf = (s) => [
164
+ ...(s.caller ? [[`caller:${s.caller}`, callerLimits(s.caller)]] : []),
165
+ [scopeSubject(s.scopeKey), config.perScope],
166
+ ];
167
+ const report = async (state) => {
168
+ if (!opts.onBudgetState)
169
+ return;
170
+ try {
171
+ await opts.onBudgetState(state);
172
+ }
173
+ catch {
174
+ /* a broken mirror must not touch the task */
175
+ }
176
+ };
150
177
  return {
151
178
  store,
152
179
  async admit(s) {
153
180
  const day = today(now);
154
- const checks = [
155
- [s.caller ? `caller:${s.caller}` : '', s.caller ? callerLimits(s.caller) : undefined],
156
- [scopeSubject(s.scopeKey), config.perScope],
157
- ];
158
- for (const [subject, limits] of checks) {
159
- if (!subject || !limits)
181
+ for (const [subject, limits] of subjectsOf(s)) {
182
+ if (!limits)
160
183
  continue;
161
- const hit = over(limits, await store.get(day, subject));
184
+ const usage = await store.get(day, subject);
185
+ const hit = over(limits, usage);
162
186
  if (hit) {
187
+ await report({ subject, day, usage, limits, level: 'over', reached: hit, cause: 'admit', agentId: s.agentId, stopped: enforce });
188
+ if (!enforce)
189
+ continue;
163
190
  const who = subject.startsWith('caller:') ? `Caller '${s.caller}'` : 'This user';
164
191
  return { ok: false, reason: `${who} has used today's budget of ${hit}. It resets at 00:00 UTC.` };
165
192
  }
166
193
  }
194
+ if (outsideStop) {
195
+ const reason = await outsideStop(s);
196
+ if (reason)
197
+ return { ok: false, reason };
198
+ }
167
199
  return { ok: true };
168
200
  },
169
201
  async record(s, usage) {
170
202
  const day = today(now);
171
203
  const delta = { tasks: 1, ...usage };
172
- const writes = [store.add(day, scopeSubject(s.scopeKey), delta)];
173
- if (s.caller)
174
- writes.push(store.add(day, `caller:${s.caller}`, delta));
175
- await Promise.all(writes);
204
+ const subjects = subjectsOf(s);
205
+ await Promise.all(subjects.map(([subject]) => store.add(day, subject, delta)));
206
+ if (!opts.onBudgetState)
207
+ return;
208
+ for (const [subject, limits] of subjects) {
209
+ let totals;
210
+ try {
211
+ totals = await store.get(day, subject);
212
+ }
213
+ catch {
214
+ continue; // the spend is recorded; only the mirror misses this one
215
+ }
216
+ const level = levelOf(limits, totals, warnAt);
217
+ const reached = level === 'over' ? over(limits, totals) : undefined;
218
+ await report({ subject, day, usage: totals, ...(limits ? { limits } : {}), level, ...(reached ? { reached } : {}), cause: 'record', agentId: s.agentId });
219
+ }
176
220
  },
177
221
  };
178
222
  }
@@ -208,6 +208,8 @@ export interface AgentSpec {
208
208
  mode?: 'task';
209
209
  /** The syndicate's `max_concurrency`, on its orchestrator (ADR 0116): delegated calls one step runs at once. */
210
210
  maxConcurrency?: number;
211
+ /** `metadata:` (ADR 0141): `meta.agent.<key>` on the agent's span. */
212
+ metadata?: Record<string, string | number | boolean>;
211
213
  }
212
214
  /**
213
215
  * The spec of a workflow syndicate: every agent through compileSubagentSpec
@@ -270,6 +270,8 @@ function specOf(yaml, name, description, instruction, tools, { resolvedModel, mo
270
270
  spec.context = yaml.context;
271
271
  if (yaml.mode)
272
272
  spec.mode = yaml.mode;
273
+ if (yaml.metadata && Object.keys(yaml.metadata).length)
274
+ spec.metadata = yaml.metadata;
273
275
  return spec;
274
276
  }
275
277
  const asTools = (tools) => tools.map((tool) => ({ kind: 'tool', tool }));
@@ -149,6 +149,8 @@ export function compileNative(spec) {
149
149
  agent.context = spec.context;
150
150
  if (spec.maxConcurrency !== undefined)
151
151
  agent.maxConcurrency = spec.maxConcurrency;
152
+ if (spec.metadata)
153
+ agent.metadata = spec.metadata;
152
154
  return agent;
153
155
  }
154
156
  /**
@@ -38,15 +38,18 @@ export { RUN_CODE, runCodeTool } from './tools/runCodeTool.ts';
38
38
  export type { CodeRun, RunCodeOutput } from './tools/runCodeTool.ts';
39
39
  export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.ts';
40
40
  export type { A2AApp, A2AAppOptions, RequestIdentity } from './a2a/app.ts';
41
- export type { A2AContext } from './a2a/executor.ts';
41
+ export type { A2AContext, TaskStateName, TaskStateRecord } from './a2a/executor.ts';
42
42
  export { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, scopeSegment, sharedSecret, trustedHeader, } from './a2a/identity.ts';
43
43
  export type { Authenticator, CallerEntry, IdentityScheme, JwtIdentityOptions } from './a2a/identity.ts';
44
44
  export { budgets, memoryUsageStore, parseBudgets, postgresUsageStore, supabaseUsageStore } from './a2a/policy.ts';
45
- export type { BudgetConfig, BudgetLimits, DailyUsage, Policy, PolicyDecision, PolicySubject, UsageStore } from './a2a/policy.ts';
45
+ export type { BudgetConfig, BudgetLevel, BudgetLimits, BudgetOptions, BudgetState, DailyUsage, HardStop, Policy, PolicyDecision, PolicySubject, UsageStore, } from './a2a/policy.ts';
46
+ export { END_USER_LABELER, feedbackRow, parseFeedback, postgresFeedbackStore } from './a2a/feedback.ts';
47
+ export type { FeedbackRow, FeedbackScore, FeedbackStore, FeedbackTurn } from './a2a/feedback.ts';
46
48
  export { createMetrics } from './observability/metrics.ts';
47
49
  export type { Metrics, TaskRecord } from './observability/metrics.ts';
48
50
  export { patternRedactor, redactRow, setTelemetryRedactor, telemetryRedactor } from './observability/redact.ts';
49
51
  export type { Redactor } from './observability/redact.ts';
52
+ export type { Metadata, MetadataValue } from './observability/metadata.ts';
50
53
  export { RemoteA2AAgent, remoteAgentTool } from './a2a/remoteAgent.ts';
51
54
  export type { RemoteAnswer } from './a2a/remoteAgent.ts';
52
55
  export { resolveTools, registerTool, registeredToolNames } from './toolRegistry.ts';
package/dist/lib/index.js CHANGED
@@ -32,6 +32,7 @@ export { RUN_CODE, runCodeTool } from './tools/runCodeTool.js';
32
32
  export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.js';
33
33
  export { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, scopeSegment, sharedSecret, trustedHeader, } from './a2a/identity.js';
34
34
  export { budgets, memoryUsageStore, parseBudgets, postgresUsageStore, supabaseUsageStore } from './a2a/policy.js';
35
+ export { END_USER_LABELER, feedbackRow, parseFeedback, postgresFeedbackStore } from './a2a/feedback.js';
35
36
  export { createMetrics } from './observability/metrics.js';
36
37
  export { patternRedactor, redactRow, setTelemetryRedactor, telemetryRedactor } from './observability/redact.js';
37
38
  export { RemoteA2AAgent, remoteAgentTool } from './a2a/remoteAgent.js';
@@ -13,6 +13,7 @@ import type { ReasoningSetting } from './models/contract.ts';
13
13
  export type { WorkflowConfig } from './workflowConfig.ts';
14
14
  export type { ScriptConfig } from './script/config.ts';
15
15
  import type { ScriptConfig } from './script/config.ts';
16
+ import type { Metadata } from './observability/metadata.ts';
16
17
  export interface ThinkingConfig {
17
18
  /** Token budget for internal reasoning. 0 = off, -1 = dynamic. */
18
19
  thinkingBudget?: number;
@@ -191,6 +192,12 @@ export interface AgentYamlConfig {
191
192
  role?: 'primary' | 'sub-agent';
192
193
  delegates?: string[];
193
194
  };
195
+ /**
196
+ * Static labels for the ledger (ADR 0141): each becomes `meta.agent.<key>`
197
+ * on this agent's `agent.invoke` span. At most 32 keys; a credential-shaped
198
+ * value is dropped at load with a warning.
199
+ */
200
+ metadata?: Metadata;
194
201
  }
195
202
  export interface SubagentYamlConfig extends Partial<AgentYamlConfig> {
196
203
  /** Required when used as AgentTool — orchestrator reads this to delegate. */
@@ -254,6 +261,13 @@ export interface SyndicateYamlConfig {
254
261
  script?: ScriptConfig;
255
262
  /** Optional default variable definitions for {{token}} interpolation. */
256
263
  variables?: VariableMap;
264
+ /**
265
+ * Static labels for the ledger (ADR 0141): each becomes `meta.<key>` on
266
+ * every root span of a turn, so on its adk_turns row. At most 32 keys; a
267
+ * credential-shaped value is dropped at load with a warning. A key named
268
+ * here cannot be set by an A2A caller's request metadata.
269
+ */
270
+ metadata?: Metadata;
257
271
  /** Defines the persistence and semantic memory layer for the syndicate. */
258
272
  memory_system?: 'internal-only' | 'session-only' | 'long-term';
259
273
  /**
@@ -6,6 +6,7 @@ import { hasSupabaseCredentials } from './persistence/supabaseProvider.js';
6
6
  import { validateSyndicateConfig } from './syndicateSchema.js';
7
7
  import { v1SpellingsOf } from './agentDialect.js';
8
8
  import { resolveAgentsDir } from './project.js';
9
+ import { dropSecretMetadata } from './observability/metadata.js';
9
10
  // ── Variable Injection (private) ──────────────────────────
10
11
  const TOKEN_RE = /\{\{(\w+)\}\}/g;
11
12
  const FULL_TOKEN_RE = /^\{\{(\w+)\}\}$/;
@@ -101,7 +102,7 @@ function resolveAndValidate(raw, label, options) {
101
102
  }
102
103
  const valid = validateSyndicateConfig(bundle !== undefined && isPlainObject(interpolated) ? { ...interpolated, bundled_references: bundle } : interpolated, label);
103
104
  const { variables: _stripped, ...clean } = valid;
104
- let config = clean;
105
+ let config = withoutSecretMetadata(clean, label, options.onWarning);
105
106
  // The script reads the bound variables (ADR 0137 item 6): the YAML's, then the caller's bindings, as {{token}} resolves them.
106
107
  if (config.script) {
107
108
  const yamlBound = isPlainObject(interpolated) && isPlainObject(interpolated.variables) ? interpolated.variables : {};
@@ -112,6 +113,23 @@ function resolveAndValidate(raw, label, options) {
112
113
  }
113
114
  return config;
114
115
  }
116
+ /**
117
+ * `metadata:` with every credential-shaped value dropped (ADR 0141), on the
118
+ * syndicate and on each agent, one warning per key naming the file and the
119
+ * key path, never the value. A `{{token}}` that resolved to a key is caught
120
+ * too: this runs on the interpolated config.
121
+ */
122
+ function withoutSecretMetadata(config, label, onWarning = console.warn) {
123
+ const meta = dropSecretMetadata(config.metadata, `${label}: metadata`, onWarning);
124
+ const agent = (a, path) => {
125
+ const m = dropSecretMetadata(a.metadata, `${label}: ${path}.metadata`, onWarning);
126
+ return m === a.metadata ? a : { ...a, metadata: m };
127
+ };
128
+ const orchestrator = agent(config.orchestrator, 'orchestrator');
129
+ const subagents = (config.subagents ?? []).map((s, i) => agent(s, `subagents.${i}`));
130
+ const changed = meta !== config.metadata || orchestrator !== config.orchestrator || subagents.some((s, i) => s !== config.subagents?.[i]);
131
+ return changed ? { ...config, ...(meta ? { metadata: meta } : {}), orchestrator, subagents } : config;
132
+ }
115
133
  /** Labels already warned about, so a server loading one file per request warns once per process. */
116
134
  const warnedV1 = new Set();
117
135
  /**
@@ -59,12 +59,16 @@ export function modelExtractor(opts = {}) {
59
59
  toolsDict: {},
60
60
  };
61
61
  const request = llmRequestToModelRequest(llmRequest, { model, stream: false });
62
+ const sources = new WeakMap();
62
63
  async function* inner() {
63
- for await (const response of adapter.generate(request))
64
- yield modelResponseToLlmResponse(response);
64
+ for await (const response of adapter.generate(request)) {
65
+ const mapped = modelResponseToLlmResponse(response);
66
+ sources.set(mapped, response);
67
+ yield mapped;
68
+ }
65
69
  }
66
70
  let text = '';
67
- for await (const response of traceLlmGeneration({ provider: adapter.provider, model, request }, inner())) {
71
+ for await (const response of traceLlmGeneration({ provider: adapter.provider, model, request, source: (r) => sources.get(r) }, inner())) {
68
72
  if (response.errorCode) {
69
73
  throw new Error(`${model}: ${response.errorCode}${response.errorMessage ? ` — ${response.errorMessage}` : ''}`);
70
74
  }
@@ -35,6 +35,25 @@ export declare function agentOfSpanName(name: string): string | null;
35
35
  export declare function isToolSpanName(name: string): boolean;
36
36
  /** True for one agent step's model-call span: ADK's `call_llm`, the loop's `model.call`. */
37
37
  export declare function isModelCallSpan(name: string, scope: string): boolean;
38
+ /** What a span the ledger keeps is, as `adk_telemetry.kind` records it (ADR 0139). */
39
+ export type LedgerSpanKind = 'turn' | 'agent' | 'model' | 'tool' | 'script' | 'node';
40
+ /**
41
+ * The kind of a span the ledger keeps a row for, from its name, else null:
42
+ * the turn's root (`Syndicate Execution: <name>`), an agent's run
43
+ * (`agent.invoke`), a model step and each provider call in it (`model.call`,
44
+ * `llm.request`), a tool call (`tool.execute`), a script's run and calls
45
+ * (`script.invoke`, `script.call`), and a workflow's walk and node runs
46
+ * (`workflow.invoke`, `node.execute`). Every other span (a credential
47
+ * refresh, a library's own) stays out of the ledger.
48
+ */
49
+ export declare function ledgerSpanKind(name: string): LedgerSpanKind | null;
50
+ /**
51
+ * The attribute a span carries when its parent in the ledger is not its
52
+ * direct parent: the nearest ancestor the ledger keeps, which the tracer
53
+ * reads from its span lineage when the span starts, while every ancestor is
54
+ * still open (ADR 0139).
55
+ */
56
+ export declare const LEDGER_PARENT_ATTRIBUTE = "ledger.parent_span_id";
38
57
  /** JSON with object keys sorted at every depth — stable across reloads. */
39
58
  export declare function stableStringify(value: unknown): string;
40
59
  /** The config with every `yaml_reference` replaced by the loaded syndicate. */
@@ -58,6 +58,37 @@ export function isToolSpanName(name) {
58
58
  export function isModelCallSpan(name, scope) {
59
59
  return (name === 'call_llm' && scope === ADK_SPAN_SCOPE) || (name === 'model.call' && scope === RUNTIME_SPAN_SCOPE);
60
60
  }
61
+ /**
62
+ * The kind of a span the ledger keeps a row for, from its name, else null:
63
+ * the turn's root (`Syndicate Execution: <name>`), an agent's run
64
+ * (`agent.invoke`), a model step and each provider call in it (`model.call`,
65
+ * `llm.request`), a tool call (`tool.execute`), a script's run and calls
66
+ * (`script.invoke`, `script.call`), and a workflow's walk and node runs
67
+ * (`workflow.invoke`, `node.execute`). Every other span (a credential
68
+ * refresh, a library's own) stays out of the ledger.
69
+ */
70
+ export function ledgerSpanKind(name) {
71
+ if (name.startsWith('Syndicate Execution: '))
72
+ return 'turn';
73
+ if (name === 'llm.request' || name === 'model.call')
74
+ return 'model';
75
+ if (name.startsWith('agent.invoke '))
76
+ return 'agent';
77
+ if (name.startsWith('tool.execute '))
78
+ return 'tool';
79
+ if (name.startsWith('script.invoke ') || name.startsWith('script.call '))
80
+ return 'script';
81
+ if (name.startsWith('workflow.invoke ') || name.startsWith('node.execute '))
82
+ return 'node';
83
+ return null;
84
+ }
85
+ /**
86
+ * The attribute a span carries when its parent in the ledger is not its
87
+ * direct parent: the nearest ancestor the ledger keeps, which the tracer
88
+ * reads from its span lineage when the span starts, while every ancestor is
89
+ * still open (ADR 0139).
90
+ */
91
+ export const LEDGER_PARENT_ATTRIBUTE = 'ledger.parent_span_id';
61
92
  /** JSON with object keys sorted at every depth — stable across reloads. */
62
93
  export function stableStringify(value) {
63
94
  if (value === null || typeof value !== 'object')