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.
- package/CHANGELOG.md +131 -1
- package/DOCUMENTATION.md +66 -4
- package/README.md +2 -0
- package/config/agents/syndicate.schema.json +69 -0
- package/config/agents/syndicateSchema.yaml +17 -0
- package/db/hardening.sql +3 -1
- package/db/migrations/0016_span_tree.sql +52 -0
- package/db/migrations/0017_cache_pricing.sql +146 -0
- package/db/migrations/0018_queue_view.sql +82 -0
- package/db/telemetry.sql +36 -8
- package/dist/lib/a2a/app.d.ts +26 -4
- package/dist/lib/a2a/app.js +41 -6
- package/dist/lib/a2a/executor.d.ts +28 -1
- package/dist/lib/a2a/executor.js +65 -2
- package/dist/lib/a2a/feedback.d.ts +121 -0
- package/dist/lib/a2a/feedback.js +219 -0
- package/dist/lib/a2a/policy.d.ts +55 -5
- package/dist/lib/a2a/policy.js +56 -12
- package/dist/lib/compile.d.ts +2 -0
- package/dist/lib/compile.js +2 -0
- package/dist/lib/compileNative.js +2 -0
- package/dist/lib/index.d.ts +5 -2
- package/dist/lib/index.js +1 -0
- package/dist/lib/loadSyndicate.d.ts +14 -0
- package/dist/lib/loadSyndicate.js +19 -1
- package/dist/lib/memory/providers.js +7 -3
- package/dist/lib/observability/lineage.d.ts +19 -0
- package/dist/lib/observability/lineage.js +31 -0
- package/dist/lib/observability/metadata.d.ts +69 -0
- package/dist/lib/observability/metadata.js +153 -0
- package/dist/lib/observability/otlpFilter.js +1 -0
- package/dist/lib/observability/supabaseSpanExporter.d.ts +31 -2
- package/dist/lib/observability/supabaseSpanExporter.js +45 -6
- package/dist/lib/observability/tracer.d.ts +17 -1
- package/dist/lib/observability/tracer.js +61 -3
- package/dist/lib/project.js +1 -1
- package/dist/lib/runtime/native/compaction.js +7 -3
- package/dist/lib/runtime/native/request.d.ts +2 -0
- package/dist/lib/runtime/native/step.js +1 -1
- package/dist/lib/runtime/native/telemetry.d.ts +10 -3
- package/dist/lib/runtime/native/telemetry.js +49 -4
- package/dist/lib/runtime/syndicateTurn.js +5 -1
- package/dist/lib/storage/postgres/index.d.ts +10 -0
- package/dist/lib/storage/postgres/index.js +6 -1
- package/dist/lib/syndicateSchema.d.ts +5 -0
- package/dist/lib/syndicateSchema.js +13 -0
- package/dist/lib/tools/taskTools.d.ts +6 -0
- package/dist/lib/tools/taskTools.js +24 -5
- package/dist/lib/workflow/toolNode.d.ts +1 -0
- package/dist/lib/workflow/toolNode.js +1 -1
- 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
|
+
}
|
package/dist/lib/a2a/policy.d.ts
CHANGED
|
@@ -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 {};
|
package/dist/lib/a2a/policy.js
CHANGED
|
@@ -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
|
|
155
|
-
|
|
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
|
|
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
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
}
|
package/dist/lib/compile.d.ts
CHANGED
|
@@ -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
|
package/dist/lib/compile.js
CHANGED
|
@@ -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
|
/**
|
package/dist/lib/index.d.ts
CHANGED
|
@@ -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
|
-
|
|
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')
|