melchizedek-agents 1.7.0 → 1.10.0

package/dist/lib/a2a/executor.js

@@ -26,6 +26,7 @@ import { deepestPause, delegatedPauses, routePause } from '../runtime/native/int
 import { isWorkflowSyndicate } from '../workflow.js';
 import { describeInput } from '../runtime/syndicateTurn.js';
 import { describeConsent } from '../runtime/credentials.js';
+import { MAX_META_KEYS, metaAttributes, requestMetadata } from '../observability/metadata.js';
 export const requestContextStorage = new AsyncLocalStorage();
 /** The app name every A2A session and memory silo is stored under. */
 export const A2A_APP_NAME = 'melchizedek-a2a';
@@ -52,6 +53,64 @@ export function surfaceAttributes(ctx) {
         attrs['surface.user'] = s.user;
     return attrs;
 }
+/**
+ * A request's metadata as root-span attributes (ADR 0141): the
+ * `X-Melch-Meta-*` headers, then the A2A message's `metadata` object (a
+ * header wins a key both name), never a key the YAML's own `metadata:`
+ * declares, and at most as many keys as the YAML leaves of the 32.
+ */
+export function requestMetaAttributes(ctx, messageMetadata, config, warn) {
+    const declared = Object.keys(config.metadata ?? {});
+    const meta = requestMetadata([ctx?.meta, messageMetadata], {
+        reserved: new Set(declared),
+        room: MAX_META_KEYS - declared.length,
+        ...(warn ? { warn } : {}),
+    });
+    return metaAttributes(meta);
+}
+const STATE_NAMES = {
+    [TaskState.TASK_STATE_SUBMITTED]: 'submitted',
+    [TaskState.TASK_STATE_WORKING]: 'working',
+    [TaskState.TASK_STATE_INPUT_REQUIRED]: 'input-required',
+    [TaskState.TASK_STATE_COMPLETED]: 'completed',
+    [TaskState.TASK_STATE_FAILED]: 'failed',
+    [TaskState.TASK_STATE_CANCELED]: 'canceled',
+    [TaskState.TASK_STATE_REJECTED]: 'rejected',
+    [TaskState.TASK_STATE_AUTH_REQUIRED]: 'auth-required',
+};
+/**
+ * The bus, with `onState` called after each published event that moves the
+ * task to a new state (the task itself, then each status update whose state
+ * differs from the last: the `[STATUS]` lines of a working task are one
+ * state). A throwing observer never reaches the task.
+ */
+function observeStates(bus, onState) {
+    let last;
+    const publish = (event) => {
+        bus.publish(event);
+        const raw = event.kind === 'task' ? event.data.status?.state : event.kind === 'statusUpdate' ? event.data.status?.state : undefined;
+        if (raw === undefined)
+            return;
+        const state = STATE_NAMES[raw] ?? 'unknown';
+        if (state === last)
+            return;
+        last = state;
+        try {
+            onState(state);
+        }
+        catch {
+            /* an observer must not fail the task */
+        }
+    };
+    return new Proxy(bus, {
+        get(target, prop) {
+            if (prop === 'publish')
+                return publish;
+            const value = Reflect.get(target, prop, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
 /** One human-readable line naming WHY a turn failed, for the failed task's
  *  status message — the text a client renders verbatim. Provider errors
  *  sometimes arrive as a raw JSON blob (Gemini ApiError), so the inner
@@ -465,11 +524,15 @@ export class SyndicateExecutor {
         }
         return this.configHash;
     }
-    async execute(requestContext, eventBus) {
+    async execute(requestContext, published) {
         const { config, log, warn } = this.opts;
         const message = requestContext.userMessage;
         const contextId = requestContext.contextId;
         const taskId = requestContext.taskId;
+        const onTaskState = this.opts.onTaskState;
+        const eventBus = onTaskState
+            ? observeStates(published, (state) => onTaskState({ taskId, contextId, state, syndicate: config.syndicate_name, agentId: this.opts.agentId ?? '', ...(traceId ? { traceId } : {}), at: Date.now() }))
+            : published;
         const short = taskId.slice(0, 8);
         let slot;
         let releaseTurn = null;
@@ -655,7 +718,7 @@ export class SyndicateExecutor {
                 trace: {
                     taskId,
                     configHash: this.configHashFor(),
-                    attributes: surfaceAttributes(ctx),
+                    attributes: { ...surfaceAttributes(ctx), ...requestMetaAttributes(ctx, message?.metadata, config, warn) },
                     traceparent: ctx.traceparent,
                     onSpanStart: (ids) => {
                         traceId = ids.traceId;

package/dist/lib/a2a/feedback.d.ts

@@ -0,0 +1,121 @@
+/**
+ * lib/a2a/feedback.ts — end-user feedback on a served turn (ADR 0140):
+ * `POST /feedback` and `POST /<agentId>/feedback`.
+ *
+ *   POST /feedback
+ *   { "traceId": "4bf9…", "score": "down", "comment": "Wrong refund policy", "userId": "u-123" }
+ *
+ * The body names the turn by exactly one of `taskId` (the A2A task) or
+ * `traceId` (the ledger's), a `score` of 'up' | 'down' or an integer 1–5,
+ * and optionally a `comment` (≤ 4,000 characters) and the product's own
+ * `userId`. It lands in the ledger as one `adk_labels` row:
+ *
+ *   ref = trace_id = the turn's trace id, labeler = 'end-user',
+ *   fields = { score, userId }   (userId null when none was sent),
+ *   note = the comment through the telemetry redactor (null when none)
+ *
+ * The route sits behind the same bearer check, authenticator, failed-auth
+ * limiter and task rate limit as the A2A routes, with its own body limit
+ * (32 KB). A caller rates only turns it could have run: the turn's
+ * `user_id` must be the caller's scope (or one beneath a scope that owns
+ * nested ones), unless the caller holds an operator credential; anything
+ * else answers the same 404 as a turn that does not exist. One label per
+ * (turn, userId) per minute, per process; without a userId the caller's
+ * scope stands in. Answers never repeat what was sent.
+ */
+import type { RequestHandler } from 'express';
+import type { Redactor } from '../observability/redact.ts';
+import type { A2AContext } from './executor.ts';
+/** The labeler every end-user feedback row carries. */
+export declare const END_USER_LABELER = "end-user";
+/** The route's own JSON body limit. */
+export declare const FEEDBACK_BODY_LIMIT = "32kb";
+/** The longest comment accepted, in characters. */
+export declare const FEEDBACK_COMMENT_MAX = 4000;
+/** One label per (turn, user) in this window. */
+export declare const FEEDBACK_WINDOW_MS = 60000;
+export type FeedbackScore = 'up' | 'down' | 1 | 2 | 3 | 4 | 5;
+/** The adk_labels row a feedback request writes (the columns it names; the rest keep their defaults). */
+export interface FeedbackRow {
+    ref: string;
+    trace_id: string;
+    labeler: typeof END_USER_LABELER;
+    fields: {
+        score: FeedbackScore;
+        userId: string | null;
+    };
+    note: string | null;
+}
+/** The turn a feedback request names, as the ledger holds it. */
+export interface FeedbackTurn {
+    traceId: string;
+    /** adk_turns.user_id: the scope key the turn ran under. */
+    userId: string | null;
+}
+/** Where feedback is read from and written to: the telemetry ledger. */
+export interface FeedbackStore {
+    /** The turn by its A2A task id or its trace id; null when the ledger has no such turn. */
+    turn(ref: {
+        taskId: string;
+    } | {
+        traceId: string;
+    }): Promise<FeedbackTurn | null>;
+    /** Appends one label. */
+    add(row: FeedbackRow): Promise<void>;
+}
+export interface ParsedFeedback {
+    ref: {
+        taskId: string;
+    } | {
+        traceId: string;
+    };
+    score: FeedbackScore;
+    comment: string | null;
+    userId: string | null;
+}
+/** Validates a feedback body. The error names the rule broken, never the value. */
+export declare function parseFeedback(body: unknown): {
+    ok: true;
+    value: ParsedFeedback;
+} | {
+    ok: false;
+    error: string;
+};
+/** The row a parsed request writes for a turn, the comment through `redactor` (none: kept as sent). */
+export declare function feedbackRow(traceId: string, f: Pick<ParsedFeedback, 'score' | 'comment' | 'userId'>, redactor: Redactor | undefined): FeedbackRow;
+/** May this caller rate a turn that ran under `turnUserId`? */
+export declare function mayRate(ctx: Pick<A2AContext, 'scopeKey' | 'ownsNested' | 'operator'>, turnUserId: string | null): boolean;
+/** One label per key per window, in this process. Keys are hashes; the map is swept as it grows. */
+export declare function feedbackLimiter(windowMs?: number, now?: () => number): {
+    /** Reserves the key; the ms to wait when it is taken. */
+    take(key: string): {
+        ok: true;
+    } | {
+        ok: false;
+        retryAfterMs: number;
+    };
+    /** Gives a reservation back (the write failed). */
+    release(key: string): void;
+};
+/** The JSON parser for the feedback routes: 32 KB, and its errors answered as JSON without the body. */
+export declare function feedbackBodyParser(): RequestHandler;
+export interface FeedbackHandlerOptions {
+    store: FeedbackStore | undefined;
+    /** The caller context the identity middleware set. */
+    context: () => A2AContext | undefined;
+    /** Validates `:agentId` on the per-agent route; false answers 404. */
+    agentServed?: (agentId: string) => boolean;
+    limiter?: ReturnType<typeof feedbackLimiter>;
+    log?: (m: string) => void;
+    warn?: (m: string) => void;
+}
+/** The route handler; mount it after authentication, with its body parsed by feedbackBodyParser(). */
+export declare function feedbackHandler(opts: FeedbackHandlerOptions): RequestHandler;
+/** Matches the feedback routes' paths, so the server-wide JSON parser leaves their bodies to feedbackBodyParser. */
+export declare const isFeedbackPath: (path: string) => boolean;
+/** A FeedbackStore over a Postgres pool holding the ledger (db/telemetry.sql). */
+export declare function postgresFeedbackStore(pool: {
+    query: (sql: string, params?: unknown[]) => Promise<{
+        rows: any[];
+    }>;
+}): FeedbackStore;

package/dist/lib/a2a/feedback.js

@@ -0,0 +1,219 @@
+/**
+ * lib/a2a/feedback.ts — end-user feedback on a served turn (ADR 0140):
+ * `POST /feedback` and `POST /<agentId>/feedback`.
+ *
+ *   POST /feedback
+ *   { "traceId": "4bf9…", "score": "down", "comment": "Wrong refund policy", "userId": "u-123" }
+ *
+ * The body names the turn by exactly one of `taskId` (the A2A task) or
+ * `traceId` (the ledger's), a `score` of 'up' | 'down' or an integer 1–5,
+ * and optionally a `comment` (≤ 4,000 characters) and the product's own
+ * `userId`. It lands in the ledger as one `adk_labels` row:
+ *
+ *   ref = trace_id = the turn's trace id, labeler = 'end-user',
+ *   fields = { score, userId }   (userId null when none was sent),
+ *   note = the comment through the telemetry redactor (null when none)
+ *
+ * The route sits behind the same bearer check, authenticator, failed-auth
+ * limiter and task rate limit as the A2A routes, with its own body limit
+ * (32 KB). A caller rates only turns it could have run: the turn's
+ * `user_id` must be the caller's scope (or one beneath a scope that owns
+ * nested ones), unless the caller holds an operator credential; anything
+ * else answers the same 404 as a turn that does not exist. One label per
+ * (turn, userId) per minute, per process; without a userId the caller's
+ * scope stands in. Answers never repeat what was sent.
+ */
+import { createHash } from 'node:crypto';
+import express from 'express';
+import { z } from 'zod';
+import { REDACTION_PATTERNS, telemetryRedactor } from '../observability/redact.js';
+/** The labeler every end-user feedback row carries. */
+export const END_USER_LABELER = 'end-user';
+/** The route's own JSON body limit. */
+export const FEEDBACK_BODY_LIMIT = '32kb';
+/** The longest comment accepted, in characters. */
+export const FEEDBACK_COMMENT_MAX = 4_000;
+/** One label per (turn, user) in this window. */
+export const FEEDBACK_WINDOW_MS = 60_000;
+const ID = /^[A-Za-z0-9._:-]{1,128}$/;
+const USER_ID = /^[A-Za-z0-9._@:+/-]{1,128}$/;
+const bodySchema = z.strictObject({
+    taskId: z.string().regex(ID).optional(),
+    traceId: z.string().regex(ID).optional(),
+    score: z.union([z.enum(['up', 'down']), z.number().int().min(1).max(5)]),
+    comment: z.string().max(FEEDBACK_COMMENT_MAX).optional(),
+    userId: z.string().regex(USER_ID).optional(),
+});
+/** Field-level messages that name the field and the rule, never the value sent. */
+const MESSAGES = {
+    taskId: 'taskId must be 1–128 characters of [A-Za-z0-9._:-].',
+    traceId: 'traceId must be 1–128 characters of [A-Za-z0-9._:-].',
+    score: "score must be 'up', 'down' or an integer from 1 to 5.",
+    comment: `comment must be a string of at most ${FEEDBACK_COMMENT_MAX.toLocaleString('en-US')} characters.`,
+    userId: 'userId must be 1–128 characters of [A-Za-z0-9._@:+/-].',
+};
+/** Validates a feedback body. The error names the rule broken, never the value. */
+export function parseFeedback(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return { ok: false, error: 'Send a JSON object body (Content-Type: application/json).' };
+    const r = bodySchema.safeParse(body);
+    if (!r.success) {
+        const issue = r.error.issues[0];
+        if (issue.code === 'unrecognized_keys')
+            return { ok: false, error: 'Unknown field; the body takes taskId or traceId, score, comment and userId.' };
+        const field = String(issue.path[0] ?? '');
+        return { ok: false, error: MESSAGES[field] ?? 'Invalid feedback body.' };
+    }
+    const { taskId, traceId, score, comment, userId } = r.data;
+    if ((taskId === undefined) === (traceId === undefined))
+        return { ok: false, error: 'Name the turn with exactly one of taskId or traceId.' };
+    if (userId && new RegExp(REDACTION_PATTERNS.secret.source).test(userId))
+        return { ok: false, error: 'userId looks like a credential; send the product’s own user id.' };
+    return {
+        ok: true,
+        value: {
+            ref: taskId !== undefined ? { taskId } : { traceId: traceId },
+            score: score,
+            comment: comment && comment.trim() ? comment : null,
+            userId: userId ?? null,
+        },
+    };
+}
+/** The row a parsed request writes for a turn, the comment through `redactor` (none: kept as sent). */
+export function feedbackRow(traceId, f, redactor) {
+    return {
+        ref: traceId,
+        trace_id: traceId,
+        labeler: END_USER_LABELER,
+        fields: { score: f.score, userId: f.userId },
+        note: f.comment === null ? null : redactor ? redactor(f.comment) : f.comment,
+    };
+}
+/** May this caller rate a turn that ran under `turnUserId`? */
+export function mayRate(ctx, turnUserId) {
+    if (ctx.operator)
+        return true;
+    if (!turnUserId)
+        return false;
+    return turnUserId === ctx.scopeKey || (!!ctx.ownsNested && turnUserId.startsWith(`${ctx.scopeKey}/`));
+}
+/** One label per key per window, in this process. Keys are hashes; the map is swept as it grows. */
+export function feedbackLimiter(windowMs = FEEDBACK_WINDOW_MS, now = Date.now) {
+    const until = new Map();
+    const sweep = () => {
+        const t = now();
+        for (const [k, v] of until)
+            if (v <= t)
+                until.delete(k);
+    };
+    return {
+        /** Reserves the key; the ms to wait when it is taken. */
+        take(key) {
+            const t = now();
+            const held = until.get(key);
+            if (held !== undefined && held > t)
+                return { ok: false, retryAfterMs: held - t };
+            if (until.size >= 10_000)
+                sweep();
+            until.set(key, t + windowMs);
+            return { ok: true };
+        },
+        /** Gives a reservation back (the write failed). */
+        release(key) {
+            until.delete(key);
+        },
+    };
+}
+/** The JSON parser for the feedback routes: 32 KB, and its errors answered as JSON without the body. */
+export function feedbackBodyParser() {
+    const parse = express.json({ limit: FEEDBACK_BODY_LIMIT });
+    return (req, res, next) => {
+        parse(req, res, (err) => {
+            if (!err)
+                return next();
+            const e = err;
+            if (e.type === 'entity.too.large' || e.status === 413) {
+                res.status(413).json({ error: `The feedback body is over ${FEEDBACK_BODY_LIMIT.toUpperCase()}.` });
+                return;
+            }
+            res.status(400).json({ error: 'The body is not valid JSON.' });
+        });
+    };
+}
+/** The route handler; mount it after authentication, with its body parsed by feedbackBodyParser(). */
+export function feedbackHandler(opts) {
+    const limiter = opts.limiter ?? feedbackLimiter();
+    return async (req, res) => {
+        const agentId = typeof req.params?.agentId === 'string' ? req.params.agentId : undefined;
+        if (agentId !== undefined && opts.agentServed && !opts.agentServed(agentId)) {
+            res.status(404).json({ error: 'Unknown agent.' });
+            return;
+        }
+        if (!opts.store) {
+            res.status(501).json({ error: 'Feedback needs the telemetry ledger; this server has none configured.' });
+            return;
+        }
+        const ctx = opts.context();
+        if (!ctx) {
+            res.status(401).json({ error: 'No authentication context.' });
+            return;
+        }
+        const parsed = parseFeedback(req.body);
+        if (!parsed.ok) {
+            res.status(400).json({ error: parsed.error });
+            return;
+        }
+        const f = parsed.value;
+        let turn;
+        try {
+            turn = await opts.store.turn(f.ref);
+        }
+        catch (err) {
+            opts.warn?.(`Feedback: the ledger could not be read (${err instanceof Error ? err.message : String(err)}).`);
+            res.status(503).json({ error: 'The ledger is unavailable; retry shortly.' });
+            return;
+        }
+        // Not found and not yours answer alike: a caller cannot probe for other people's turns.
+        if (!turn || !mayRate(ctx, turn.userId)) {
+            res.status(404).json({ error: 'No turn with that id (a turn reaches the ledger a few seconds after it ends).' });
+            return;
+        }
+        const who = f.userId !== null ? `user:${f.userId}` : `scope:${ctx.scopeKey}`;
+        const key = createHash('sha256').update(`${turn.traceId}\u0000${who}`).digest('hex');
+        const slot = limiter.take(key);
+        if (!slot.ok) {
+            res.setHeader('Retry-After', String(Math.ceil(slot.retryAfterMs / 1000)));
+            res.status(429).json({ error: 'Feedback on this turn from this user was just recorded; one per minute.' });
+            return;
+        }
+        try {
+            await opts.store.add(feedbackRow(turn.traceId, f, telemetryRedactor()));
+        }
+        catch (err) {
+            limiter.release(key);
+            opts.warn?.(`Feedback: the label was not written (${err instanceof Error ? err.message : String(err)}).`);
+            res.status(503).json({ error: 'The feedback could not be stored; retry shortly.' });
+            return;
+        }
+        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' : ''}`);
+        res.status(201).json({ ok: true, traceId: turn.traceId });
+    };
+}
+/** Matches the feedback routes' paths, so the server-wide JSON parser leaves their bodies to feedbackBodyParser. */
+export const isFeedbackPath = (path) => path === '/feedback' || /^\/[^/]+\/feedback$/.test(path);
+/** A FeedbackStore over a Postgres pool holding the ledger (db/telemetry.sql). */
+export function postgresFeedbackStore(pool) {
+    return {
+        async turn(ref) {
+            const byTask = 'taskId' in ref;
+            const { rows } = await pool.query(
+            // A dispatch task has a classifier turn beside its answer: the answer is the one rated.
+            `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]);
+            const r = rows[0];
+            return r ? { traceId: String(r.trace_id), userId: r.user_id == null ? null : String(r.user_id) } : null;
+        },
+        async add(row) {
+            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]);
+        },
+    };
+}

package/dist/lib/a2a/policy.d.ts

@@ -95,16 +95,66 @@ export type BudgetConfig = z.infer<typeof budgetsSchema>;
 export declare function parseBudgets(json: string): BudgetConfig;
 /** A scope as a counter subject: hashed, so the usage table holds no user identifier. */
 export declare const scopeSubject: (scopeKey: string) => string;
+/** Where a subject stands against its limits today. */
+export type BudgetLevel = 'ok' | 'warn' | 'over';
+/**
+ * One subject's standing, as `onBudgetState` reports it: after every task
+ * it recorded (cause 'record'), and when a task arrives over a limit
+ * (cause 'admit'; `stopped` says whether it was refused). Counts only,
+ * never user text; the scope is its hash.
+ */
+export interface BudgetState {
+    /** `caller:<name>` or `scope:<SHA-256 prefix>` (scopeSubject). */
+    subject: string;
+    /** The UTC day counted (YYYY-MM-DD). */
+    day: string;
+    /** The subject's totals for the day, this task included. */
+    usage: DailyUsage;
+    /** The limits that apply to the subject; undefined when none do. */
+    limits?: BudgetLimits;
+    /** 'over' at or past any limit, 'warn' at or past `warnAt` of one, else 'ok'. */
+    level: BudgetLevel;
+    /** The limit reached, as the refusal names it ('2,000,000 tokens'), when over. */
+    reached?: string;
+    cause: 'record' | 'admit';
+    /** The agent id the task was sent to ('' or 'default' for the boot syndicate). */
+    agentId: string;
+    /** With cause 'admit': true when the task was refused, false when it went ahead over the limit (hardStop: false). */
+    stopped?: boolean;
+}
+/**
+ * A stop decided outside the daily limits, at admission: return a reason to
+ * refuse the task with it, or undefined to admit it. Throwing refuses (fail
+ * closed). A desktop app serving locally passes its own month's spend check.
+ */
+export type HardStop = (subject: PolicySubject) => string | undefined | Promise<string | undefined>;
+export interface BudgetOptions {
+    store?: UsageStore;
+    now?: () => Date;
+    /**
+     * Called with each subject's standing after a task is recorded, and when
+     * a task arrives over a limit, so a consumer can mirror a deployment's spend. Errors are
+     * swallowed; it never delays or fails a task beyond its own runtime.
+     */
+    onBudgetState?: (state: BudgetState) => void | Promise<void>;
+    /** The share of a limit at which the level is 'warn'. Default 0.8. */
+    warnAt?: number;
+    /**
+     * true (default): a subject at a limit is refused. false: the limits only
+     * report ('over' through onBudgetState) and tasks go ahead. A function:
+     * the limits refuse, and the function is asked as well (HardStop).
+     */
+    hardStop?: boolean | HardStop;
+}
 /**
  * Daily budgets per caller and per scope. A request is refused when the
  * caller or its scope has reached any limit today (UTC); the message says
  * which and when it resets. A store failure refuses (fail closed) — a
- * budget that cannot be read is not a budget.
+ * budget that cannot be read is not a budget. `onBudgetState` mirrors each
+ * subject's standing; `hardStop` makes the limits advisory, or adds an
+ * outside stop (BudgetOptions).
  */
-export declare function budgets(config: BudgetConfig, opts?: {
-    store?: UsageStore;
-    now?: () => Date;
-}): Policy & {
+export declare function budgets(config: BudgetConfig, opts?: BudgetOptions): Policy & {
     store: UsageStore;
 };
 export {};

package/dist/lib/a2a/policy.js

@@ -137,42 +137,86 @@ function over(limits, u) {
         return `${limits.tokens.toLocaleString('en-US')} tokens`;
     return undefined;
 }
+function levelOf(limits, u, warnAt) {
+    if (!limits)
+        return 'ok';
+    if (over(limits, u))
+        return 'over';
+    const near = (used, limit) => limit !== undefined && used >= limit * warnAt;
+    return near(u.tasks, limits.tasks) || near(u.llmCalls, limits.llmCalls) || near(tokensOf(u), limits.tokens) ? 'warn' : 'ok';
+}
 /**
  * Daily budgets per caller and per scope. A request is refused when the
  * caller or its scope has reached any limit today (UTC); the message says
  * which and when it resets. A store failure refuses (fail closed) — a
- * budget that cannot be read is not a budget.
+ * budget that cannot be read is not a budget. `onBudgetState` mirrors each
+ * subject's standing; `hardStop` makes the limits advisory, or adds an
+ * outside stop (BudgetOptions).
  */
 export function budgets(config, opts = {}) {
     const store = opts.store ?? memoryUsageStore();
     const now = opts.now ?? (() => new Date());
+    const warnAt = opts.warnAt !== undefined && opts.warnAt > 0 && opts.warnAt <= 1 ? opts.warnAt : 0.8;
+    const enforce = opts.hardStop !== false;
+    const outsideStop = typeof opts.hardStop === 'function' ? opts.hardStop : undefined;
     const callerLimits = (caller) => (caller && config.callers?.[caller]) || config.perCaller;
+    const subjectsOf = (s) => [
+        ...(s.caller ? [[`caller:${s.caller}`, callerLimits(s.caller)]] : []),
+        [scopeSubject(s.scopeKey), config.perScope],
+    ];
+    const report = async (state) => {
+        if (!opts.onBudgetState)
+            return;
+        try {
+            await opts.onBudgetState(state);
+        }
+        catch {
+            /* a broken mirror must not touch the task */
+        }
+    };
     return {
         store,
         async admit(s) {
             const day = today(now);
-            const checks = [
-                [s.caller ? `caller:${s.caller}` : '', s.caller ? callerLimits(s.caller) : undefined],
-                [scopeSubject(s.scopeKey), config.perScope],
-            ];
-            for (const [subject, limits] of checks) {
-                if (!subject || !limits)
+            for (const [subject, limits] of subjectsOf(s)) {
+                if (!limits)
                     continue;
-                const hit = over(limits, await store.get(day, subject));
+                const usage = await store.get(day, subject);
+                const hit = over(limits, usage);
                 if (hit) {
+                    await report({ subject, day, usage, limits, level: 'over', reached: hit, cause: 'admit', agentId: s.agentId, stopped: enforce });
+                    if (!enforce)
+                        continue;
                     const who = subject.startsWith('caller:') ? `Caller '${s.caller}'` : 'This user';
                     return { ok: false, reason: `${who} has used today's budget of ${hit}. It resets at 00:00 UTC.` };
                 }
             }
+            if (outsideStop) {
+                const reason = await outsideStop(s);
+                if (reason)
+                    return { ok: false, reason };
+            }
             return { ok: true };
         },
         async record(s, usage) {
             const day = today(now);
             const delta = { tasks: 1, ...usage };
-            const writes = [store.add(day, scopeSubject(s.scopeKey), delta)];
-            if (s.caller)
-                writes.push(store.add(day, `caller:${s.caller}`, delta));
-            await Promise.all(writes);
+            const subjects = subjectsOf(s);
+            await Promise.all(subjects.map(([subject]) => store.add(day, subject, delta)));
+            if (!opts.onBudgetState)
+                return;
+            for (const [subject, limits] of subjects) {
+                let totals;
+                try {
+                    totals = await store.get(day, subject);
+                }
+                catch {
+                    continue; // the spend is recorded; only the mirror misses this one
+                }
+                const level = levelOf(limits, totals, warnAt);
+                const reached = level === 'over' ? over(limits, totals) : undefined;
+                await report({ subject, day, usage: totals, ...(limits ? { limits } : {}), level, ...(reached ? { reached } : {}), cause: 'record', agentId: s.agentId });
+            }
         },
     };
 }

package/dist/lib/compile.d.ts

@@ -208,6 +208,8 @@ export interface AgentSpec {
     mode?: 'task';
     /** The syndicate's `max_concurrency`, on its orchestrator (ADR 0116): delegated calls one step runs at once. */
     maxConcurrency?: number;
+    /** `metadata:` (ADR 0141): `meta.agent.<key>` on the agent's span. */
+    metadata?: Record<string, string | number | boolean>;
 }
 /**
  * The spec of a workflow syndicate: every agent through compileSubagentSpec

package/dist/lib/compile.js

@@ -270,6 +270,8 @@ function specOf(yaml, name, description, instruction, tools, { resolvedModel, mo
         spec.context = yaml.context;
     if (yaml.mode)
         spec.mode = yaml.mode;
+    if (yaml.metadata && Object.keys(yaml.metadata).length)
+        spec.metadata = yaml.metadata;
     return spec;
 }
 const asTools = (tools) => tools.map((tool) => ({ kind: 'tool', tool }));

package/dist/lib/compileNative.js

@@ -149,6 +149,8 @@ export function compileNative(spec) {
         agent.context = spec.context;
     if (spec.maxConcurrency !== undefined)
         agent.maxConcurrency = spec.maxConcurrency;
+    if (spec.metadata)
+        agent.metadata = spec.metadata;
     return agent;
 }
 /**

package/dist/lib/doctor.d.ts

@@ -27,6 +27,7 @@ import type { Platform } from './models/endpoints.ts';
 import type { CapabilityGap, CapabilityReport } from './models/capabilities.ts';
 import type { ProviderId } from './models/providerMap.ts';
 import type { RuntimeName, RuntimeSource } from './runtime/runtimeFlag.ts';
+import { type ProjectCheck } from './project.ts';
 /**
  * What a file costs to run: `keyless` (all Ollama), a single provider's id
  * when every agent shares one (`gemini`, `anthropic`, `openai`, `xai` — one
@@ -169,7 +170,16 @@ export interface DoctorResult {
     serving?: DoctorServing;
     /** A stored Sign in with ChatGPT credential (ADR 0126), when one is present or its variables are set. */
     chatgpt?: DoctorChatGpt;
+    /** The project manifest (ADR 0138) found from the working directory, when there is one. */
+    project?: DoctorProject;
 }
+/** A `melchizedek.json` at or above the working directory: its checks, or why it does not load. */
+export type DoctorProject = ProjectCheck | {
+    root: string;
+    error: string;
+    problems: string[];
+    warnings: string[];
+};
 /**
  * A Sign in with ChatGPT credential (ADR 0126): where it is, whether it is
  * signed in and carries OpenAI ids here, and what stops it. Never a token.