melchizedek-agents 1.8.0 → 1.10.0

package/db/migrations/0018_queue_view.sql

@@ -0,0 +1,82 @@
+-- ============================================================================
+-- 0018_queue_view — the job queue as an operator reads it (ADR 0021, 0113)
+-- ============================================================================
+-- A read model over melchizedek_tasks (migration 0009, checkpoint columns
+-- from 0014): one row per background job, with what an operator asks of a
+-- queue — is it stuck, how often was it tried, why did it fail. Todo items
+-- are not jobs and are left out. Nothing is stored; the view reads the
+-- table as it stands.
+--
+--   owner          the list the job belongs to (the caller's scope key;
+--                  '' for a shared list)
+--   id             the job's id within that list (t1, t2, …)
+--   title          the job's title as queued (user text)
+--   status         queued | running | done | failed | cancelled
+--   attempts       claims so far (a claim counts one, a retry resets it)
+--   retries        attempts beyond the first: GREATEST(attempts - 1, 0)
+--   max_attempts   the claims a job gets before an interruption fails it
+--                  (MAX_ATTEMPTS in lib/tools/taskTools.ts)
+--   dead_lettered  true when the job failed and will not run again unless
+--                  someone retries it (status 'failed')
+--   last_error     the error the job failed with, or why it was not retried
+--                  (cut at 1,000 characters when written)
+--   lease_owner    the worker holding a running job, and lease_until when
+--                  its claim runs out: a running job whose lease is past is
+--                  stuck until the next recover()
+--   has_checkpoint whether a resumable checkpoint is kept (running or
+--                  queued only), and checkpoint_at when it was saved
+--   created_at, started_at, finished_at, updated_at
+--
+-- Retry a dead-lettered or cancelled job with postgresStorage().retryTask
+-- (owner, id), the same rule task_update's `queued` applies. The view has
+-- the table's owner's privileges where security_invoker is not available
+-- (Postgres < 15), so it is revoked from the API roles here and in
+-- db/hardening.sql, like the table. Idempotent; safe to re-run.
+-- ============================================================================
+
+CREATE OR REPLACE VIEW melchizedek_task_queue AS
+  SELECT
+    t.owner,
+    t.id,
+    t.record->>'title'                                        AS title,
+    t.status,
+    COALESCE((t.record->>'attempts')::int, 0)                 AS attempts,
+    GREATEST(COALESCE((t.record->>'attempts')::int, 0) - 1, 0) AS retries,
+    2                                                         AS max_attempts,
+    (t.status = 'failed')                                     AS dead_lettered,
+    t.record->>'error'                                        AS last_error,
+    t.lease_owner,
+    t.lease_until,
+    (t.checkpoint IS NOT NULL)                                AS has_checkpoint,
+    t.checkpoint_at,
+    (t.record->>'created_at')::timestamptz                    AS created_at,
+    (t.record->>'started_at')::timestamptz                    AS started_at,
+    (t.record->>'finished_at')::timestamptz                   AS finished_at,
+    t.updated_at
+  FROM melchizedek_tasks t
+  WHERE t.kind = 'background';
+
+COMMENT ON VIEW melchizedek_task_queue IS
+  'Background jobs as an operator reads them: status, attempts, retries, dead_lettered, last_error, lease and checkpoint. Retry with postgresStorage().retryTask(owner, id). Migration 0018.';
+
+-- Postgres 15+: the view reads with the querying role's rights.
+DO $$
+BEGIN
+  IF current_setting('server_version_num')::int >= 150000 THEN
+    EXECUTE 'ALTER VIEW melchizedek_task_queue SET (security_invoker = true)';
+  END IF;
+END $$;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'anon') THEN
+    EXECUTE 'REVOKE ALL ON melchizedek_task_queue FROM anon';
+  END IF;
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'authenticated') THEN
+    EXECUTE 'REVOKE ALL ON melchizedek_task_queue FROM authenticated';
+  END IF;
+END $$;
+
+INSERT INTO melchizedek_schema_version (version, name)
+VALUES (18, '0018_queue_view')
+ON CONFLICT (version) DO NOTHING;

package/db/telemetry.sql

@@ -22,10 +22,14 @@
 --                  resolved syndicate that ran) and engine_version. Kept
 --                  indefinitely; full-text searchable. Eval runs land here
 --                  too, tagged eval_* so production views exclude them.
---   adk_telemetry  ONE ROW PER SPAN — the raw llm.request and root spans as
---                  before (v1 shape, now with the identity columns). Per-call
---                  tokens, latency and the agent that made the call. Small;
---                  kept indefinitely.
+--   adk_telemetry  ONE ROW PER SPAN the ledger keeps — the turn's root, each
+--                  agent run, model step (model.call) and provider call
+--                  (llm.request), tool call, script run and call, workflow
+--                  walk and node run — with its parent among them and its
+--                  kind, so the turn's span tree is stored (ADR 0139). Per-call
+--                  tokens, latency and the agent that made the call; a tool
+--                  call's arguments and the start of its result. Small; kept
+--                  indefinitely.
 --   adk_payloads   FULL REQUEST/RESPONSE PER MODEL CALL — the assembled
 --                  prompt (system instruction, history, tool schemas) and the
 --                  raw response. 10-100x the size of a turn row and repeats
@@ -47,7 +51,7 @@ CREATE TABLE IF NOT EXISTS adk_telemetry (
   ts              TIMESTAMPTZ NOT NULL DEFAULT now(),
   trace_id        TEXT NOT NULL,
   span_id         TEXT NOT NULL,
-  span_name       TEXT NOT NULL,          -- 'llm.request' | 'Syndicate Execution: <name>'
+  span_name       TEXT NOT NULL,          -- 'llm.request' | 'Syndicate Execution: <name>' | 'agent.invoke <name>' | ...
   syndicate       TEXT,                   -- syndicate name, when known
   agent           TEXT,                   -- the agent that made the call / answered the turn
   provider        TEXT,                   -- 'gemini' | 'anthropic' | 'openai' | 'xai' | 'ollama'
@@ -68,6 +72,23 @@ CREATE INDEX IF NOT EXISTS idx_adk_telemetry_ts      ON adk_telemetry (ts DESC);
 CREATE INDEX IF NOT EXISTS idx_adk_telemetry_trace   ON adk_telemetry (trace_id);
 CREATE INDEX IF NOT EXISTS idx_adk_telemetry_session ON adk_telemetry (session_id);
 
+-- The span tree (migration 0016_span_tree, ADR 0139), for a fresh install;
+-- 0016 adds the same columns to a ledger that already exists:
+--   parent_span_id      the nearest ancestor span the ledger keeps; NULL for a root
+--   kind                turn | agent | model | tool | script | node
+--   error               the span failed (status, error code, a tool's error response)
+--   cache_read_tokens   parts of input_tokens read from / written to the
+--   cache_write_tokens  provider's prompt cache: one call's, or a root's sum
+-- All NULL on rows written before 0016. Tokens and cost sit on llm.request
+-- rows (and a root's on the root): a model.call row carries neither, so a
+-- trace's rows sum without counting a call twice.
+ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS parent_span_id     TEXT;
+ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS kind               TEXT;
+ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS error              BOOLEAN;
+ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS cache_read_tokens  INTEGER;
+ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS cache_write_tokens INTEGER;
+CREATE INDEX IF NOT EXISTS idx_adk_telemetry_parent ON adk_telemetry (trace_id, parent_span_id);
+
 -- ── adk_turns: one row per turn — the system of record ───────────────────
 CREATE TABLE IF NOT EXISTS adk_turns (
   id                 BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
@@ -123,6 +144,10 @@ CREATE TABLE IF NOT EXISTS adk_turns (
   UNIQUE (trace_id, span_id)
 );
 
+-- Cache tokens summed over the turn's calls (migration 0016, ADR 0139).
+ALTER TABLE adk_turns ADD COLUMN IF NOT EXISTS cache_read_tokens  INTEGER;
+ALTER TABLE adk_turns ADD COLUMN IF NOT EXISTS cache_write_tokens INTEGER;
+
 CREATE INDEX IF NOT EXISTS idx_adk_turns_ts        ON adk_turns (ts DESC);
 CREATE INDEX IF NOT EXISTS idx_adk_turns_trace     ON adk_turns (trace_id);
 CREATE INDEX IF NOT EXISTS idx_adk_turns_session   ON adk_turns (session_id, ts);
@@ -167,8 +192,10 @@ CREATE INDEX IF NOT EXISTS idx_adk_turns_surface_user
 -- cost_usd is filled at write time by the trigger below from model_pricing
 -- (db/migrations/0015_model_pricing.sql), so both sinks and a replayed
 -- dead-letter spool get it, and the price table is the one source:
---   adk_telemetry  an llm.request row: its model and tokens. A root row: the
---                  turn's per-model usage on the span (syndicate.usage).
+--   adk_telemetry  an llm.request row: its model and tokens, cache reads and
+--                  writes at their own rates (migration 0017). A root row: the
+--                  turn's per-model usage on the span (syndicate.usage). Any
+--                  other row (an agent run, a model step, a tool call): NULL.
 --   adk_turns      the turn's per-model usage (attributes->'syndicate.usage',
 --                  the tracer sums each model's calls), so a turn that used
 --                  two models is priced per model, input summed per call.
@@ -225,7 +252,8 @@ BEGIN
     RETURN NEW;
   END IF;
   IF NEW.model IS NOT NULL THEN
-    NEW.cost_usd := melchizedek_cost_usd(NEW.model, NEW.input_tokens, NEW.output_tokens, NEW.thinking_tokens);
+    NEW.cost_usd := melchizedek_cost_usd(NEW.model, NEW.input_tokens, NEW.output_tokens, NEW.thinking_tokens,
+                                         NEW.cache_read_tokens::bigint, NEW.cache_write_tokens::bigint);
   ELSE
     NEW.cost_usd := melchizedek_usage_text_cost(NEW.span->'attributes'->>'syndicate.usage');
   END IF;

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

@@ -19,8 +19,10 @@
  *   5. BYOK headers → per-request AsyncLocalStorage context. Agent-card GETs
  *      are exempt from X-API-Key: discovery must not require a model key.
  *   6. Task rate limiter (POSTs only; polling GETs are exempt).
- *   7. Routes: the adopter's own (`routes`), DELETE /memory, the default
- *      syndicate at /a2a/*, and every other syndicate at /:agentId/a2a/*.
+ *   7. Routes: the adopter's own (`routes`), DELETE /memory, POST /feedback
+ *      and /:agentId/feedback (ADR 0140; their own 32 KB body limit), the
+ *      default syndicate at /a2a/*, and every other syndicate at
+ *      /:agentId/a2a/*.
  *
  * State that is per-process (documented, not hidden): the A2A task store,
  * the handler cache, the rate-limiter counters. Sessions and memory are
@@ -53,9 +55,10 @@ import type { AuditSink } from '../observability/audit.ts';
 export declare const DEFAULT_MAX_CONCURRENT_PER_SCOPE = 4;
 import type { EraseCounts } from '../memory/erase.ts';
 import type { Embedder, MemoryExtractor } from '../memory/providers.ts';
-import type { A2AContext } from './executor.ts';
+import type { A2AContext, TaskStateRecord } from './executor.ts';
 import type { IdentityScheme } from './identity.ts';
 import type { Policy } from './policy.ts';
+import type { FeedbackStore } from './feedback.ts';
 import type { TaskRecord } from '../observability/metrics.ts';
 import type { OAuthConsent, ToolCredentials } from '../tools/oauthConsent.ts';
 /** Agent ids address a config (file or "registry:<id>"): a safe charset only. */
@@ -117,6 +120,14 @@ export interface A2AAppOptions {
         rlsHardening?: () => Promise<RlsHardeningStatus>;
         /** Appends audit events (postgresStorage supplies one; ADR 0042). */
         audit?: AuditSink;
+        /**
+         * Where `POST /feedback` reads turns and writes end-user labels: the
+         * telemetry ledger (ADR 0140). postgresStorage supplies one when its
+         * `ledger` is on; `postgresFeedbackStore(pool)` (lib/a2a/feedback.ts)
+         * builds one on any pool holding db/telemetry.sql. Without it the
+         * route answers 501.
+         */
+        feedback?: FeedbackStore;
         /**
          * One turn at a time per conversation across instances (postgresStorage
          * supplies an advisory lock). Default: a lock in this process.
@@ -174,6 +185,15 @@ export interface A2AAppOptions {
     metricsToken?: string;
     /** One record per task, however it ended (structured logs, your own metrics). */
     onTaskEnd?: (record: TaskRecord) => void;
+    /**
+     * Every state a task enters, as the executor publishes it (ADR 0141):
+     * `submitted` first, `working` with its first progress line, then the
+     * state it ends in (`completed`, `failed`, `canceled`, `rejected`,
+     * `input-required`). A repeat of the same state is not reported again. For
+     * a live view of in-flight work; `tasks/get` answers the same state to a
+     * polling caller. A throwing hook is ignored.
+     */
+    onTaskState?: (record: TaskStateRecord) => void;
     /**
      * Credentials plug point (ADR 0017/0023): how a provider is reached for
      * this request — from a secret manager, per tenant, anywhere. Return an
@@ -194,7 +214,9 @@ export interface A2AAppOptions {
         extractor?: MemoryExtractor;
         embedder?: Embedder;
     };
-    /** Adopter routes, mounted after authentication and before the A2A routes. */
+    /** Adopter routes, mounted after authentication and before the A2A routes.
+     *  A POST to a path ending in /feedback (one segment deep) parses at the
+     *  feedback routes' 32 KB limit, not `bodyLimit`. */
     routes?: (app: Express) => void;
     /**
      * Tool credentials for every turn (ADR 0072): the sealed per-user store,

package/dist/lib/a2a/app.js

@@ -19,8 +19,10 @@
  *   5. BYOK headers → per-request AsyncLocalStorage context. Agent-card GETs
  *      are exempt from X-API-Key: discovery must not require a model key.
  *   6. Task rate limiter (POSTs only; polling GETs are exempt).
- *   7. Routes: the adopter's own (`routes`), DELETE /memory, the default
- *      syndicate at /a2a/*, and every other syndicate at /:agentId/a2a/*.
+ *   7. Routes: the adopter's own (`routes`), DELETE /memory, POST /feedback
+ *      and /:agentId/feedback (ADR 0140; their own 32 KB body limit), the
+ *      default syndicate at /a2a/*, and every other syndicate at
+ *      /:agentId/a2a/*.
  *
  * State that is per-process (documented, not hidden): the A2A task store,
  * the handler cache, the rate-limiter counters. Sessions and memory are
@@ -61,7 +63,9 @@ import { eraseScope } from '../memory/erase.js';
 import { namespacedMemoryService } from '../memory/namespace.js';
 import { memoryCrossesProviders, memoryDestinations } from '../memory/providers.js';
 import { A2A_APP_NAME, SyndicateExecutor, TaskLimiter, deriveUserId, requestContextStorage, } from './executor.js';
+import { droppedHeaderWarning, headerMetadata } from '../observability/metadata.js';
 import { HEADER_VALUE_PATTERN, SCOPE_KEY_PATTERN } from './identity.js';
+import { feedbackBodyParser, feedbackHandler, feedbackLimiter, isFeedbackPath } from './feedback.js';
 import { createMetrics } from '../observability/metrics.js';
 import { ConsentError } from '../tools/oauthConsent.js';
 import { setOAuthHosts } from '../tools/oauthHosts.js';
@@ -545,6 +549,7 @@ export async function createA2AApp(options) {
             agentId,
             policy: options.policy,
             onTaskEnd,
+            ...(options.onTaskState ? { onTaskState: options.onTaskState } : {}),
             onAudit: audit,
             log,
             warn,
@@ -716,7 +721,10 @@ export async function createA2AApp(options) {
         });
     }
     // ── 4. Body ────────────────────────────────────────────────────────────────
-    app.use(express.json({ limit: options.bodyLimit ?? '1mb' }));
+    // A POST to /feedback or /<id>/feedback parses at 32 KB, its errors as JSON (ADR 0140).
+    const jsonBody = express.json({ limit: options.bodyLimit ?? '1mb' });
+    const feedbackBody = feedbackBodyParser();
+    app.use((req, res, next) => (req.method === 'POST' && isFeedbackPath(req.path) ? feedbackBody(req, res, next) : jsonBody(req, res, next)));
     // ── 5. Caller context: who is calling, and whose data this is ──────────
     // Agent-card GETs need no caller context: discovery must not require a
     // model key or an identity.
@@ -764,6 +772,18 @@ export async function createA2AApp(options) {
             }
             surface[field] = raw;
         }
+        // X-Melch-Meta-*: per-request metadata, telemetry only (ADR 0141). Refused when malformed, as X-Surface is.
+        const metaHeaders = headerMetadata(req.headers);
+        if (metaHeaders.error) {
+            res.status(400).json({ error: metaHeaders.error });
+            return;
+        }
+        const meta = metaHeaders.meta;
+        // Warned about only once the caller is known: an anonymous request writes no log line.
+        const warnDroppedMeta = () => {
+            for (const key of metaHeaders.dropped ?? [])
+                warn(droppedHeaderWarning(key));
+        };
         // The adopter's identity system decides, when one is plugged in.
         if (options.resolveRequest) {
             let identity;
@@ -796,6 +816,7 @@ export async function createA2AApp(options) {
             }
             if (identity.apiKey && !identity.provider)
                 provider = 'google';
+            warnDroppedMeta();
             requestContextStorage.run({
                 apiKey,
                 provider,
@@ -804,7 +825,7 @@ export async function createA2AApp(options) {
                 caller: identity.caller,
                 ownsNested: identity.ownsNested ?? false,
                 operator: identity.operator ?? false,
-                sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent),
+                sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent), ...(meta ? { meta } : {}),
             }, () => next());
             return;
         }
@@ -829,7 +850,8 @@ export async function createA2AApp(options) {
             // The caller's key funds its provider, and its hash prefixes the scope
             // so no key holder can reach another's data.
             const scopeKey = deriveUserId({ apiKey, siteUserId });
-            requestContextStorage.run({ apiKey, provider, siteUserId, scopeKey, surface, caller: 'shared-secret', ownsNested: !siteUserId, operator: !!options.serverSecret, sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent) }, () => next());
+            warnDroppedMeta();
+            requestContextStorage.run({ apiKey, provider, siteUserId, scopeKey, surface, caller: 'shared-secret', ownsNested: !siteUserId, operator: !!options.serverSecret, sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent), ...(meta ? { meta } : {}) }, () => next());
             return;
         }
         // Server mode: the server's credentials pay; X-API-Key is not used.
@@ -837,6 +859,7 @@ export async function createA2AApp(options) {
             warnedIgnoredKey = true;
             warn('A caller sent X-API-Key, which server key mode ignores. Set A2A_KEY_MODE=byok (keyMode: \'byok\') if callers fund their own inference — and to keep reaching sessions and memory stored under key-hash silos.');
         }
+        warnDroppedMeta();
         requestContextStorage.run({
             apiKey: '',
             provider,
@@ -846,7 +869,7 @@ export async function createA2AApp(options) {
             // Everyone holding the secret is one caller; without a secret (loopback) the caller is local.
             caller: options.serverSecret ? 'shared-secret' : 'local',
             operator: !!options.serverSecret,
-            sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent),
+            sourceIp: req.ip, traceparent: validTraceparent(req.headers.traceparent), ...(meta ? { meta } : {}),
         }, () => next());
     });
     // ── 6. Task rate limit ────────────────────────────────────────────────────
@@ -933,6 +956,18 @@ export async function createA2AApp(options) {
     const served = options.servedAgents ? new Set(options.servedAgents) : undefined;
     class AgentNotFound extends Error {
     }
+    // End-user feedback (ADR 0140): behind the same authentication and task
+    // rate limit as a task, with its own body limit and per-turn limit.
+    const onFeedback = feedbackHandler({
+        store: options.storage?.feedback,
+        context: () => requestContextStorage.getStore(),
+        agentServed: (agentId) => isValidAgentId(agentId) && (!served || served.has(agentId)),
+        limiter: feedbackLimiter(),
+        log,
+        warn,
+    });
+    app.post('/feedback', onFeedback);
+    app.post('/:agentId/feedback', onFeedback);
     const loadAgentConfig = async (agentId) => {
         const registryId = agentId.startsWith('registry:') ? agentId.slice('registry:'.length) : registryIds.has(agentId) ? agentId : undefined;
         if (registryId) {

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

@@ -25,6 +25,7 @@ import type { ToolCredentials } from '../tools/oauthConsent.ts';
 import type { TaskRecord } from '../observability/metrics.ts';
 import type { AuditSink } from '../observability/audit.ts';
 import type { Policy } from './policy.ts';
+import type { Metadata } from '../observability/metadata.ts';
 /** Per-request caller context, set by the server's identity middleware. */
 export interface A2AContext {
     /** The caller's provider key in BYOK mode (or from resolveRequest); '' otherwise. */
@@ -54,6 +55,8 @@ export interface A2AContext {
     sourceIp?: string;
     /** The caller's W3C traceparent, when well formed: the turn's root span links to it. */
     traceparent?: string;
+    /** The request's `X-Melch-Meta-*` headers, checked (ADR 0141): `meta.<key>` on the turn's root span. Telemetry only. */
+    meta?: Metadata;
 }
 export interface SurfaceContext {
     name: string;
@@ -73,6 +76,28 @@ export declare const A2A_APP_NAME = "melchizedek-a2a";
 export declare function deriveUserId(ctx: Pick<A2AContext, 'apiKey' | 'siteUserId'>): string;
 /** Root-span attributes for the caller's surface (absent headers add none). */
 export declare function surfaceAttributes(ctx: A2AContext | undefined): Record<string, string>;
+/**
+ * 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 declare function requestMetaAttributes(ctx: Pick<A2AContext, 'meta'> | undefined, messageMetadata: unknown, config: Pick<SyndicateYamlConfig, 'metadata'>, warn?: (message: string) => void): Record<string, string | number | boolean>;
+/** The A2A task states, as the protocol spells them. */
+export type TaskStateName = 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled' | 'rejected' | 'auth-required' | 'unknown';
+/** One state a task entered, as the executor published it (A2AAppOptions.onTaskState). */
+export interface TaskStateRecord {
+    taskId: string;
+    contextId: string;
+    state: TaskStateName;
+    /** The syndicate's name, and the agent id the task was sent to (`default` for the one served at /a2a/*). */
+    syndicate: string;
+    agentId: string;
+    /** The turn's trace id, once its root span started (absent on `submitted`, and on a task refused before it ran). */
+    traceId?: string;
+    /** When the state was published, ms since the epoch. */
+    at: number;
+}
 /** 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
@@ -115,6 +140,8 @@ export interface ExecutorOptions {
     policy?: Policy;
     /** One record per task, however it ended: the task log and metrics. */
     onTaskEnd?: (record: TaskRecord) => void;
+    /** Every state the task enters, as it is published (ADR 0141). */
+    onTaskState?: (record: TaskStateRecord) => void;
     /** Receives one `task.end` audit event per task (ADR 0042). */
     onAudit?: AuditSink;
     /**
@@ -204,7 +231,7 @@ export declare class SyndicateExecutor implements AgentExecutor {
     constructor(opts: ExecutorOptions);
     /** Provenance stamp for every turn this executor serves (lineage.ts). */
     configHashFor(): string;
-    execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void>;
+    execute(requestContext: RequestContext, published: ExecutionEventBus): Promise<void>;
     /**
      * Aborts the task's run; `execute` then publishes the `canceled` status.
      * The SDK calls this only on the instance whose event bus carries the

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;