melchizedek-agents 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -4,7 +4,137 @@ Consumers of the package read this file; it records changes to the
 **published API surface** (the exports map in `package.json`, the bins,
 the starter pack and the templates), not the repo's full history.
 
-## Unreleased
+## 1.10.0 — 2026-10-20
+
+A minor release for deployments: a served syndicate takes end-user
+feedback at POST /feedback into the ledger (ADR 0140), budgets report
+their state and can stop on a caller's own rule, and the job queue has a
+read model with a retry.
+
+### Added
+
+- **End-user feedback, `POST /feedback` and `POST /<agentId>/feedback`
+  (ADR 0140).** A product's thumbs or 1–5 rating of a served turn, named by
+  its A2A `taskId` or its `traceId`, with an optional `comment` (≤ 4,000
+  characters) and `userId`, lands in the ledger as one `adk_labels` row:
+  `ref = trace_id = <trace id>`, `labeler = 'end-user'`,
+  `fields = { score, userId }`, `note` = the comment through the telemetry
+  redactor. Behind the bearer, the authenticator and the task rate limit,
+  with a 32 KB body limit, the caller's own turns only, and one label per
+  (turn, user) per minute. New option `storage.feedback`; `postgresStorage`
+  supplies it when `ledger` is on. New subpath
+  `melchizedek-agents/a2a/feedback` and barrel exports: `parseFeedback`,
+  `feedbackRow`, `postgresFeedbackStore`, `END_USER_LABELER`, types
+  `FeedbackStore`, `FeedbackRow`, `FeedbackScore`, `FeedbackTurn`.
+- **Budget hooks.** `budgets(config, opts)` takes `onBudgetState(state)`,
+  called with each subject's day totals, limits and level (`ok`, `warn`,
+  `over`) after every task and when a task arrives over a limit; `warnAt`
+  (default 0.8); and `hardStop`: `true` (default, as before), `false`
+  (limits only report), or a function returning a refusal reason, asked at
+  admission (a local server's own spend check). New types `BudgetState`,
+  `BudgetLevel`, `BudgetOptions`, `HardStop`.
+- **The job queue's read model.** Migration `0018_queue_view` adds the view
+  `melchizedek_task_queue`: one row per background job with `attempts`,
+  `retries`, `max_attempts`, `dead_lettered`, `last_error`, the lease and
+  the checkpoint. `postgresStorage().retryTask(owner, id)` queues a failed
+  or cancelled job again with its attempts reset (`applyRetry` in
+  `lib/tools/taskTools.ts`, the rule `task_update`'s `queued` applies).
+  The view is revoked from the API roles in the migration and in
+  `db/hardening.sql`.
+
+## 1.9.0 — 2026-10-20
+
+Not published on its own: these changes ship in 1.10.0.
+
+A minor release for observability: the ledger keeps a turn's span tree
+with cache tokens and their prices (ADR 0139), and a syndicate's YAML
+and an A2A request can label a turn with metadata, with a hook on every
+task state (ADR 0141).
+
+The ledger keeps a turn's span tree, counts prompt-cache tokens, and
+prices them at their own rates (ADR 0139). **Apply the schema before
+upgrading the engine:** `npx melchizedek-db apply --telemetry` runs the
+new migrations 0016 and 0017 and `db/telemetry.sql`; the sinks write the
+new columns, so a ledger without them refuses the rows (they are spooled
+to the dead-letter file, and `telemetry:replay` re-sends them once the
+schema is applied). Rows written before keep NULL in every new column.
+
+### Added
+
+- **The span tree in `adk_telemetry` (migration `0016_span_tree`).** Every
+  span of a turn gets a row: the root, `agent.invoke <name>`, `model.call`,
+  `llm.request`, `tool.execute <name>`, `script.invoke` / `script.call`,
+  `workflow.invoke` / `node.execute`. New columns `parent_span_id` (the
+  nearest ancestor that has a row, read from the tracer's lineage when the
+  span starts and recorded as `ledger.parent_span_id` where it differs
+  from the direct parent), `kind` (`turn | agent | model | tool | script |
+  node`) and `error`; index `idx_adk_telemetry_parent`. A `model.call` row
+  carries no tokens and no payload (its `llm.request` rows and
+  `adk_payloads` hold them). New exports on `./observability/*`:
+  `ledgerSpanKind`, `LedgerSpanKind`, `LEDGER_PARENT_ATTRIBUTE`
+  (`lineage`); `isLedgerSpan`, `ledgerParentOf`, `spanFailed`, and the
+  new `TelemetryRow` / `TurnRow` fields (`supabaseSpanExporter`).
+- **Tool arguments and results on tool spans.** `tool.args` and
+  `tool.result`, JSON, run through the telemetry redactor and then cut at
+  8,192 characters (`TOOL_ATTRIBUTE_MAX_CHARS`, with
+  `tool.args_truncated` / `tool.result_truncated`), on the loop's tool
+  calls and a tool node's. `OTEL_EXPORT_CONTENT=off` drops `tool.result`
+  as it drops `tool.args`.
+- **Cache tokens and finish reasons.** `llm.request` records
+  `llm.tokens.cache_read` and `llm.tokens.cache_write` (parts of
+  `llm.tokens.input`, set when the provider reports them) and
+  `llm.finish_reason`; `model.call` records `llm.finish_reason` too.
+  `adk_telemetry` and `adk_turns` gain `cache_read_tokens` and
+  `cache_write_tokens` (a turn's summed over its calls; the root span's
+  `syndicate.tokens.cache_read` / `.cache_write`), and `syndicate.usage`
+  carries `cache_read` / `cache_write` per model. `LlmCallMeta.source`
+  lets a caller of `traceLlmGeneration` hand the contract response each
+  `LlmResponse` came from, which is where a cache write is read.
+- **Cache pricing (migration `0017_cache_pricing`).** `model_pricing`
+  gains `cache_read_per_mtok` and `cache_write_per_mtok` (NULL prices the
+  token as input, so every existing row prices as before);
+  `melchizedek_cost_usd(model, input, output, thinking, cache_read,
+  cache_write)` prices them (the four-argument form stays);
+  `melchizedek_usage_cost` and the ledger trigger read them. Seeded from
+  the vendors' lists, checked 2026-10-20: the Anthropic rows 0015 seeded
+  gain their cache rates (5-minute write) while they still hold 0015's
+  rates, `claude-opus-5-5` and `claude-sonnet-5-5` are added, and OpenAI's
+  `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6-sol`, `gpt-6-luna`, `gpt-5.6-sol` /
+  `-terra` / `-luna`, `gpt-5.5`, `gpt-5.4` (under-272K rates), `gpt-5.2`,
+  `gpt-5.1`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano` get rows. Gemini, Grok and
+  Kimi rows get no cache rates.
+- **`metadata:` in the syndicate YAML (ADR 0141).** `{ key: value }` on
+  the syndicate and on any agent: strings (at most 256 characters),
+  numbers or booleans, at most 32 keys, each key
+  `[A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}`. The syndicate's become
+  `meta.<key>` on every root span of a turn, so on
+  `adk_turns.attributes`; an agent's become `meta.agent.<key>` on its
+  `agent.invoke` span. A value shaped like a key or token is dropped at
+  load with a warning (`LoadSyndicateOptions.onWarning`) naming the key,
+  never the value; string values pass through the telemetry redactor. An
+  attribute an in-process caller passes in `trace.attributes` wins a key
+  both name. `config/agents/syndicate.schema.json` is regenerated.
+- **Per-request metadata over A2A (ADR 0141).** `X-Melch-Meta-<key>`
+  headers and the scalar entries of the A2A message's `metadata` object
+  become `meta.<key>` on the turn's root span, with the YAML's limits and
+  redaction; at most 32 keys a turn, the YAML's first. A header wins a key
+  both name; a key the YAML declares, or one starting `agent.`, is never
+  taken from a request; a credential-shaped value is dropped with a
+  warning. A malformed `X-Melch-Meta-*` header is refused with 400; a
+  message entry that is not metadata is skipped. `A2AContext.meta` holds
+  the checked headers.
+- **`A2AAppOptions.onTaskState(record)` (ADR 0141).** Called after each
+  new state the executor publishes, with
+  `{ taskId, contextId, state, syndicate, agentId, traceId?, at }`:
+  `submitted`, `working` (with the first progress line), then the state
+  the task ends in. Barrel types `TaskStateRecord`, `TaskStateName`,
+  `Metadata`, `MetadataValue`; the helpers are in
+  `melchizedek-agents/observability/metadata`.
+
+### Docs
+
+- `tasks/get` and the states a polling caller reads, in DOCUMENTATION.md
+  §6 and the A2A wiki doc.
 
 ## 1.8.0 — 2026-10-18
 

package/DOCUMENTATION.md

@@ -126,6 +126,7 @@ Field reference:
 |---|---|---|
 | `syndicate_name` | root | Display name. On the CLI it also namespaces memory user keys; on the A2A server memory is keyed by the caller's silo across every long-term syndicate that server serves. |
 | `memory_system` | root | `internal-only` (nothing persists — on the server too: its transcripts stay in process memory), `session-only` (transcript persists in Supabase), `long-term` (adds fact distillation + vector recall). |
+| `metadata` | root, any agent | Static labels for the ledger ([ADR 0141](./wiki/decisions/0141-metadata-and-the-task-state-hook.md)): `{ key: value }` with string (at most 256 characters), number or boolean values, at most 32 keys, each key `[A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}`. The syndicate's become `meta.<key>` on every root span of a turn, so on its `adk_turns.attributes` (`meta.tags: "a,b"` gives the turn tags); an agent's become `meta.agent.<key>` on its `agent.invoke` span. A value shaped like a key or token is dropped at load with a warning naming the key; string values pass through the telemetry redactor. An A2A caller can add keys of its own (§6, Headers) but never set one named here. |
 | `variables` | root | Key/values bound into `{{placeholders}}` anywhere in instructions. `current_date` is always injected; CLI `--bind key=value` overrides. |
 | `memory_extraction_rules` | root | Domain rules appended to the shared fact-extraction prompt for THIS syndicate only (requires `memory_system: "long-term"`). The extraction prompt is global — anything domain-specific belongs here, never edited into it. Unset, the prompt renders byte-identical to before the slot existed (§4). |
 | `memory_extraction_model` | root | The model that distils this syndicate's turns into memory records (long-term only); any model id. Default: the deployment's `MEMORY_EXTRACTION_MODEL`. |
@@ -192,7 +193,7 @@ function, and every adapter recognises it by marker
 | `inspect_image` | Contract | **Blind visual inventory** of a file under `outputs/`: subjects with exact counts, composition, light, palette, medium cues, artifacts — zero quality judgments. Its signature accepts *only* a file path, so an orchestrator cannot leak expectations into the observation (see `image_production.yaml`). |
 | `task_add` / `task_list` / `task_get` / `task_update` | Contract | A to-do list and job queue. Default: a single-user JSON file (`MELCHIZEDEK_TASKS_FILE`, default `outputs/tasks.json`), so every caller of a shared endpoint shares one list. With `DATABASE_URL` (migration 0009) each caller has its own list, scoped by the caller's scope key, and any number of workers take jobs safely. |
 | `ask_user` | Contract, long-running | Asks the person one question (optionally with `options`) and ends the turn `input-required`; the next message on the conversation is the call's result. Any agent but a workflow node's; inside a delegated subagent the question reaches the person with the agent path (§6, Questions). |
-| `task_queue` | Contract | Queues a background job (a self-contained instruction). The tool only writes the queue; `npm run assistant:worker` (`melchizedek-worker`) claims each job, runs it through one agent compiled from YAML (default: the Assistant's Worker), and writes the result back for `task_get`. `--once` drains and exits, for cron. A run is durable (ADR 0113): it is checkpointed beside the job at every step boundary (migration 0014 on Postgres), a job claimed again resumes from its last checkpoint (inside a dispatch route too, ADR 0121), a checkpoint above `MELCHIZEDEK_CHECKPOINT_MAX_BYTES` (default 5 MiB of JSON; `TaskBackendOptions.checkpointMaxBytes`, `postgresStorage({ taskQueue })`) is skipped and the previous one kept, SIGTERM re-queues the job in hand, and `task_update` can cancel a running job. |
+| `task_queue` | Contract | Queues a background job (a self-contained instruction). The tool only writes the queue; `npm run assistant:worker` (`melchizedek-worker`) claims each job, runs it through one agent compiled from YAML (default: the Assistant's Worker), and writes the result back for `task_get`. `--once` drains and exits, for cron. A run is durable (ADR 0113): it is checkpointed beside the job at every step boundary (migration 0014 on Postgres), a job claimed again resumes from its last checkpoint (inside a dispatch route too, ADR 0121), a checkpoint above `MELCHIZEDEK_CHECKPOINT_MAX_BYTES` (default 5 MiB of JSON; `TaskBackendOptions.checkpointMaxBytes`, `postgresStorage({ taskQueue })`) is skipped and the previous one kept, SIGTERM re-queues the job in hand, and `task_update` can cancel a running job. On Postgres the view `melchizedek_task_queue` (migration 0018) lists every job with `attempts`, `retries`, `dead_lettered`, `last_error`, its lease and checkpoint, and `postgresStorage().retryTask(owner, id)` queues a failed or cancelled job again. |
 
 **MCP tools** are the exception to the registry: a subagent with
 `mcp_server_url:` (or several servers under `mcp_servers:`) in its YAML
@@ -626,8 +627,14 @@ row per turn with input, output, the responding agent, the plan-dispatch
 route, errors, tokens, model-vs-tool latency, the tool calls with their
 responses, the ids that join it to `adk_sessions` (`session_id`,
 `invocation_id`), provenance (`config_hash`, `engine_version`) and a
-full-text `search` column; `adk_telemetry` — one row per `llm.request` /
-root span; and `adk_payloads` — full prompts and responses per model call,
+full-text `search` column; `adk_telemetry` — one row per span of the
+turn's tree (the root, `agent.invoke`, `model.call`, `llm.request`,
+`tool.execute`, script and workflow spans), each with `parent_span_id`
+(the nearest ancestor that has a row), `kind` (`turn | agent | model |
+tool | script | node`) and `error` (migration 0016, ADR 0139); a tool
+span carries `tool.args` and `tool.result` (redacted, then cut at 8 KB),
+and tokens sit on the `llm.request` rows and the root, never on a
+`model.call` row; and `adk_payloads` — full prompts and responses per model call,
 kept by policy (`TELEMETRY_PAYLOADS=off|errors|sample|all`,
 `TELEMETRY_PAYLOAD_SAMPLE`, `TELEMETRY_PAYLOAD_TTL_DAYS`) and expired by
 `melchizedek_prune_telemetry()`. A row from a failed call's `llm.request`
@@ -648,6 +655,14 @@ input summed per call), thinking at the output rate unless the row sets
 never a partial sum; `ollama/*` costs zero. Add or change a rate with an
 `INSERT … ON CONFLICT (model) DO UPDATE` on `model_pricing`; rows already
 written keep the rate in force when they were written (ADR 0136).
+Prompt-cache tokens are parts of the input: each `llm.request` records
+`llm.tokens.cache_read` / `llm.tokens.cache_write` (and
+`llm.finish_reason`), `adk_telemetry` and `adk_turns` carry
+`cache_read_tokens` / `cache_write_tokens` (the turn's summed over its
+calls), and `syndicate.usage` carries `cache_read` / `cache_write` per
+model. `model_pricing.cache_read_per_mtok` / `cache_write_per_mtok` price
+them (migration 0017; NULL prices them as input), seeded for Anthropic and
+OpenAI from their price lists (ADR 0139).
 Operate it with `npm run telemetry:stats`,
 `telemetry:prune` and `telemetry:replay` (the exporter spools failed
 batches to `outputs/telemetry-deadletter.ndjson`).
@@ -700,6 +715,7 @@ README has the commands.
 | `GET /<agentId>/.well-known/agent-card.json` | bearer | another syndicate's card; its URLs point at `/<agentId>/a2a/...` |
 | `POST /<agentId>/a2a/jsonrpc`, `/<agentId>/a2a/rest` | bearer | another syndicate (`A2A_SERVED_AGENTS` restricts which) |
 | `DELETE /memory` | bearer | erase everything stored for the calling scope: facts, sessions (with subagent rows), ledger rows, A2A tasks and the third-party tokens held for its tools, including conversations whose sessions have expired, with per-store counts; `?all=1` covers every memory namespace |
+| `POST /feedback`, `/<agentId>/feedback` | bearer | an end user's rating of a turn (ADR 0140): `{ "taskId" or "traceId", "score": "up" \| "down" \| 1–5, "comment"?, "userId"? }` → `201 { ok, traceId }`; one `adk_labels` row (below). 501 without the ledger |
 
 "bearer" means the credential `A2A_AUTH` asks for (below); with no
 `A2A_SERVER_SECRET` and no authenticator the server binds `127.0.0.1` only.
@@ -745,6 +761,38 @@ or pass your own `resolveRequest`.
   The counts live in the `melchizedek_usage` table (`db/migrations/0004_usage.sql`)
   when Postgres or Supabase is configured, else in process memory. A store
   that cannot be read refuses the task.
+  `budgets(config, { onBudgetState, warnAt, hardStop })` adds two hooks.
+  `onBudgetState(state)` is called with each subject's standing after every
+  task (`cause: 'record'`) and when a task arrives over a limit
+  (`cause: 'admit'`, `stopped` saying whether it was refused):
+  `{ subject: 'caller:<name>' | 'scope:<hash>', day, usage, limits?,
+  level: 'ok' | 'warn' | 'over', reached?, agentId }`, `warn` from `warnAt`
+  (default 0.8) of any limit, so a consumer can mirror a deployment's
+  spend. `hardStop: false` makes the limits advisory (reported, not
+  enforced); a function `(subject) => reason | undefined` is an outside
+  stop asked at admission after the limits, whose reason refuses the task
+  (a desktop app serving locally passes its monthly spend check, with
+  `budgets({}, { hardStop })`). It may throw; that refuses too.
+- **End-user feedback** (`POST /feedback`, `lib/a2a/feedback.ts`, ADR 0140):
+  a product's thumbs or 1–5 rating of a turn, named by its A2A `taskId` (a
+  dispatch task's answer, not its classifier turn) or its `traceId`, with an
+  optional `comment` (at most 4,000 characters) and the product's own
+  `userId` ([A-Za-z0-9._@:+/-], at most 128; a credential-shaped one is
+  refused). It writes one `adk_labels` row: `ref` and `trace_id` the turn's
+  trace id, `labeler = 'end-user'`, `fields = { score, userId }` (`score`
+  the string or the number as sent, `userId` null when none), `note` the
+  comment through the telemetry redactor (`TELEMETRY_REDACT`), null when
+  none. The route is behind the bearer, the authenticator and the task rate
+  limit like a task, with its own 32 KB body limit. A caller rates only
+  turns whose `user_id` is its scope (or beneath a scope that owns nested
+  ones) unless it holds an operator credential; another's turn answers the
+  same 404 as a missing one, and a turn reaches the ledger a few seconds
+  after it ends. One label per turn per `userId` (else per scope) per
+  minute, per process: 429 with `Retry-After`. Answers never repeat what
+  was sent. It needs the ledger in Postgres: `postgresStorage({ ledger:
+  true })` supplies `storage.feedback`, and `postgresFeedbackStore(pool)`
+  builds one on any pool with `db/telemetry.sql` applied; the supabase-js
+  path has none.
 - **One record per task** (option `onTaskEnd`): task id, trace id, agent,
   caller, a hash of the scope, status, reason, duration, model calls and
   tokens. The trace id is the one the turn's spans and its ledger row carry,
@@ -755,6 +803,14 @@ or pass your own `resolveRequest`.
   record carries `callerTraceId`. The turn keeps a trace id of its own, since
   ledger attribution and erasure key on it and a caller must not choose it.
   `A2A_LOG_FORMAT=json` prints every server line as JSON, this record included.
+- **Every state a task enters** (option `onTaskState`): `{ taskId, contextId,
+  state, syndicate, agentId, traceId?, at }` after each new state the server
+  publishes: `submitted`, `working` (with the first progress line), then
+  `completed`, `failed`, `canceled`, `rejected` or `input-required`. A repeat
+  of the state is not reported again; `traceId` is there once the turn's root
+  span started; `at` is ms since the epoch; a throwing hook is ignored. For a
+  live view of work in flight. A caller polling instead reads the same state
+  with `tasks/get` (below).
 - **The audit trail** (`melchizedek_audit`, `db/migrations/0012_audit_log.sql`;
   option `audit`, supplied by `postgresStorage`): one row per failed
   authentication (`auth.failure`), task outcome (`task.end`), erasure
@@ -825,6 +881,7 @@ sending it regulated data.
 | `X-API-Key` | BYOK mode only: the caller's model key (see above) |
 | `X-Provider` | BYOK mode only: which provider `X-API-Key` belongs to (default `google`) |
 | `X-Surface`, `X-Surface-Guild`, `-Channel`, `-User` | optional, telemetry only |
+| `X-Melch-Meta-<key>` | optional, telemetry only: `meta.<key>` (the key lowercased) on the turn's root span, with the limits of the YAML's `metadata:`. A header outside them is refused with 400. The A2A message's own `metadata` object adds its scalar entries the same way (a header wins a key both name; other entries are skipped). At most 32 keys a turn, the YAML's first; a key the YAML declares, or one starting `agent.`, is never taken from a request; a credential-shaped value is dropped ([ADR 0141](./wiki/decisions/0141-metadata-and-the-task-state-hook.md)). |
 
 #### Sessions
 
@@ -840,7 +897,12 @@ transcripts in process memory even when Supabase is configured.
 (Method names below are 0.3's; 1.0 clients use `SendMessage`,
 `GetTask`, `SendStreamingMessage`, `CancelTask` and the 1.0 enum spellings.)
 `message/send` blocks until the turn finishes unless the request sets
-`configuration.blocking: false`; then poll `tasks/get`. `message/stream`
+`configuration.blocking: false`; then poll `tasks/get` with the returned
+task id (`{"jsonrpc":"2.0","id":2,"method":"tasks/get","params":{"id":"<task id>"}}`):
+`result.status.state` is `submitted`, `working`, `input-required` (an
+approval, a question or a consent waits; the status message says which),
+`completed`, `failed`, `canceled` or `rejected`, and once it is final,
+`result.status.message` carries the answer or the reason. `message/stream`
 emits `[STATUS]` progress updates (tool calls, the chosen route, guard
 notes) and the answer as the final status message. With
 `A2A_STREAM_TEXT=true` (`streamText` in code) it also streams the answer as

package/README.md

@@ -106,6 +106,8 @@ console.log(result.status, result.text);
 
 `runSyndicateTurn` is the same runtime the server, CLI, and eval harness use. It runs every syndicate on the engine's own agent loop and, for a workflow, its own scheduler (the `native` runtime, the only one). `MELCHIZEDEK_RUNTIME=adk` is an error that names 1.0.0; `npx melchizedek-doctor` prints the runtime in use (ADR 0107). To read syndicates from somewhere else, pass `loadSyndicate(file, { agentsDir })` or set `MELCHIZEDEK_AGENTS_DIR`. To serve inside your own Express app, mount `(await createA2AApp({ defaultSyndicate: 'mine.yaml', serverSecret })).app`. `events.onEvent` and `events.onTextDelta` follow the answering agent; `events.onAgentEvent(event, branch)` follows every delegated subagent live, its thinking, text and tool calls, with `branch.path` and `branch.callId` saying where it runs (ADR 0135).
 
+A served syndicate also takes end-user ratings at `POST /feedback` (`{ traceId | taskId, score: 'up' | 'down' | 1–5, comment?, userId? }`, into the ledger's `adk_labels`; `melchizedek-agents/a2a/feedback`, ADR 0140), and `budgets(config, { onBudgetState, hardStop })` from `melchizedek-agents/a2a/policy` mirrors each caller's spend and takes an outside stop. On Postgres, `melchizedek_task_queue` (migration 0018) is the job queue's read model and `postgresStorage().retryTask(owner, id)` its Retry.
+
 The example syndicates ship inside the package at `node_modules/melchizedek-agents/config/agents/examples/`; copy one out as a starting point.
 
 ### Custom Tools and Guards

package/config/agents/syndicate.schema.json

@@ -1028,6 +1028,29 @@
             }
           },
           "additionalProperties": false
+        },
+        "metadata": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}$"
+          },
+          "additionalProperties": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 256
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              }
+            ]
+          },
+          "description": "Labels for the ledger: strings (at most 256 characters), numbers or booleans, at most 32 keys. Each becomes `meta.agent.<key>` on this agent's agent.invoke span. A value shaped like a key or token is dropped at load with a warning; string values pass through the telemetry redactor (ADR 0141).",
+          "maxProperties": 32
         }
       },
       "required": [
@@ -2064,6 +2087,29 @@
             },
             "additionalProperties": false
           },
+          "metadata": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}$"
+            },
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "string",
+                  "maxLength": 256
+                },
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "boolean"
+                }
+              ]
+            },
+            "description": "Labels for the ledger: strings (at most 256 characters), numbers or booleans, at most 32 keys. Each becomes `meta.agent.<key>` on this agent's agent.invoke span. A value shaped like a key or token is dropped at load with a warning; string values pass through the telemetry redactor (ADR 0141).",
+            "maxProperties": 32
+          },
           "yaml_reference": {
             "description": "A whole nested syndicate (filename under the agents dir) used as this subagent. An approval request or ask_user question raised inside it pauses the turn with the agent path (ADR 0110, ADR 0111): a delegate syndicate's gates anywhere, a dispatch syndicate's on its routes, which it classifies and runs as at the top, its route's answer being its own (ADR 0120), and a workflow's ask_user nodes and gates, wherever each runs: delegated to as a subagent, as a dispatch route or as a workflow node (ADR 0119).",
             "type": "string",
@@ -2384,6 +2430,29 @@
       },
       "additionalProperties": false
     },
+    "metadata": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}$"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string",
+            "maxLength": 256
+          },
+          {
+            "type": "number"
+          },
+          {
+            "type": "boolean"
+          }
+        ]
+      },
+      "description": "Labels for the ledger: strings (at most 256 characters), numbers or booleans, at most 32 keys. Each becomes `meta.<key>` on every turn's root span, so on the ledger row (adk_turns.attributes); a key the YAML names cannot be set by an A2A caller. A value shaped like a key or token is dropped at load with a warning; string values pass through the telemetry redactor (ADR 0141).",
+      "maxProperties": 32
+    },
     "variables": {
       "description": "Defaults for {{token}} interpolation. {{current_date}} is built in.",
       "type": "object",

package/config/agents/syndicateSchema.yaml

@@ -53,6 +53,18 @@ syndicate_name: "My Syndicate"
 variables:
   my_variable: "default_value"
 
+# [optional] Static labels for the ledger (ADR 0141): each becomes
+# `meta.<key>` on the turn's root span, so on its adk_turns row; `tags`
+# (comma-separated) gives the turn tags. Strings (at most 256 characters),
+# numbers or booleans; keys [A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}; at most 32.
+# ⚠ A value shaped like a key or token is dropped at load with a warning.
+# An A2A caller's own metadata (X-Melch-Meta-*, Message.metadata) never
+# overrides a key named here.
+# metadata:
+#   environment: "prod"
+#   team: "growth"
+#   tags: "nightly,eu"
+
 # [optional] Self-correction, ON by default: the engine's reflect-and-retry,
 # ported from ADK's plugins (ADR 0034, ADR 0075). model_errors: retries of a model
 # reply the engine marks malformed (default 2). tool_errors: retries of a tool that threw, with
@@ -323,6 +335,11 @@ orchestrator:
   # stderr are each cut at 20,000 characters, with a line saying so.
   # Maps to: tools[] (a toolset) and instruction (the appended index)
 
+  # [optional] Labels for this agent's agent.invoke span, each as
+  # `meta.agent.<key>`; the same rules as the syndicate's metadata.
+  # metadata:
+  #   role: "researcher"
+
   # [optional] Few-shot exchanges the engine adds to every request's
   # instruction (lib/tools/examples.ts), in the block ADK's ExampleTool
   # wrote; the model never calls it.

package/db/hardening.sql

@@ -84,7 +84,9 @@ BEGIN
   END LOOP;
   -- The production view and the retention function read/delete those
   -- tables on behalf of the caller; neither belongs on the public API.
-  FOREACH t IN ARRAY ARRAY['adk_turns_production', 'adk_kpi_daily', 'adk_kpi_routes_daily', 'adk_kpi_judges_daily', 'adk_kpi_hourly'] LOOP
+  -- So does the job queue's read model (migration 0018).
+  FOREACH t IN ARRAY ARRAY['adk_turns_production', 'adk_kpi_daily', 'adk_kpi_routes_daily', 'adk_kpi_judges_daily', 'adk_kpi_hourly',
+                            'melchizedek_task_queue'] LOOP
     IF to_regclass('public.' || t) IS NOT NULL THEN
       PERFORM pg_temp.melchizedek_revoke_api(format('%I', t));
     END IF;

package/db/migrations/0016_span_tree.sql

@@ -0,0 +1,52 @@
+-- ============================================================================
+-- 0016_span_tree — the ledger keeps a turn's span tree and its cache tokens
+--                  (ADR 0139)
+-- ============================================================================
+-- adk_telemetry holds one row per span the ledger keeps: the turn's root,
+-- each agent run, model step and provider call, tool call, script run and
+-- call, workflow walk and node run (lib/observability/lineage.ts
+-- ledgerSpanKind). Each row now says where it sits:
+--   parent_span_id  the nearest ancestor span the ledger keeps a row for;
+--                   NULL for a root, and for every row written before 0016
+--   kind            turn | agent | model | tool | script | node; NULL for a
+--                   row written before 0016
+--   error           the span failed (an error status or code, a tool's error
+--                   response); NULL for a row written before 0016
+-- The full span (attributes, events, status) stays in `span`.
+--
+-- Cache tokens, the parts of input_tokens a provider read from or wrote to
+-- its prompt cache (lib/models/contract.ts Usage), priced at their own rates
+-- by 0017_cache_pricing:
+--   adk_telemetry.cache_read_tokens / cache_write_tokens  one call's (an
+--       llm.request row), or the turn's sum (a root row)
+--   adk_turns.cache_read_tokens / cache_write_tokens      summed over every
+--       call of the turn, as a provider bills them
+-- NULL where nothing was reported, and on every row written before 0016.
+--
+-- The ledger tables are optional: db/telemetry.sql creates them, after the
+-- migrations, and adds the same columns for a fresh install. This migration
+-- upgrades a ledger that already exists in place, and does nothing where
+-- there is none. Numbers and span ids only: nothing personal, nothing secret.
+-- Idempotent; safe to re-run.
+-- ============================================================================
+
+DO $span_tree$
+BEGIN
+  IF to_regclass('public.adk_telemetry') IS NOT NULL THEN
+    EXECUTE 'ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS parent_span_id     TEXT';
+    EXECUTE 'ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS kind               TEXT';
+    EXECUTE 'ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS error              BOOLEAN';
+    EXECUTE 'ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS cache_read_tokens  INTEGER';
+    EXECUTE 'ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS cache_write_tokens INTEGER';
+    EXECUTE 'CREATE INDEX IF NOT EXISTS idx_adk_telemetry_parent ON adk_telemetry (trace_id, parent_span_id)';
+  END IF;
+  IF to_regclass('public.adk_turns') IS NOT NULL THEN
+    EXECUTE 'ALTER TABLE adk_turns ADD COLUMN IF NOT EXISTS cache_read_tokens  INTEGER';
+    EXECUTE 'ALTER TABLE adk_turns ADD COLUMN IF NOT EXISTS cache_write_tokens INTEGER';
+  END IF;
+END
+$span_tree$;
+
+INSERT INTO melchizedek_schema_version (version, name)
+VALUES (16, '0016_span_tree')
+ON CONFLICT (version) DO NOTHING;

package/db/migrations/0017_cache_pricing.sql

@@ -0,0 +1,146 @@
+-- ============================================================================
+-- 0017_cache_pricing — prompt-cache reads and writes at their own rates
+--                      (ADR 0139, extends ADR 0136)
+-- ============================================================================
+-- model_pricing gains two rates, USD per million tokens:
+--   cache_read_per_mtok   a token read from the provider's prompt cache
+--   cache_write_per_mtok  a token written to it (Anthropic's 5-minute cache,
+--                         the TTL the engine's requests get; OpenAI's 30-minute
+--                         write where its price list names one)
+-- NULL prices that token as input, which is what every row meant before:
+-- a cache token is an input token (lib/models/contract.ts Usage counts both
+-- inside inputTokens), so a row without cache rates prices exactly as 0015.
+--
+-- The cost functions take the two counts:
+--   melchizedek_cost_usd(model, input, output, thinking, cache_read, cache_write)
+--       input less both cache counts at the input rate, each cache count at
+--       its rate, output, thinking at the thinking rate (else output's)
+--   melchizedek_cost_usd(model, input, output, thinking)  the same with no
+--       cache tokens, kept for a caller written against 0015
+--   melchizedek_usage_cost(usage)  reads each model's cache_read and
+--       cache_write beside input, output and thinking in syndicate.usage;
+--       melchizedek_usage_text_cost (db/telemetry.sql) calls it, so the
+--       ledger trigger prices a turn's cache tokens too.
+--
+-- The seed: rates checked against the vendors' own price lists on
+-- 2026-10-20 (platform.claude.com/docs/en/about-claude/pricing and
+-- developers.openai.com/api/docs/pricing, standard tier), with verified_at
+-- set to that day. An Anthropic row 0015 seeded gains its cache rates only
+-- while it still holds 0015's input and output rates and no cache rate: an
+-- operator's own rates are never overwritten. New rows never overwrite a
+-- row that exists. Models the engine names but the lists price by prompt
+-- length beyond a flat row (claude-haiku-5-5, gpt-5.5 and gpt-5.4 over
+-- 272K) are left as noted below. Gemini, Grok and Kimi rows get no cache
+-- rates here (none was checked): their cache tokens price as input.
+--
+-- Nothing secret, nothing personal. Idempotent; safe to re-run.
+-- ============================================================================
+
+ALTER TABLE model_pricing ADD COLUMN IF NOT EXISTS cache_read_per_mtok  NUMERIC CHECK (cache_read_per_mtok >= 0);
+ALTER TABLE model_pricing ADD COLUMN IF NOT EXISTS cache_write_per_mtok NUMERIC CHECK (cache_write_per_mtok >= 0);
+
+-- Anthropic: the rows 0015 seeded, at the rates it seeded them.
+UPDATE model_pricing p
+SET cache_read_per_mtok  = s.cache_read,
+    cache_write_per_mtok = s.cache_write,
+    verified_at = '2026-10-20',
+    source = 'platform.claude.com/docs/en/about-claude/pricing',
+    note = 'Anthropic first-party, checked 2026-10-20; cache write is the 5-minute rate',
+    updated_at = now()
+FROM (VALUES
+  ('claude-fable-5-1',  10.00, 50.00, 0.25, 12.50),
+  ('claude-fable-5',    10.00, 50.00, 1.00, 12.50),
+  ('claude-opus-5',      5.00, 25.00, 0.50,  6.25),
+  ('claude-opus-4-8',    5.00, 25.00, 0.50,  6.25),
+  ('claude-opus-4-7',    5.00, 25.00, 0.50,  6.25),
+  ('claude-opus-4-6',    5.00, 25.00, 0.50,  6.25),
+  ('claude-sonnet-5',    2.00, 10.00, 0.20,  2.50),
+  ('claude-sonnet-4-6',  3.00, 15.00, 0.30,  3.75),
+  ('claude-haiku-4-5',   1.00,  5.00, 0.10,  1.25)
+) AS s(model, input, output, cache_read, cache_write)
+WHERE p.model = s.model
+  AND p.input_per_mtok = s.input
+  AND p.output_per_mtok = s.output
+  AND p.cache_read_per_mtok IS NULL
+  AND p.cache_write_per_mtok IS NULL;
+
+INSERT INTO model_pricing (model, input_per_mtok, output_per_mtok, cache_read_per_mtok, cache_write_per_mtok, verified_at, source, note) VALUES
+  -- Anthropic models 0015 did not seed. claude-haiku-5-5 is left out: its
+  -- price doubles past a 100K-token prompt, which a flat row cannot say.
+  ('claude-opus-5-5',    4.00, 20.00, 0.20, 5.00, '2026-10-20', 'platform.claude.com/docs/en/about-claude/pricing', 'Anthropic first-party, checked 2026-10-20; cache write is the 5-minute rate'),
+  ('claude-sonnet-5-5',  2.00, 10.00, 0.10, 2.50, '2026-10-20', 'platform.claude.com/docs/en/about-claude/pricing', 'Anthropic first-party, checked 2026-10-20; cache write is the 5-minute rate'),
+  -- OpenAI, standard tier. Reasoning tokens bill as output (thinking NULL).
+  -- A NULL cache write: the list names no write rate, so a write prices as input.
+  ('gpt-6-astra',       10.00, 50.00, 1.00,  12.50, '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20; cache write is the 30-minute rate'),
+  ('gpt-6.1-sol',        2.00, 10.00, 0.10,  2.50,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20; cache write is the 30-minute rate'),
+  ('gpt-6-sol',          2.00, 10.00, 0.20,  2.50,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20; cache write is the 30-minute rate'),
+  ('gpt-6-luna',         0.10,  0.50, 0.01,  0.125, '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20; cache write is the 30-minute rate'),
+  ('gpt-5.6-sol',        4.00, 20.00, 0.40,  5.00,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20; cache write is the 30-minute rate'),
+  ('gpt-5.6-terra',      2.00, 12.00, 0.20,  2.50,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20; cache write is the 30-minute rate'),
+  ('gpt-5.6-luna',       0.20,  1.20, 0.02,  0.25,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20; cache write is the 30-minute rate'),
+  ('gpt-5.5',            5.00, 30.00, 0.50,  NULL,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20; the rate for prompts under 272K tokens'),
+  ('gpt-5.4',            2.50, 15.00, 0.25,  NULL,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20; the rate for prompts under 272K tokens'),
+  ('gpt-5.2',            1.75, 14.00, 0.175, NULL,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20'),
+  ('gpt-5.1',            1.25, 10.00, 0.125, NULL,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20'),
+  ('gpt-5',              1.25, 10.00, 0.125, NULL,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20'),
+  ('gpt-5-mini',         0.25,  2.00, 0.025, NULL,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20'),
+  ('gpt-5-nano',         0.05,  0.40, 0.005, NULL,  '2026-10-20', 'developers.openai.com/api/docs/pricing', 'OpenAI standard tier, checked 2026-10-20')
+ON CONFLICT (model) DO NOTHING;
+
+-- The row that prices `model`: its own, else its prefix's `<prefix>/*`.
+CREATE OR REPLACE FUNCTION melchizedek_cost_usd(model TEXT, input BIGINT, output BIGINT, thinking BIGINT, cache_read BIGINT, cache_write BIGINT)
+RETURNS NUMERIC
+LANGUAGE sql
+STABLE
+SET search_path = public
+AS $$
+  SELECT (greatest(coalesce(input, 0) - coalesce(cache_read, 0) - coalesce(cache_write, 0), 0) * p.input_per_mtok
+          + coalesce(cache_read, 0) * coalesce(p.cache_read_per_mtok, p.input_per_mtok)
+          + coalesce(cache_write, 0) * coalesce(p.cache_write_per_mtok, p.input_per_mtok)
+          + coalesce(output, 0) * p.output_per_mtok
+          + coalesce(thinking, 0) * coalesce(p.thinking_per_mtok, p.output_per_mtok)) / 1000000
+  FROM model_pricing p
+  WHERE p.model = melchizedek_cost_usd.model
+     OR (position('/' IN melchizedek_cost_usd.model) > 0
+         AND p.model = split_part(melchizedek_cost_usd.model, '/', 1) || '/*')
+  ORDER BY (p.model = melchizedek_cost_usd.model) DESC
+  LIMIT 1
+$$;
+
+CREATE OR REPLACE FUNCTION melchizedek_cost_usd(model TEXT, input BIGINT, output BIGINT, thinking BIGINT)
+RETURNS NUMERIC
+LANGUAGE sql
+STABLE
+SET search_path = public
+AS $$
+  SELECT melchizedek_cost_usd(model, input, output, thinking, 0::bigint, 0::bigint)
+$$;
+
+CREATE OR REPLACE FUNCTION melchizedek_usage_cost(usage JSONB)
+RETURNS NUMERIC
+LANGUAGE sql
+STABLE
+SET search_path = public
+AS $$
+  SELECT CASE
+    WHEN usage IS NULL OR jsonb_typeof(usage) <> 'object' THEN NULL
+    -- bool_and over no rows is NULL: a turn that made no model call costs nothing.
+    WHEN coalesce(bool_and(c.cost IS NOT NULL), true) THEN coalesce(sum(c.cost), 0)
+    ELSE NULL
+  END
+  FROM (
+    SELECT melchizedek_cost_usd(
+             e.key,
+             CASE WHEN jsonb_typeof(e.value->'input') = 'number' THEN (e.value->>'input')::numeric::bigint END,
+             CASE WHEN jsonb_typeof(e.value->'output') = 'number' THEN (e.value->>'output')::numeric::bigint END,
+             CASE WHEN jsonb_typeof(e.value->'thinking') = 'number' THEN (e.value->>'thinking')::numeric::bigint END,
+             CASE WHEN jsonb_typeof(e.value->'cache_read') = 'number' THEN (e.value->>'cache_read')::numeric::bigint END,
+             CASE WHEN jsonb_typeof(e.value->'cache_write') = 'number' THEN (e.value->>'cache_write')::numeric::bigint END
+           ) AS cost
+    FROM jsonb_each(CASE WHEN jsonb_typeof(usage) = 'object' THEN usage ELSE '{}'::jsonb END) e
+  ) c
+$$;
+
+INSERT INTO melchizedek_schema_version (version, name)
+VALUES (17, '0017_cache_pricing')
+ON CONFLICT (version) DO NOTHING;